From eec3564d17dd349d4bee0bcc99b364cc9032a7b3 Mon Sep 17 00:00:00 2001
From: Jules Dejaeghere <dej.j@live.be>
Date: Tue, 2 Apr 2024 22:31:11 +0200
Subject: [PATCH] Add docstring

---
 custom_components/irm_kmi/pollen.py | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/custom_components/irm_kmi/pollen.py b/custom_components/irm_kmi/pollen.py
index bbec52e..3d1ef0d 100644
--- a/custom_components/irm_kmi/pollen.py
+++ b/custom_components/irm_kmi/pollen.py
@@ -1,3 +1,4 @@
+"""Parse pollen info from SVG from IRM KMI api"""
 import logging
 import xml.etree.ElementTree as ET
 from typing import List
@@ -8,6 +9,22 @@ _LOGGER = logging.getLogger(__name__)
 
 
 class PollenParser:
+    """
+    The SVG looks as follows (see test fixture for a real example)
+
+    Active pollens
+    ---------------------------------
+    Oak                        active
+    Ash                        active
+    ---------------------------------
+    Birch         ---|---|---|---|-*-
+    Alder         -*-|---|---|---|---
+
+    This classe parses the oak and ash as active, birch as purple and alder as green in the example.
+    For active pollen, check if an active text is present on the same line as the pollen name
+    For the color scale, look for a white dot (nearly) at the same level as the pollen name.  From the white dot
+    horizontal position, determine the level
+    """
     def __init__(
             self,
             xml_string: str
@@ -16,6 +33,7 @@ class PollenParser:
 
     @staticmethod
     def _validate_svg(elements: List[ET.Element]) -> bool:
+        """Make sure that the colors of the scale are still where we expect them"""
         x_values = {"rectgreen": 80,
                     "rectyellow": 95,
                     "rectorange": 110,
@@ -32,14 +50,17 @@ class PollenParser:
 
     @staticmethod
     def get_default_data() -> dict:
+        """Return all the known pollen with 'none' value"""
         return {k.lower(): 'none' for k in POLLEN_NAMES}
 
     @staticmethod
     def get_option_values() -> List[str]:
+        """List all the values that the pollen can have"""
         return ['active', 'green', 'yellow', 'orange', 'red', 'purple', 'none']
 
     @staticmethod
     def _extract_elements(root) -> List[ET.Element]:
+        """Recursively collect all elements of the SVG in a list"""
         elements = []
         for child in root:
             elements.append(child)
@@ -48,7 +69,7 @@ class PollenParser:
 
     @staticmethod
     def _dot_to_color_value(dot: ET.Element) -> str:
-
+        """Map the dot horizontal position to a color or 'none'"""
         try:
             cx = float(dot.attrib.get('cx'))
         except ValueError:
@@ -70,6 +91,8 @@ class PollenParser:
             return 'none'
 
     def get_pollen_data(self) -> dict:
+        """From the XML string, parse the SVG and extract the pollen data from the image.
+        If an error occurs, return the default value"""
         pollen_data = self.get_default_data()
         try:
             root = ET.fromstring(self._xml)