Updated the docstrings for utils

seismostats/utils/__init__.py

@@ -1,32 +1,38 @@
+# flake8: noqa
 import functools
 import math
 
 import pandas as pd
 from jinja2 import Environment, FileSystemLoader, select_autoescape
 
-from seismostats.utils.binning import (bin_to_precision, get_cum_fmd,  # noqa
-                                       get_fmd)
-from seismostats.utils.coordinates import CoordinateTransformer  # noqa
-from seismostats.utils.coordinates import (bounding_box_to_polygon,  # noqa
-                                           polygon_to_bounding_box)
-from seismostats.utils.filtering import cat_intersect_polygon  # noqa
-from seismostats.utils.simulate_distributions import (  # noqa
-    simulate_magnitudes, simulate_magnitudes_binned)
-
-
-def _check_required_cols(df: pd.DataFrame, required_cols: list[str]):
+from seismostats.utils.binning import (
+    bin_to_precision,
+    get_cum_fmd,
+    get_fmd,
+)
+from seismostats.utils.coordinates import CoordinateTransformer
+from seismostats.utils.coordinates import (
+    bounding_box_to_polygon,
+    polygon_to_bounding_box,
+)
+from seismostats.utils.filtering import cat_intersect_polygon
+from seismostats.utils.simulate_distributions import (
+    simulate_magnitudes,
+    simulate_magnitudes_binned,
+)
+
+
+def _check_required_cols(df: pd.DataFrame, required_cols: list[str]) -> bool:
     """
     Check if a DataFrame has the required columns.
 
     Args:
-        df : pandas DataFrame
-            DataFrame to check.
-            required_cols : list of str
-            List of required columns.
+        df:             DataFrame to check.
+        required_cols:  List of required columns.
 
     Returns:
-        bool
-            True if the DataFrame has the required columns, False otherwise.
+        check:          True if the DataFrame has the required columns,
+                    False otherwise.
     """
 
     if not set(required_cols).issubset(set(df.columns)):
@@ -39,12 +45,12 @@ def require_cols(_func=None, *, require: list[str], exclude: list[str] = None):
     Decorator to check if a Class has the required columns for a method.
 
     Args:
-        _func : function, optional
-            Function to decorate.
-        require : list of str
-            List of required columns.
-        exclude : list of str, optional
-            List of columns to exclude from the required columns.
+        _func:          Function to decorate.
+        require:        List of required columns.
+        exclude:        List of columns to exclude from the required columns.
+
+    Returns:
+        requirement:    Decorator function.
     """
 
     def decorator_require(func):
@@ -70,17 +76,36 @@ def wrapper_require(self, *args, **kwargs):
         return decorator_require(_func)
 
 
-def is_nan(value):
+def is_nan(value: float) -> bool:
+    """
+    Check if a value is NaN.
+
+    Args:
+        value:  Value to check.
+
+    Returns:
+        check:  True if the value is NaN, False otherwise.
+
+    Examples:
+        >>> from seismostats.utils import is_nan
+
+        >>> is_nan(float('nan'))
+        True
+        >>> is_nan(1.0)
+        False
+    """
     return isinstance(value, float) and math.isnan(value)
 
 
 def _render_template(data: dict, template_path: str) -> str:
-
+    """
+    Render a Jinja template with the provided data.
+    """
     env = Environment(
-        loader=FileSystemLoader('/'),  # Base directory for templates
-        autoescape=select_autoescape()
+        loader=FileSystemLoader("/"),  # Base directory for templates
+        autoescape=select_autoescape(),
     )
-    env.tests['nan'] = is_nan
+    env.tests["nan"] = is_nan
 
     template = env.get_template(template_path)
 

seismostats/utils/_config.py

@@ -1,6 +1,6 @@
 from typing import Any, TypedDict
 
-Options = TypedDict('Options', {'warnings': bool})
+Options = TypedDict("Options", {"warnings": bool})
 
 __options = Options(warnings=True)
 
@@ -9,17 +9,26 @@ def set_option(key: str, value: Any):
     """
     Sets the value of the specified option.
 
-        Available options:
-            - 'warnings': bool (default: True)
-                If True, warnings will be shown.
+    Available options:
+        - 'warnings': bool (default: True)
+            If True, warnings will be shown.
 
     Args:
-        key :   The option to set.
-        value : The value to set the option to.
+        key:   The option to set. Available options are 'warnings'.
+        value: The value to set the option to.
 
     Raises:
         KeyError: If the key is not in the available options.
 
+    Examples:
+        >>> from seismostats.utils._config import set_option
+
+        >>> # Disable warnings
+        >>> set_option('warnings', False)
+
+    See also:
+        :func:`seismostats.utils._config.get_option`
+
     """
     global __options
     if key in __options:
@@ -32,15 +41,21 @@ def get_option(key: str) -> Any:
     """
     Gets the value of the specified option.
 
-        Available options:
-            - 'warnings': bool (default: True)
-                If True, warnings will be shown.
+    Available options:
+        - 'warnings': bool (default: True)
+            If True, warnings will be shown.
 
     Args:
-        key :   The option to get.
+        key:   The option to get. Available options are 'warnings'.
 
     Returns:
         value:  The value of the option.
+
+    Examples:
+        >>> from seismostats.utils._config import get_option
+
+        >>> # Get the value of the 'warnings' option
+        >>> warnings = get_option('warnings')
     """
 
     return __options[key]