sascha_hemi/hacs_waste_collection_schedule
1
0
Fork 0
mirror of https://github.com/sascha-hemi/hacs_waste_collection_schedule.git synced 2026-03-21 00:04:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

update contributing md files

Browse Source 
for how to use the new exceptions
for the new Source attributes
This commit is contained in:
5ila5
2024-08-17 15:35:58 +02:00
committed by 5ila5
parent a550e01bd7
commit d5012c84a8
2 changed files with 72 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/contributing_ics.md
View File

@@ -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.

69
doc/contributing_source.md
View File

@@ -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.