diff --git a/doc/contributing_ics.md b/doc/contributing_ics.md index c95ac4b2..76b7fb43 100644 --- a/doc/contributing_ics.md +++ b/doc/contributing_ics.md @@ -32,7 +32,7 @@ test_cases: TEST_CASES | title | String | Title of the service provider. Used as link title in README.md and info.md. | | url | String | Service provider homepage URL. The idea is to help users to identify their service provider if they search for an URL instead of a service provider name. The abbreviated domain name is therefore displayed next to the source title in README.md. | | country | String | [Optional] Overwrite default country code which is derived from yaml file name. | -| howto | String | A multi-line string in markdown format which describes the steps to configure the ICS source. | +| howto | Dictionary[String, String] | Adictionary of `language`: A multi-line string in markdown format which describes the steps to configure the ICS source. | | test_cases | Dict | A dictionary with test-cases. The key of an entry represents the name of the test-case which will be displayed during testing. The item contains a dictionary of the source arguments. | Example: @@ -121,3 +121,7 @@ To use it: 2023-07-12 : Altpapier ... ``` + +### Test before submitting using pytest + +To ensure that the source script is working as expected, it is recommended to install and run `pytest` in the `waste_collection_schedule` directory. This will run some additional tests making sure attributes are set correctly and all required files are present and update_docu_links run successfully. Pytest does not test the source script itself. diff --git a/doc/contributing_source.md b/doc/contributing_source.md index 7ba137b9..d62a025f 100644 --- a/doc/contributing_source.md +++ b/doc/contributing_source.md @@ -39,18 +39,59 @@ ICON_MAP = { # Optional: Dict of waste types and suitable mdi icons "ORGANIC": "mdi:leaf", } +#### Arguments affecting the configuration GUI #### + +HOW_TO_GET_ARGUMENTS_DESCRIPTION = { # Optional dictionary to describe how to get the arguments, will be shown in the GUI configuration form above the input fields, does not need to be translated in all languages + "en": "HOW TO GET ARGUMENTS DESCRIPTION", + "de": "WIE MAN DIE ARGUMENTE ERHÄLT", + "it": "COME OTTENERE GLI ARGOMENTI", +} + +PARAM_DESCRIPTIONS = { # Optional dict to describe the arguments, will be shown in the GUI configuration below the respective input field + "en": { + "arg1": "Description of ARG1", + "arg2": "Description of ARG2", + }, + "de": { + "arg1": "Beschreibung von ARG1", + "arg2": "Beschreibung von ARG2", + }, + "it": { + "arg1": "Descrizione di ARG1", + "arg2": "Descrizione di ARG2", + }, +} + +PARAM_TRANSLATIONS = { # Optional dict to translate the arguments, will be shown in the GUI configuration form as placeholder text + "en": { + "arg1": "User Readable Name for ARG1", + "arg2": "User Readable Name for ARG2", + }, + "de": { + "arg1": "Benutzerfreundlicher Name für ARG1", + "arg2": "Benutzerfreundlicher Name für ARG2", + }, + "it": { + "arg1": "Nome leggibile dall'utente per ARG1", + "arg2": "Nome leggibile dall'utente per ARG2", + }, +} + +#### End of arguments affecting the configuration GUI #### class Source: - def __init__(self, arg1, arg2): # argX correspond to the args dict in the source configuration + def __init__(self, arg1:str, arg2:int): # argX correspond to the args dict in the source configuration self._arg1 = arg1 self._arg2 = arg2 - def fetch(self): + def fetch(self) -> list[Collection]: # replace this comment with # api calls or web scraping required # to capture waste collection schedules # and extract date and waste type details + if ERROR_CONDITION: + raise Exception("YOUR ERROR MESSAGE HERE") # DO NOT JUST return [] entries = [] # List that holds collection schedule @@ -72,6 +113,23 @@ Filtering of data for waste types or time periods is a functionality of the fram - A source script should return all data for the entire time period available (including past dates if they are returned). - A source script should **not** provide a configuration option to limit the requested time frame. +### Exceptions + +- A source script should raise an exception if an error occurs during the fetch process. DO NOT JUST RETURN AN EMPTY LIST. +- A source should throw predefined exceptions wherever possible. You can import them from `waste_collection_schedule.exceptions`.: + +| Exception | Description | +|-----------|-------------| +| `SourceArgumentExceptionMultiple` | Raised when there is an error with more than one argument, and you want the error to be displayed at specific arguments. | +| `SourceArgumentException` | Raised when there is an error with an argument and you want the error to be displayed at this argument. | +| `SourceArgumentSuggestionsExceptionBase` | Base class for exceptions that provide suggestions for arguments. | +| `SourceArgumentNotFound` | Raised when an argument could not be found by the API/during the fetch process. It should NOT be thronw when an required argument is not provided | +| `SourceArgumentNotFoundWithSuggestions` | As `SourceArgumentNotFound`, but with alternative suggestions. Preferred if you do now possible different values | +| `SourceArgAmbiguousWithSuggestions` | Raised when an argument leads to multiple matches and you do not know which to choose, should provide as many suggestions as possible | +| `SourceArgumentRequired` | Raised when a required argument is missing. | +| `SourceArgumentRequiredWithSuggestions` | As `SourceArgumentRequired`, but with alternative suggestions. Preferred if you do now possible values | + + ## Service Provider Markdown File Create a new markdown file in the `doc/source` folder. The file name should be the url of your service provider in lower case, for example `abc_com.md` for `https://www.abc.com`. @@ -130,6 +188,9 @@ The script iterates through all source files and extracts some meta information | URL | String | Service provider homepage URL. The idea is to help users to identify their service provider if they search for an URL instead of a service provider name. The abbreviated domain name is therefore displayed next to the source title in README.md. | | COUNTRY | String | [Optional] Overwrite default country code which is derived from source file name. | | EXTRA_INFO | List of Dicts or Callable | [Optional] Used to add extra links in README.md and info.md if the source supports multiple service providers at the same time. The following keys can be added to the dict: `title`, `url`, `country`, `default_params`. In case a key (`title`, `url`, `country`) is missing, the corresponding value from the attributes above will be used instead. The `default_params` is a dictionary that will be auto filled when selecting this extra_info provider in the GUI configuration form. | +| HOW_TO_GET_ARGUMENTS_DESCRIPTION | Dict | [Optional] Description of how to get the arguments, will be shown in the GUI configuration form above the input fields, does not need to be translated in all languages. | +| PARAM_DESCRIPTIONS | Dict | [Optional] Description of the arguments, will be shown in the GUI configuration below the respective input field. | +| PARAM_TRANSLATIONS | Dict | [Optional] Translate the arguments, will be shown in the GUI configuration form as placeholder text. Some common parameters will be automatically translated if you do not provide this | Examples: @@ -224,3 +285,7 @@ To use it: 2023-12-08: 55L RECYCLING BOX [mdi:recycle] 2023-12-15: 240L GREY RUBBISH BIN [mdi:trash-can] ``` + +### Test before submitting using pytest + +To ensure that the source script is working as expected, it is recommended to install and run `pytest` in the `waste_collection_schedule` directory. This will run some additional tests making sure attributes are set correctly and all required files are present and update_docu_links run successfully. Pytest does not test the source script itself.