sibi-dst 0.3.32__py3-none-any.whl → 0.3.33__py3-none-any.whl

sibi_dst/df_helper/backends/sqlalchemy/_sql_model_builder.py

@@ -10,6 +10,28 @@ apps_label = "datacubes"
 
 
 class SqlAlchemyModelBuilder:
+    """
+    Provides functionality for building SQLAlchemy ORM models dynamically from
+    reflected database tables. This class is intended for use with a SQLAlchemy
+    engine and metadata to automatically generate ORM models for specified
+    database tables.
+
+    The primary purpose of this class is to simplify the process of creating
+    SQLAlchemy ORM models by reflecting tables from a connected database,
+    dynamically generating model classes, and handling relationships between
+    tables.
+
+    :ivar engine: SQLAlchemy engine connected to the database.
+    :type engine: Engine
+    :ivar table_name: Name of the table for which the model is generated.
+    :type table_name: str
+    :ivar metadata: SQLAlchemy MetaData instance for reflecting tables.
+    :type metadata: MetaData
+    :ivar table: Reflected SQLAlchemy Table object for the specified table name.
+    :type table: Optional[Table]
+    :ivar class_name: Dynamically normalized class name derived from table_name.
+    :type class_name: str
+    """
     _model_cache = {}  # Local cache for model classes
 
     def __init__(self, engine, table_name):
@@ -27,6 +49,16 @@ class SqlAlchemyModelBuilder:
         self.class_name = self.normalize_class_name(self.table_name)
 
     def build_model(self) -> type:
+        """
+        Builds and returns a database model class corresponding to the specified table name.
+        The method checks if the model is already registered in the ORM's registry. If not,
+        it reflects the database schema of the specified table and dynamically creates the
+        model class.
+
+        :raises ValueError: If the specified table does not exist in the database.
+        :return: A database model class corresponding to the specified table name.
+        :rtype: type
+        """
         # Check if the model is already registered
         model = Base.registry._class_registry.get(self.class_name)
         if model:
@@ -42,10 +74,17 @@ class SqlAlchemyModelBuilder:
 
     def create_model(self) -> type:
         """
-        Create a SQLAlchemy ORM model for the reflected table.
+        Generates a SQLAlchemy model class dynamically based on the specified table and
+        its columns. The method extracts column information, defines the necessary
+        attributes, and creates the model class if it doesn't already exist in the
+        SQLAlchemy base registry.
 
-        Returns:
-            type: Dynamically generated SQLAlchemy ORM model class.
+        :raises KeyError: If the table or table name does not exist in the provided
+            schema.
+        :raises Exception: If the model creation fails for any reason.
+
+        :return: The dynamically created or fetched model class.
+        :rtype: type
         """
         # Normalize the class name from the table name
         columns = self.get_columns(self.table)
@@ -70,13 +109,17 @@ class SqlAlchemyModelBuilder:
 
     def get_columns(self, table: Table):
         """
-        Extract columns from the table and create corresponding SQLAlchemy fields.
-
-        Args:
-            table (Table): SQLAlchemy Table object.
-
-        Returns:
-            dict: Dictionary of column attributes.
+        Extracts and returns a dictionary of column names and their corresponding column
+        objects from a given table, excluding reserved names. Reserved names are used
+        internally and should not overlap with column names in the provided table. The
+        method ensures sanitized column names through normalization and filters out any
+        column matching reserved keywords.
+
+        :param table: The table object from which columns are to be extracted.
+        :type table: Table
+        :return: A dictionary containing the sanitized column names as keys and their
+            corresponding column objects as values, excluding reserved names.
+        :rtype: dict
         """
         columns = {}
         reserved_names = ["metadata", "class_", "table"]
@@ -89,11 +132,18 @@ class SqlAlchemyModelBuilder:
 
     def add_relationships(self, attrs, table: Table):
         """
-        Add relationships to the model for foreign keys.
-
-        Args:
-            attrs (dict): Attributes of the dynamically created model.
-            table (Table): SQLAlchemy Table object.
+        Adds relationships to the provided attributes dictionary for a given database table.
+
+        This method iterates through the foreign keys of the provided table, constructs
+        relationship attributes, and updates the attributes dictionary with relationships
+        that connect the current table to related tables.
+
+        :param attrs: Dictionary of attributes to which relationships will be added.
+                      The dictionary will be updated with new relationship mappings.
+        :type attrs: dict
+        :param table: A database table object containing foreign key relationships.
+                      The method will use this table to establish relationships.
+        :return: None
         """
         for fk in table.foreign_keys:
             related_table_name = fk.column.table.name
@@ -104,26 +154,37 @@ class SqlAlchemyModelBuilder:
     @staticmethod
     def normalize_class_name(table_name: str) -> str:
         """
-        Normalize a table name into a valid Python class name.
-
-        Args:
-            table_name (str): Name of the table.
-
-        Returns:
-            str: Normalized class name.
+        Generate a normalized class name from a given table name by capitalizing
+        each word separated by underscores and concatenating them.
+
+        This static method takes a string representation of a table name, where
+        words are separated by underscores, and converts it into a camel case
+        class name. It processes the string by capitalizing the first letter of
+        each word and removing the underscores. The normalized class name
+        returned can be used programmatically for various purposes, such as
+        class generation or naming conventions.
+
+        :param table_name: The table name to normalize, with words separated by
+            underscores. E.g., 'sample_table' becomes 'SampleTable'.
+        :type table_name: str
+        :return: A normalized class name in camel case format.
+        :rtype: str
         """
         return "".join(word.capitalize() for word in table_name.split("_"))
 
     @staticmethod
     def normalize_column_name(column_name: str) -> str:
         """
-        Normalize a column name into a valid Python identifier.
-
-        Args:
-            column_name (str): Name of the column.
-
-        Returns:
-            str: Normalized column name.
+        Normalize a column name by replacing any non-word characters or leading numbers
+        with underscores, while ensuring it does not conflict with reserved keywords
+        such as 'class', 'def', 'return', etc. If the normalized name conflicts with
+        a Python reserved keyword, "_field" is appended to it.
+
+        :param column_name: The original name of the column to be normalized.
+        :type column_name: str
+        :return: A normalized column name that is safe and compatible for usage
+            in various contexts such as database columns or Python code.
+        :rtype: str
         """
         column_name = re.sub(r"\W|^(?=\d)", "_", column_name)
         if column_name in {"class", "def", "return", "yield", "global"}:

sibi_dst/df_helper/core/_params_config.py

@@ -27,6 +27,36 @@ LOOKUP_SEP = "__"
 
 
 class ParamsConfig(BaseModel):
+    """
+    Defines a configuration model for parameters with functionality for parsing,
+    validation, and conversion of legacy filters.
+
+    This class extends BaseModel from Pydantic and is designed to handle multiple
+    sets of configurations, including field mappings, filters, dataframe parameters,
+    and dataframe options. It allows for flexible parsing of parameters across a
+    variety of supported structures and ensures that legacy filters can be
+    appropriately converted for compatibility.
+
+    :ivar field_map: Maps field names to their equivalent legacy field names.
+    :type field_map: Optional[Dict]
+    :ivar legacy_filters: Indicates whether legacy filters should be processed.
+    :type legacy_filters: bool
+    :ivar sticky_filters: Stores additional filters as key-value pairs that persist
+        across parameter parsing.
+    :type sticky_filters: Dict[str, Union[str, bool, int, float, list, tuple]]
+    :ivar filters: Holds all the current filters including sticky and dynamically
+        parsed filters.
+    :type filters: Dict[str, Union[str, Dict, bool, int, float, list, tuple]]
+    :ivar df_params: Contains parameters related to dataframe configurations in a
+        structured format.
+    :type df_params: Dict[str, Union[tuple, str, bool, None]]
+    :ivar df_options: Stores optional configurations for a dataframe, allowing for
+        additional behavior customization.
+    :type df_options: Dict[str, Union[bool, str, None]]
+    :ivar params: Dictionary of parameters provided for configuration, supporting
+        both basic and nested structures.
+    :type params: Dict[str, Union[str, bool, int, float, List[Union[str, int, bool, float]]]]
+    """
     field_map: Optional[Dict] = Field(default_factory=dict)
     legacy_filters: bool = False
     sticky_filters: Dict[str, Union[str, bool, int, float, list, tuple]] = Field(default_factory=dict)
@@ -42,6 +72,17 @@ class ParamsConfig(BaseModel):
         return self
 
     def parse_params(self, params):
+        """
+        Parses and separates the given parameters into specific categories such as dataframe parameters,
+        dataframe options, and filters. Updates existing class attributes with the parsed values,
+        retaining any sticky filters. Also handles the legacy filters if provided.
+
+        :param params: Dictionary containing parameters to process. These parameters can include specific
+            keys relevant for dataframe configuration (e.g., dataframe parameters, dataframe options)
+            as well as arbitrary filter settings.
+        :type params: dict
+        :return: None
+        """
         self.legacy_filters = params.pop('legacy_filters', self.legacy_filters)
         self.field_map = params.pop('field_map', self.field_map)
         self.sticky_filters = params.pop('params', self.sticky_filters)
@@ -60,6 +101,24 @@ class ParamsConfig(BaseModel):
             self.convert_legacy_filters()
 
     def convert_legacy_filters(self):
+        """
+            Converts legacy filter fields in the `self.filters` dictionary to their
+            modern equivalents using the mappings provided in `self.field_map`.
+            This method ensures backward compatibility for filters by automatically
+            translating the old field names into the current system.
+
+            The function first verifies that the required dictionaries (`legacy_filters`,
+            `field_map`, `filters`) are valid. It creates a reverse map of `field_map` for
+            efficient lookup, processes the key names within `self.filters`, and updates
+            them to reflect the legacy mapping.
+
+            :raises KeyError: If any required dictionary key is missing during processing.
+
+            :param self.legacy_filters: A boolean flag indicating whether legacy filters
+                are being used.
+            :type self.legacy_filters: bool
+
+        """
         if not self.legacy_filters or not self.field_map or not self.filters:
             return
         # create a reverse map of the field_map

sibi_dst/geopy_helper/geo_location_service.py

@@ -8,6 +8,20 @@ app_geo_locator_test_place = os.environ.get('GEO_LOCATOR_TEST_PLACE', "San Jose,
 
 
 class GeolocationService:
+    """
+    Provides geolocation services, such as forward and reverse geocoding.
+
+    This class is intended to interface with a geocoding service (e.g., Nominatim)
+    for performing geocoding operations. It initializes the geolocation service
+    based on a provided or default configuration and provides methods for geocoding
+    addresses or retrieving addresses from coordinates.
+
+    :ivar geolocator: Instance of the geocoding service used for geolocation tasks.
+        Will be `None` if initialization fails or is incomplete.
+    :type geolocator: Optional[Nominatim]
+    :ivar debug: Indicates whether debug messages are enabled.
+    :type debug: bool
+    """
     debug: bool = False
 
     def __init__(self, debug=False):

sibi_dst/geopy_helper/utils.py

@@ -5,6 +5,16 @@ geolocator = None
 
 
 def get_geolocator():
+    """
+    Provides a function to instantiate or retrieve a global geolocator instance
+    using the GeolocationService class. If the geolocator has already been
+    created, it will return the original global instance. Otherwise, it initializes
+    a new instance of the GeolocationService with debugging enabled and stores it
+    globally.
+
+    :return: The global instance of the GeolocationService
+    :rtype: GeolocationService
+    """
     global geolocator
     if geolocator is None:
         geolocator = GeolocationService(debug=True)
@@ -15,6 +25,23 @@ def get_geolocator():
 
 
 def get_address_by_coordinates(latitude, longitude, exactly_one=True):
+    """
+    Retrieves the address based on the provided geographic coordinates (latitude and
+    longitude). Utilizes the geopy library's geolocator to find and reverse-geocode
+    the location associated with the given coordinates. Returns a human-readable
+    address if available or an error message for specific conditions.
+
+    :param latitude: The latitude of the location to find the address for.
+    :type latitude: float
+    :param longitude: The longitude of the location to find the address for.
+    :type longitude: float
+    :param exactly_one: If true, ensures exactly one result is returned. If false,
+        returns a list of possible matches. Defaults to True.
+    :type exactly_one: bool, optional
+    :return: A string containing the human-readable address of the location or an
+        error message in case of failure.
+    :rtype: str
+    """
     geolocator = get_geolocator()
     try:
         location = geolocator.reverse((latitude, longitude), exactly_one=exactly_one)
@@ -28,10 +55,17 @@ def get_address_by_coordinates(latitude, longitude, exactly_one=True):
 
 def get_coordinates_for_address(address):
     """
-    Geocode an address using a custom Nominatim server.
+    Gets geographical coordinates (latitude and longitude) along with the full formatted
+    address for a given address string. Makes use of a geolocation service to retrieve
+    the data and handles possible exceptions during the process.
+
+    :param address: The address as a string for which coordinates need to be determined.
+    :type address: str
 
-    :param address: The address to geocode.
-    :return: A dictionary with the location's latitude, longitude, and full address, or a message if an error occurs.
+    :return: A dictionary containing the full formatted address, latitude, and longitude
+             if the location is found. Otherwise, returns a string describing an error
+             or that no location was found.
+    :rtype: dict or str
     """
     geolocator = get_geolocator()
     try:

sibi_dst/osmnx_helper/base_osm_map.py

@@ -11,6 +11,64 @@ from folium.plugins import Fullscreen
 
 
 class BaseOsmMap:
+    """
+    BaseOsmMap class serves as a foundational class for creating and managing maps
+    using OpenStreetMap data. It integrates features from libraries like osmnx and
+    folium to facilitate visualization, tile layer management, bounding box handling,
+    and nearest node calculation for geographic coordinates.
+
+    The class is designed to be subclassed, enabling customization of map processing
+    logic while providing core functionalities needed for map creation and manipulation.
+
+    :ivar tile_options: Dictionary containing options for pre-defined tile layers.
+                        Keys represent display names while values represent tile layer configurations.
+    :type tile_options: dict
+    :ivar bounds: Default map bounds representing geographical extents for Costa Rica.
+    :type bounds: list[list[float]]
+    :ivar osmnx_graph: Input graph representing OpenStreetMap network data, used for
+                       operations like subgraph extraction and nearest node calculation.
+    :type osmnx_graph: networkx.classes.multidigraph.MultiDiGraph
+    :ivar df: DataFrame containing data points with geographic coordinates. It must
+              not be empty and should include latitude and longitude columns as specified
+              in `lat_col` and `lon_col`.
+    :type df: pandas.DataFrame
+    :ivar lat_col: Name of the column in `df` representing latitude coordinates of data points.
+    :type lat_col: str
+    :ivar lon_col: Name of the column in `df` representing longitude coordinates of data points.
+    :type lon_col: str
+    :ivar osm_map: Folium Map object that serves as a container for geographic visualization.
+                   This is dynamically initialized based on the provided data.
+    :type osm_map: folium.Map
+    :ivar G: Subgraph of the provided `osmnx_graph`, extracted based on bounding box
+             derived from the input data.
+    :type G: networkx.classes.multidigraph.MultiDiGraph
+    :ivar map_html_title: HTML-escaped title for map visualization, shown on the interactive map.
+    :type map_html_title: str
+    :ivar zoom_start: Initial zoom level for the map when rendered.
+    :type zoom_start: int
+    :ivar fullscreen: Boolean option to enable or disable fullscreen control on the interactive map.
+    :type fullscreen: bool
+    :ivar fullscreen_position: Position of the fullscreen control on the map, e.g., 'topright'.
+    :type fullscreen_position: str
+    :ivar tiles: Default tile layer to be used for the map visualization.
+    :type tiles: str
+    :ivar verbose: Boolean flag indicating if verbose logging of operations should be enabled.
+    :type verbose: bool
+    :ivar sort_keys: Keys to sort the DataFrame by, if applicable, before processing.
+    :type sort_keys: list[str] or None
+    :ivar dt_field: Column name in `df` representing datetimes, if applicable, for specialized processing.
+    :type dt_field: str or None
+    :ivar dt: List of datetime objects extracted from `dt_field` in `df`, dynamically initialized.
+    :type dt: list[datetime.datetime] or None
+    :ivar calc_nearest_nodes: Boolean flag to indicate whether nearest nodes to the input
+                              points should be calculated from `osmnx_graph`.
+    :type calc_nearest_nodes: bool
+    :ivar nearest_nodes: List of nearest node IDs for each point in the input data, if calculated.
+    :type nearest_nodes: list[int] or None
+    :ivar max_bounds: Boolean indicating whether bounds (default to Costa Rica) should be applied
+                      to fit the map within those limits interactively.
+    :type max_bounds: bool
+    """
     tile_options = {
         "OpenStreetMap": "OpenStreetMap",
         "CartoDB": "cartodbpositron",
@@ -20,6 +78,47 @@ class BaseOsmMap:
     bounds = [[8.0340, -85.9417], [11.2192, -82.5566]]
 
     def __init__(self, osmnx_graph=None, df=None, **kwargs):
+        """
+        Initializes a map visualization handler with input parameters for managing and displaying
+        spatial data in conjunction with an OSMnx graph. It validates input parameters for completeness
+        and correctness, and configures internal attributes for the visualization of map layers.
+
+        :param osmnx_graph: The OSMnx graph to be used for spatial data processing.
+        :param df: The pandas DataFrame containing spatial data.
+        :param kwargs: Additional keyword arguments for customization.
+        :type osmnx_graph: object
+        :type df: pandas.DataFrame
+        :type kwargs: dict
+
+        :raises ValueError: If `osmnx_graph` is not provided.
+        :raises ValueError: If `df` is not provided.
+        :raises ValueError: If the provided `df` is empty.
+
+        :attribute df: A copy of the provided DataFrame.
+        :attribute osmnx_graph: The input OSMnx graph used for spatial data operations.
+        :attribute lat_col: The name of the column in `df` containing latitude values.
+        :attribute lon_col: The name of the column in `df` containing longitude values.
+        :attribute osm_map: Internal representation of the map; initialized to None.
+        :attribute G: Placeholder for graph-related data; initialized to None.
+        :attribute map_html_title: Sanitized HTML title to be used in rendered map outputs.
+        :attribute zoom_start: The initial zoom level for the map visualization (default: 13).
+        :attribute fullscreen: Boolean flag to enable fullscreen map display (default: True).
+        :attribute fullscreen_position: The position of the fullscreen control button
+            (default: 'topright').
+        :attribute tiles: The tile set to be used for the map visualization (default: 'OpenStreetMap').
+        :attribute verbose: Boolean flag for enabling verbose output (default: False).
+        :attribute sort_keys: Optional parameter dictating sorting order for keys (default: None).
+        :attribute dt_field: Optional name of the datetime field in the DataFrame (default: None).
+        :attribute dt: Placeholder for date/time data; initialized to None.
+        :attribute calc_nearest_nodes: Boolean flag to calculate nearest nodes to coordinates
+            (default: False).
+        :attribute nearest_nodes: Placeholder for nearest nodes data; initialized to None.
+        :attribute max_bounds: Boolean flag to restrict the map view to maximum bounds
+            (default: False).
+
+        :note: This class also initializes necessary internal functionalities including DataFrame
+            pre-processing (`_prepare_df`) and base map setup (`_initialise_map`).
+        """
         if osmnx_graph is None:
             raise ValueError('osmnx_graph must be provided')
         if df is None:
@@ -50,6 +149,21 @@ class BaseOsmMap:
 
 
     def _prepare_df(self):
+        """
+        Prepares the underlying DataFrame for further processing.
+
+        This method performs several operations on the DataFrame, such as sorting,
+        resetting the index, and extracting relevant columns into various lists.
+        Additionally, it calculates the nearest nodes from an OSMnx graph if
+        required. The operations are governed by instance attributes and their
+        current states.
+
+        :raises AttributeError: If required attributes for processing are not
+            correctly set or do not exist in the DataFrame.
+        :param self: Object that contains the DataFrame (df) and other related
+            attributes required for processing.
+        :return: None
+        """
         if self.sort_keys:
             self.df.sort_values(by=self.sort_keys, inplace=True)
         self.df.reset_index(drop=True, inplace=True)
@@ -63,6 +177,15 @@ class BaseOsmMap:
 
 
     def _initialise_map(self):
+        """
+        Initializes an OpenStreetMap (OSM) map instance and extracts a subgraph of map
+        data based on provided GPS points. The map's central location is calculated
+        as the mean of the latitudinal and longitudinal values of the GPS points.
+        Additionally, a bounding box is determined to extract the relevant section
+        of the map graph.
+
+        :return: None
+        """
         gps_array = np.array(self.gps_points)
         mean_latitude = np.mean(gps_array[:, 0])
         mean_longitude = np.mean(gps_array[:, 1])
@@ -73,6 +196,24 @@ class BaseOsmMap:
 
 
     def _attach_supported_tiles(self):
+        """
+        Attach supported tile layers from the provided tile options to the map object.
+
+        This method normalizes the default tile layer name and ensures that it is not
+        duplicated in the map by filtering out the default tile from the `tile_options`.
+        Then, it iterates over the filtered tile options and attaches each supported
+        tile layer to the map object using the folium library.
+
+        :raises KeyError: If any key in `tile_options` is invalid or not found.
+
+        :param self:
+            The instance of the class. It is expected to have the following attributes:
+                - tiles (str): The name of the default tile layer.
+                - tile_options (Dict[str, str]): A dictionary of tile layer names
+                  and their associated URLs.
+                - osm_map (folium.Map): The map object to which tile layers are attached.
+        :return: None
+        """
         # Normalize the default tile name to lowercase for comparison
         normalized_default_tile = self.tiles.lower()
 
@@ -84,6 +225,22 @@ class BaseOsmMap:
 
 
     def _get_bounding_box_from_points(self, margin=0.001):
+        """
+        Calculate a bounding box from GPS points with an additional margin.
+
+        This method processes the GPS points in the `self.gps_points` list
+        and calculates a geographical bounding box encompassing all
+        points with an optional margin added to its boundaries. The
+        bounding box is defined by the northernmost, southernmost,
+        easternmost, and westernmost boundaries.
+
+        :param margin: A float value that adds a margin to the bounding
+            box boundaries.
+            Defaults to 0.001.
+        :return: A tuple containing four float values in the order:
+            north (northernmost boundary), south (southernmost boundary),
+            east (easternmost boundary), and west (westernmost boundary).
+        """
         latitudes = [point[0] for point in self.gps_points]
         longitudes = [point[1] for point in self.gps_points]
 
@@ -96,6 +253,26 @@ class BaseOsmMap:
 
 
     def _extract_subgraph(self, north, south, east, west):
+        """
+        Extracts a subgraph from the OSMnx graph based on a specified bounding box.
+
+        This function takes the northern, southern, eastern, and western bounds to
+        define a geographic bounding box. It creates a polygon from these bounds and
+        identifies nodes within the graph that fall within this boundary. A new subgraph
+        is then created using these identified nodes. This functionality supports different
+        approaches depending on the OSMnx version.
+
+        :param north: The northern boundary of the bounding box.
+        :type north: float
+        :param south: The southern boundary of the bounding box.
+        :type south: float
+        :param east: The eastern boundary of the bounding box.
+        :type east: float
+        :param west: The western boundary of the bounding box.
+        :type west: float
+        :return: A subgraph extracted from the OSMnx graph containing nodes within the bounding box.
+        :rtype: networkx.Graph
+        """
         # Create a bounding box polygon
         # from osmnx v2 this is how it is done
         if ox.__version__ >= '2.0':
@@ -117,18 +294,45 @@ class BaseOsmMap:
 
     @abstractmethod
     def process_map(self):
+        """
+        This abstract method serves as a blueprint for processing a map. It is intentionally
+        left unimplemented and must be overridden in any concrete subclass. Subclasses should
+        provide their own specific logic for map processing by implementing this interface.
+
+        :return: None
+        """
         # this is to be implemented at the subclass level
         # implement here your specific map logic.
         ...
 
 
     def pre_process_map(self):
+        """
+        Pre-processes the map data.
+
+        This method is designed to be overridden in a subclass to perform specific
+        pre-processing procedures on map data. When overridden, the implementation
+        in the subclass must call `super().pre_process_map` first to inherit and
+        maintain the existing behavior of this base implementation.
+
+        :return: None
+        """
         # this is to be implemented at the subclass level
         # call super().pre_process_map first to inherit the following behaviour
         ...
 
 
     def _post_process_map(self):
+        """
+        Performs post-processing tasks on the map object to enhance its functionality
+        and ensure required adjustments or attributes are attached to it. This method
+        is mainly used internally to finalize map setup based on current configurations.
+
+        :raises AttributeError: This error is raised if one of the required attributes
+            is not properly initialized or missing during the processing.
+        :raises ValueError: This error is raised if provided bounds are invalid or
+            incompatible for fitting.
+        """
         self._attach_supported_tiles()
         self.add_tile_layer()
         self._add_fullscreen()
@@ -138,26 +342,76 @@ class BaseOsmMap:
 
 
     def add_tile_layer(self):
+        """
+        Adds a tile layer to the OpenStreetMap (OSM) representation.
+        This method is intended to handle the inclusion of additional
+        tile layers in the map. Subclasses should override this method,
+        call their custom logic, and conclude with a call to this base
+        implementation to add necessary controls to the map instance.
+
+        :rtype: None
+        :return: This method does not return any value.
+        """
         # Override in subclass and call super().add_tile_layer at the end
         folium.LayerControl().add_to(self.osm_map)
 
 
     def _add_fullscreen(self):
+        """
+        Adds a fullscreen functionality to the map if the fullscreen attribute is set.
+
+        This method checks whether the fullscreen mode is enabled by evaluating
+        the `fullscreen` attribute of the class. If `fullscreen` is set to True,
+        a Fullscreen instance is created with the specified position from
+        `fullscreen_position` and added to the map (`osm_map`).
+
+        :return: None
+        """
         if self.fullscreen:
             Fullscreen(position=self.fullscreen_position).add_to(self.osm_map)
 
 
     def _add_map_title(self):
+        """
+        Adds a title to the map if the title is specified.
+
+        This method checks if the attribute `map_html_title` is set. If it is,
+        it creates an HTML element containing the title and adds it to the
+        map's root HTML structure using Folium's API.
+
+        :raises AttributeError: If `osm_map` or `osm_map.get_root()` is not defined
+            or does not support the necessary operations.
+        """
         if self.map_html_title:
             self.osm_map.get_root().html.add_child(folium.Element(self.map_html_title))
 
 
     @staticmethod
     def _sanitize_html(input_html):
+        """
+        Sanitizes the provided HTML input by escaping special HTML characters.
+        This method ensures the input string is safe for use in HTML contexts
+        by converting characters like `<`, `>`, and `&` into their corresponding
+        HTML-safe representations.
+
+        :param input_html: The HTML string that needs to be sanitized.
+        :type input_html: str
+        :return: The sanitized version of the input HTML string with special
+            characters escaped.
+        :rtype: str
+        """
         return html.escape(input_html)
 
 
     def generate_map(self):
+        """
+        Generates a map by executing preprocessing, main processing, and
+        post-processing tasks sequentially. This method combines multiple
+        stages to prepare and retrieve the final map object.
+
+        :return: The completed and processed OpenStreetMap map instance
+        :rtype: object
+        """
         self.pre_process_map()
         self.process_map()
         self._post_process_map()