From 9d71aaf223655c7926fe0f4e284231110fb4cc7e Mon Sep 17 00:00:00 2001
From: Christian Ledermann <christian.ledermann@gmail.com>
Date: Thu, 18 Jul 2024 18:48:05 +0100
Subject: [PATCH] better docstrings and ruff fixes

---
 fastkml/registry.py |   1 +
 fastkml/styles.py   | 343 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 341 insertions(+), 3 deletions(-)

diff --git a/fastkml/registry.py b/fastkml/registry.py
index b341a6d6..d80aaff0 100644
--- a/fastkml/registry.py
+++ b/fastkml/registry.py
@@ -13,6 +13,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this library; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+"""Registry for XML objects."""
 from dataclasses import dataclass
 from enum import Enum
 from typing import TYPE_CHECKING
diff --git a/fastkml/styles.py b/fastkml/styles.py
index e0e745ee..5f311898 100644
--- a/fastkml/styles.py
+++ b/fastkml/styles.py
@@ -15,6 +15,8 @@
 # 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
 """
+KML Styles.
+
 Once you've created features within Google Earth and examined the KML
 code Google Earth generates, you'll notice how styles are an important
 part of how your data is displayed.
@@ -82,6 +84,29 @@ def __init__(
         url: Optional[str] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a Style object.
+
+        Args:
+        ----
+        ns : str, optional
+            The namespace of the Style object.
+        name_spaces : dict, optional
+            A dictionary of namespace prefixes and their corresponding URIs.
+        id : str, optional
+            The ID of the Style object.
+        target_id : str, optional
+            The ID of the target object that this Style object applies to.
+        url : str, optional
+            The URL of the Style object.
+        **kwargs : Any
+            Additional keyword arguments.
+
+        Returns:
+        -------
+        None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -105,6 +130,15 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if the style has a URL.
+
+        Returns
+        -------
+        bool
+            True if the style has a URL, False otherwise.
+
+        """
         return bool(self.url)
 
     @classmethod
@@ -128,7 +162,8 @@ def get_tag_name(cls) -> str:
 
 class _StyleSelector(_BaseObject):
     """
-    This is an abstract element and cannot be used directly in a KML file.
+    Abstract element that cannot be used directly in a KML file.
+
     It is the base type for the <Style> and <StyleMap> elements. The
     StyleMap element selects a style based on the current mode of the
     Placemark. An element derived from StyleSelector is uniquely identified
@@ -140,8 +175,8 @@ class _StyleSelector(_BaseObject):
 
 class _ColorStyle(_BaseObject):
     """
-    abstract element; do not create.
-    This is an abstract element and cannot be used directly in a KML file.
+    Abstract element that cannot be used directly in a KML file.
+
     It provides elements for specifying the color and color mode of
     extended style types.
     subclasses are: IconStyle, LabelStyle, LineStyle, PolyStyle.
@@ -170,6 +205,24 @@ def __init__(
         color_mode: Optional[ColorMode] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a Style object.
+
+        Args:
+        ----
+            ns (Optional[str]): The namespace of the style.
+            name_spaces (Optional[Dict[str, str]]): The dictionary of namespaces.
+            id (Optional[str]): The ID of the style.
+            target_id (Optional[str]): The target ID of the style.
+            color (Optional[str]): The color of the style.
+            color_mode (Optional[ColorMode]): The color mode of the style.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+        -------
+            None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -253,6 +306,25 @@ def __init__(
         yunits: Optional[Units] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a Style element.
+
+        Args:
+        ----
+            ns (Optional[str]): The namespace for the element.
+            name_spaces (Optional[Dict[str, str]]): The dictionary of namespace prefixes
+                and URIs.
+            x (Optional[float]): The x-coordinate of the point.
+            y (Optional[float]): The y-coordinate of the point.
+            xunits (Optional[Units]): The units for the x-coordinate.
+            yunits (Optional[Units]): The units for the y-coordinate.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+        -------
+            None
+
+        """
         super().__init__(ns=ns, name_spaces=name_spaces, **kwargs)
         self.x = x
         self.y = y
@@ -274,6 +346,14 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if both x and y attributes are not None.
+
+        Returns
+        -------
+            bool: True if both x and y are not None, False otherwise.
+
+        """
         return all((self.x is not None, self.y is not None))
 
     @classmethod
@@ -363,6 +443,29 @@ def __init__(
         hot_spot: Optional[HotSpot] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a Style object.
+
+        Args:
+        ----
+            ns (Optional[str]): The namespace for the Style object.
+            name_spaces (Optional[Dict[str, str]]): The dictionary of namespace prefixes
+                and URIs.
+            id (Optional[str]): The ID of the Style object.
+            target_id (Optional[str]): The target ID of the Style object.
+            color (Optional[str]): The color of the Style object.
+            color_mode (Optional[ColorMode]): The color mode of the Style object.
+            scale (Optional[float]): The scale of the Style object.
+            heading (Optional[float]): The heading of the Style object.
+            icon (Optional[Icon]): The icon of the Style object.
+            hot_spot (Optional[HotSpot]): The hot spot of the Style object.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+        -------
+            None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -397,6 +500,15 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if the Style has an icon.
+
+        Returns
+        -------
+        bool
+            True if the Style has an icon, False otherwise.
+
+        """
         return bool(self.icon)
 
 
@@ -469,6 +581,26 @@ def __init__(
         width: Optional[float] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a Style object.
+
+        Args:
+        ----
+            ns (Optional[str]): The namespace for the Style object.
+            name_spaces (Optional[Dict[str, str]]): The dictionary of namespace prefixes
+                and URIs.
+            id (Optional[str]): The ID of the Style object.
+            target_id (Optional[str]): The target ID of the Style object.
+            color (Optional[str]): The color of the Style object.
+            color_mode (Optional[ColorMode]): The color mode of the Style object.
+            width (Optional[float]): The width of the Style object.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+        -------
+            None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -496,6 +628,14 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if the style has a width defined.
+
+        Returns
+        -------
+            bool: True if the width is not None, False otherwise.
+
+        """
         return self.width is not None
 
 
@@ -541,6 +681,27 @@ def __init__(
         outline: Optional[bool] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a Style object.
+
+        Args:
+        ----
+            ns (Optional[str]): The namespace for the style.
+            name_spaces (Optional[Dict[str, str]]): The dictionary of namespace prefixes
+                and URIs.
+            id (Optional[str]): The ID of the style.
+            target_id (Optional[str]): The ID of the target element.
+            color (Optional[str]): The color of the style.
+            color_mode (Optional[ColorMode]): The color mode of the style.
+            fill (Optional[bool]): Whether to fill the style.
+            outline (Optional[bool]): Whether to outline the style.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+        -------
+            None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -570,6 +731,14 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Return True if the style has a fill or outline, False otherwise.
+
+        Returns
+        -------
+            bool: True if the style has a fill or outline, False otherwise.
+
+        """
         return self.fill is not None or self.outline is not None
 
 
@@ -620,6 +789,26 @@ def __init__(
         scale: Optional[float] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a Style object.
+
+        Args:
+        ----
+            ns (Optional[str]): The namespace for the style.
+            name_spaces (Optional[Dict[str, str]]): The dictionary of namespace prefixes
+                and URIs.
+            id (Optional[str]): The ID of the style.
+            target_id (Optional[str]): The ID of the target element.
+            color (Optional[str]): The color of the style.
+            color_mode (Optional[ColorMode]): The color mode of the style.
+            scale (Optional[float]): The scale of the style.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+        -------
+            None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -647,6 +836,15 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if the Style has any non-None attributes.
+
+        Returns
+        -------
+            bool: True if any of the following attributes are not None:
+                scale, color, color_mode.
+
+        """
         return any(
             (
                 self.scale is not None,
@@ -734,6 +932,27 @@ def __init__(
         display_mode: Optional[DisplayMode] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a Style object.
+
+        Args:
+        ----
+            ns (Optional[str]): The namespace for the style.
+            name_spaces (Optional[Dict[str, str]]): The dictionary of namespace prefixes
+            and URIs.
+            id (Optional[str]): The ID of the style.
+            target_id (Optional[str]): The ID of the target element.
+            bg_color (Optional[str]): The background color of the style.
+            text_color (Optional[str]): The text color of the style.
+            text (Optional[str]): The text content of the style.
+            display_mode (Optional[DisplayMode]): The display mode of the style.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+        -------
+            None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -763,6 +982,19 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if the Style has any non-None attributes.
+
+        Returns
+        -------
+            bool: True if any of the following attributes are not None:
+                - bg_color
+                - text_color
+                - text
+                - display_mode
+            False otherwise.
+
+        """
         return any(
             (
                 self.bg_color is not None,
@@ -844,6 +1076,24 @@ def __init__(
         styles: Optional[Iterable[AnyStyle]] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a Style element.
+
+        Args:
+        ----
+            ns (Optional[str]): The namespace for the element.
+            name_spaces (Optional[Dict[str, str]]): The dictionary of namespace prefixes
+                and URIs.
+            id (Optional[str]): The ID of the element.
+            target_id (Optional[str]): The target ID of the element.
+            styles (Optional[Iterable[AnyStyle]]): The list of styles.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+        -------
+            None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -867,6 +1117,15 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if the Styles object contains any styles.
+
+        Returns
+        -------
+        bool
+            True if the Styles object contains any styles, False otherwise.
+
+        """
         return any(self.styles)
 
 
@@ -919,6 +1178,31 @@ def __init__(
         style: Optional[Union[StyleUrl, Style]] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a StyleSelector object.
+
+        Args:
+        ----
+            ns : Optional[str]
+                The namespace of the element.
+            name_spaces : Optional[Dict[str, str]]
+                The dictionary of namespace prefixes and URIs.
+            id : Optional[str]
+                The ID of the element.
+            target_id : Optional[str]
+                The target ID of the element.
+            key : Optional[PairKey]
+                The key of the element.
+            style : Optional[Union[StyleUrl, Style]]
+                The style or style URL of the element.
+            kwargs : Any
+                Additional keyword arguments.
+
+        Returns:
+        -------
+         None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -944,6 +1228,14 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if the StyleMap has both a key and a style.
+
+        Returns
+        -------
+            bool: True if the StyleMap has both a key and a style, False otherwise.
+
+        """
         return all((self.key is not None, self.style is not None))
 
 
@@ -977,6 +1269,7 @@ def __bool__(self) -> bool:
 class StyleMap(_StyleSelector):
     """
     A <StyleMap> maps between two different Styles.
+
     Typically a <StyleMap> element is used to provide separate normal and highlighted
     styles for a placemark, so that the highlighted version appears when
     the user mouses over the icon in Google Earth.
@@ -995,6 +1288,24 @@ def __init__(
         pairs: Optional[Iterable[Pair]] = None,
         **kwargs: Any,
     ) -> None:
+        """
+        Initialize a new Style object.
+
+        Args:
+        ----
+            ns (Optional[str]): The namespace of the style.
+            name_spaces (Optional[Dict[str, str]]): The dictionary of namespace prefixes
+                and URIs.
+            id (Optional[str]): The ID of the style.
+            target_id (Optional[str]): The ID of the target element.
+            pairs (Optional[Iterable[Pair]]): The list of pairs.
+            **kwargs (Any): Additional keyword arguments.
+
+        Returns:
+        -------
+            None
+
+        """
         super().__init__(
             ns=ns,
             name_spaces=name_spaces,
@@ -1018,10 +1329,27 @@ def __repr__(self) -> str:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if the Style has any pairs.
+
+        Returns
+        -------
+        bool
+            True if the Style has any pairs, False otherwise.
+
+        """
         return bool(self.pairs)
 
     @property
     def normal(self) -> Optional[Union[StyleUrl, Style]]:
+        """
+        Get the normal style for the feature.
+
+        Returns
+        -------
+            The normal style for the feature, if available. Otherwise, returns None.
+
+        """
         return next(
             (pair.style for pair in self.pairs if pair.key == PairKey.normal),
             None,
@@ -1029,6 +1357,15 @@ def normal(self) -> Optional[Union[StyleUrl, Style]]:
 
     @property
     def highlight(self) -> Optional[Union[StyleUrl, Style]]:
+        """
+        Return the highlight style associated with this StyleMap.
+
+        Returns
+        -------
+            The highlight style, which can be either a StyleUrl or a Style object.
+            If no highlight style is found, None is returned.
+
+        """
         return next(
             (pair.style for pair in self.pairs if pair.key == PairKey.highlight),
             None,