Skip to content

Latest commit

 

History

History
127 lines (93 loc) · 6.25 KB

contributing_ics.md

File metadata and controls

127 lines (93 loc) · 6.25 KB
Raw

Waste Collection Schedule logo

Add support via generic ICS source

Files required for a new Service Provider

The following files need to be provided to support a new service provider:

  • A yaml based ICS configuration file that contains the name and the url of the supported service provider and has test cases that can be used to confirm functionality.
  • A source markdown (.md) file that describes how to configure the new source and sensor, with examples. This file will be generated automatically out of the yaml file
  • An updated README.md file containing details of the new service provider. This file will be automatically updated by a script.
  • An updated info.md file containing details of the new service provider. This file will be automatically updated by a script.

The framework contains a test script that can be used to confirm source scripts are retrieving and returning correctly formatted waste collection schedules.

yaml based ICS configuration

Create a new file in the /doc/ics/yaml folder. The file name should be the url of your service provider in lower case, for example abc_com.yaml for https://www.abc.com.

The yaml file should have the following general structure

title: TITLE
url: URL
country: COUNTRY
howto: HOWTO
test_cases: TEST_CASES
Attribute Type Description
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 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:

title: Entsorgungsgesellschaft Görlitz-Löbau-Zittau
url: https://www.abfall-eglz.de
howto: 
  en: |
      - Go to <https://www.abfall-eglz.de/abfallkalender.html> and select your municipality.  
      - Right-click on `Entsorgungstermine als iCalendar herunterladen` and copy link address.
      - Replace the `url` in the example configuration with this link.
   de: |
      - Gehen Sie zu <https://www.abfall-eglz.de/abfallkalender.html> und wählen Sie Ihre Gemeinde aus.
      - Klicken Sie mit der rechten Maustaste auf `Entsorgungstermine als iCalendar herunterladen` und kopieren Sie den Link.
      - Ersetzen Sie die `url` in der Beispielkonfiguration durch diesen Link.
test_cases:
   Oppach:
       url: "https://www.abfall-eglz.de/abfallkalender.html?ort=Oppach&ortsteil=Ort+Oppach&strasse=&ics=1"
       split_at: " & "

Service Provider Markdown File

The markdown file will be automatically generated from the information in the yaml file. Just call update_docu_links.py in the top-level directory. This will also update README.md and info.md automatically.

./update_docu_links.py

Update Links in README.md and info.md

The README.md file in the top level folder contains a list of supported service providers.

The info.md is rendered in the HACS user interface within Home Assistant and gives potential users a summary of what the component does, and the service providers supported.

The links in both files can be updated automatically using the script update_docu_links.py in the top-level directory:

./update_docu_links.py

Test the new ICS configuration

Debugging a source script within Home Assistant is not recommended. Home Assistant's start-up process is too slow for fast debugging cycles. To help with debugging/troubleshooting, the Waste Collection Schedule framework contains a command line script that can be used to test source scripts. The script iterates through the test cases defined in the source script passing each set of arguments to the source script and prints the results.

The script supports the following options:

Option Argument Description
-I - Test all yaml files.
-y YAML yaml file name in folder /doc/ics/yaml without ending .yaml
-l - List all found dates.
-i - Add icon name to output. Only effective together with -l.
-t - Show extended exception info and stack trace.

For debugging purposes of a single yaml configuration, it is recommended to use the -y YAML option. If used without any arguments provided, the script tests every script in the custom_components/waste_collection_schedule/waste_collection_schedule/source folder and prints the number of found entries for every test case.

To use it:

  1. Navigate to the /custom_components/waste_collection_schedule/waste_collection_schedule/test/ directory

  2. Confirm the test_sources.py script is present

  3. Execute the test script. For example, testing the abc_com.yaml configuration file would be:

    test_sources.py -y koblenz_de

  4. Confirm the results returned match expectation. For example, testing koblenz_de returns:

    Testing ICS koblenz_de
  found 60 entries for Altstadt

  5. To view individual date entries, use the -l arguments, for example:

    test_sources.py -y koblenz_de -l
Testing ICS koblenz_de
  found 60 entries for Altstadt
    2023-04-19 : Altpapier
    2023-05-10 : Altpapier
    2023-06-01 : Altpapier
    2023-06-21 : Altpapier
    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.