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

sibi_dst/df_helper/_parquet_artifact.py

@@ -9,11 +9,74 @@ from sibi_dst.utils import DateUtils
 
 
 class ParquetArtifact(DfHelper):
+    """
+    Class designed to manage Parquet data storage and retrieval using a specified
+    DataWrapper class for data processing. It provides functionality for loading,
+    updating, rebuilding, and generating Parquet files within a configurable
+    storage filesystem. The class ensures that all essential configurations and
+    filesystems are properly set up before operations.
+
+    Detailed functionality includes support for dynamically managing and generating
+    Parquet files based on time periods, with customizable options for paths,
+    filenames, date fields, and more. It is an abstraction for efficiently handling
+    storage tasks related to distributed or local file systems.
+
+    :ivar config: Configuration dictionary containing all configurable parameters
+                  for managing Parquet data storage, such as paths, filenames,
+                  and date ranges.
+    :type config: dict
+    :ivar df: Cached Dask DataFrame used to store and manipulate data loaded
+              from the Parquet file.
+    :type df: Optional[dask.dataframe.DataFrame]
+    :ivar data_wrapper_class: Class responsible for abstracting data processing
+                              operations required for Parquet file generation.
+    :type data_wrapper_class: type
+    :ivar date_field: Name of the field used to identify and process data by date.
+    :type date_field: Optional[str]
+    :ivar parquet_storage_path: Filesystem path to store Parquet files.
+    :type parquet_storage_path: Optional[str]
+    :ivar parquet_filename: Name of the Parquet file to be generated and managed.
+    :type parquet_filename: Optional[str]
+    :ivar parquet_start_date: Date string specifying the start date for data range
+                              processing.
+    :type parquet_start_date: Optional[str]
+    :ivar parquet_end_date: Date string specifying the end date for data range
+                            processing.
+    :type parquet_end_date: Optional[str]
+    :ivar filesystem_type: Type of the filesystem used for managing storage
+                           operations (e.g., `file`, `s3`, etc.).
+    :type filesystem_type: str
+    :ivar filesystem_options: Additional options for configuring the filesystem.
+    :type filesystem_options: dict
+    :ivar fs: Filesystem object used for storage operations.
+    :type fs: fsspec.AbstractFileSystem
+    """
     DEFAULT_CONFIG = {
         'backend': 'parquet'
     }
 
     def __init__(self, data_wrapper_class,  **kwargs):
+        """
+        Initializes an instance of the class with given configuration and validates
+        required parameters. Sets up the filesystem to handle storage, ensuring
+        necessary directories exist. The configuration supports a variety of options
+        to manage parquet storage requirements, including paths, filenames, and date
+        ranges.
+
+        :param data_wrapper_class: The class responsible for wrapping data to be managed
+                                   by this instance.
+        :type data_wrapper_class: type
+        :param kwargs: Arbitrary keyword arguments to override default configuration.
+                       Includes settings for `date_field`, `parquet_storage_path`,
+                       `parquet_filename`, `parquet_start_date`, `parquet_end_date`,
+                       `filesystem_type`, `filesystem_options`, and `fs`.
+        :type kwargs: dict
+
+        :raises ValueError: If any of the required configuration options
+                            (`date_field`, `parquet_storage_path`,
+                            `parquet_filename`, `parquet_start_date`,
+                            or `parquet_end_date`) are missing or not set properly.
+        """
         self.config = {
             **self.DEFAULT_CONFIG,
             **kwargs,
@@ -61,6 +124,11 @@ class ParquetArtifact(DfHelper):
         dw = DataWrapper(self.data_wrapper_class, **params)
         dw.process()
 
+    def __exit__(self, exc_type, exc_value, traceback):
+        # Ensure resources are cleaned up
+        if self.fs:
+            self.fs.close()
+
     def update_parquet(self, period: str = 'today', **kwargs) -> None:
         """Update the Parquet file with data from a specific period."""
         kwargs.update(self.parse_parquet_period(period=period))

sibi_dst/df_helper/_parquet_reader.py

@@ -7,6 +7,42 @@ from sibi_dst.df_helper import DfHelper
 
 
 class ParquetReader(DfHelper):
+    """
+    This class is a specialized helper for reading and managing Parquet files.
+
+    The `ParquetReader` class is designed to facilitate working with Parquet
+    datasets stored across different filesystems. It initializes the required
+    resources, ensures the existence of the specified Parquet directory,
+    and provides an abstraction to load the data into a Dask DataFrame.
+
+    The class requires configuration for the storage path and dates defining
+    a range of interest. It also supports various filesystem types through
+    `fsspec`.
+
+    :ivar config: Holds the final configuration for this instance, combining
+        `DEFAULT_CONFIG` with user-provided configuration.
+    :type config: dict
+    :ivar df: Stores the loaded Dask DataFrame after the `load()` method is
+        invoked. Initially set to None.
+    :type df: Optional[dd.DataFrame]
+    :ivar parquet_storage_path: The path to the Parquet storage directory.
+    :type parquet_storage_path: str
+    :ivar parquet_start_date: Start date for Parquet data selection. Must
+        be set in the configuration.
+    :type parquet_start_date: str
+    :ivar parquet_end_date: End date for Parquet data selection. Must be
+        set in the configuration.
+    :type parquet_end_date: str
+    :ivar filesystem_type: The type of filesystem the Parquet files are
+        stored on (e.g., "file", "s3").
+    :type filesystem_type: str
+    :ivar filesystem_options: Any additional options required for the
+        specified filesystem type.
+    :type filesystem_options: dict
+    :ivar fs: Instance of `fsspec` filesystem used to interact with the
+        Parquet storage.
+    :type fs: fsspec.AbstractFileSystem
+    """
     DEFAULT_CONFIG = {
         'backend': 'parquet'
     }
@@ -31,7 +67,10 @@ class ParquetReader(DfHelper):
         # Filesystem setup
         self.filesystem_type = filesystem_type
         self.filesystem_options = filesystem_options or {}
-        self.fs = fsspec.filesystem(self.filesystem_type, **self.filesystem_options)
+        self.fs = self.config.setdefault('fs', None)
+        if self.fs is None:
+            self.fs = fsspec.filesystem(self.filesystem_type, **self.filesystem_options)
+        self.config.setdefault('fs', self.fs)
 
         if not self.directory_exists():
             raise ValueError(f"{self.parquet_storage_path} does not exist")
@@ -48,3 +87,8 @@ class ParquetReader(DfHelper):
             return info['type'] == 'directory'
         except FileNotFoundError:
             return False
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        # Ensure resources are cleaned up
+        if self.fs:
+            self.fs.close()

sibi_dst/df_helper/backends/django/_db_connection.py

@@ -6,6 +6,27 @@ from ._sql_model_builder import DjangoSqlModelBuilder
 
 
 class DjangoConnectionConfig(BaseModel):
+    """
+    Represents a configuration for establishing a Django database connection.
+
+    This class is used for defining the configurations necessary to establish a Django
+    database connection. It supports dynamic model generation if the model is not
+    provided explicitly. It also validates the connection configuration to ensure it
+    is properly set up before being used.
+
+    :ivar live: Indicates whether the connection is live. Automatically set to False if
+        a table is provided without a pre-built model.
+    :type live: bool
+    :ivar connection_name: The name of the database connection to use. This is a mandatory
+        parameter and must be provided.
+    :type connection_name: str
+    :ivar table: The name of the database table to use. Required for dynamic model
+        generation when no model is provided.
+    :type table: str
+    :ivar model: The Django model that represents the database table. If not provided,
+        this can be generated dynamically by using the table name.
+    :type model: Any
+    """
     live: bool = False
     connection_name: str = None
     table: str = None
@@ -13,6 +34,18 @@ class DjangoConnectionConfig(BaseModel):
 
     @model_validator(mode="after")
     def check_model(self):
+        """
+        Validates and modifies the instance based on the provided attributes and conditions.
+        This method ensures that all required parameters are populated and consistent, and it
+        dynamically builds a model if necessary. The method also ensures the connection is
+        validated after the model preparation process.
+
+        :raises ValueError: If `connection_name` is not provided.
+        :raises ValueError: If `table` name is not specified when building the model dynamically.
+        :raises ValueError: If there are errors during the dynamic model-building process.
+        :raises ValueError: If `validate_connection` fails due to invalid configuration.
+        :return: The validated and potentially mutated instance.
+        """
         # connection_name is mandatory
         if self.connection_name is None:
             raise ValueError("Connection name must be specified")
@@ -38,7 +71,14 @@ class DjangoConnectionConfig(BaseModel):
         return self
 
     def validate_connection(self):
-        """Test if the database connection is valid by executing a simple query."""
+        """
+        Ensures the database connection is valid by performing a simple
+        query. Raises a ValueError if the connection is broken or if any
+        other exception occurs during the query.
+
+        :raises ValueError: If the connection to the database cannot be
+            established or if the query fails.
+        """
         try:
             # Perform a simple query to test the connection
             self.model.objects.using(self.connection_name).exists()

sibi_dst/df_helper/backends/django/_io_dask.py

@@ -11,6 +11,28 @@ from django.utils.encoding import force_str as force_text
 
 
 class ReadFrameDask:
+    """
+    Handles Django ORM QuerySet to Dask DataFrame conversion with support for field
+    type inference, chunked data retrieval, and verbose updates.
+
+    This class provides methods to efficiently convert a Django QuerySet into a
+    Dask DataFrame while preserving field types and incorporating additional
+    capabilities such as replacing fields with verbose choices or related object
+    information. The class design leverages static and class methods to maintain
+    flexibility and reusability for handling Django model fields and their data
+    types.
+
+    :ivar qs: The Django QuerySet to be converted into a Dask DataFrame.
+    :type qs: django.db.models.query.QuerySet
+    :ivar coerce_float: Whether to attempt to coerce numeric values to floats.
+    :type coerce_float: bool
+    :ivar chunk_size: The number of records to fetch and process per chunk from
+        the QuerySet.
+    :type chunk_size: int
+    :ivar verbose: If True, provides verbose updates during DataFrame creation
+        by replacing fields with readable representations (e.g., verbose names).
+    :type verbose: bool
+    """
     FieldDoesNotExist = (
         django.core.exceptions.FieldDoesNotExist
         if django.VERSION < (1, 8)
@@ -22,6 +44,22 @@ class ReadFrameDask:
             qs,
             **kwargs,
     ):
+        """
+        An initialization method for a class that sets class attributes based on provided
+        arguments or default values using the keyword arguments. The method allows
+        customization of behaviors like coercing data types, handling chunked operations,
+        and verbosity level during execution.
+
+        :param qs: A data source or query set for processing; its type is dependent
+            on the expected data being handled.
+        :param kwargs: Additional keyword arguments that may include:
+            - coerce_float: A boolean indicating whether floats should be coerced
+              during handling. Default is False.
+            - chunk_size: An integer value representing the size of chunks for
+              data processing. Default is 1000.
+            - verbose: A boolean to specify if verbose logging or output
+              should occur during execution. Default is True.
+        """
         self.qs = qs
         self.coerce_float = kwargs.setdefault("coerce_float", False)
         self.chunk_size = kwargs.setdefault("chunk_size", 1000)
@@ -29,6 +67,19 @@ class ReadFrameDask:
 
     @staticmethod
     def replace_from_choices(choices):
+        """
+        Provides a method to replace elements in a list of values based on a mapping of choices.
+
+        This static method generates a closure function that replaces items in a list by
+        looking up their corresponding values in a provided dictionary of choices. If an
+        item cannot be found in the dictionary, it is left unchanged.
+
+        :param choices:
+            Dictionary where keys are original values and values are their replacements.
+        :return:
+            A function that takes a list of values and replaces elements using the
+            provided choices dictionary.
+        """
         def inner(values):
             return [choices.get(v, v) for v in values]
 
@@ -36,10 +87,35 @@ class ReadFrameDask:
 
     @staticmethod
     def get_model_name(model):
+        """
+        Retrieves the model name from a given Django model instance.
+
+        This method accesses the `_meta.model_name` attribute of the provided
+        model object to extract and return the model's name.
+
+        :param model: A Django model instance from which the model name is
+            derived.
+        :type model: object
+        :return: The name of the model as a string.
+        :rtype: str
+        """
         return model._meta.model_name
 
     @staticmethod
     def get_related_model(field):
+        """
+        Retrieve the related model from the provided field.
+
+        This function determines the related model associated with the given field.
+        It checks various attributes commonly used to indicate relations in models and
+        retrieves the related model if present.
+
+        :param field: The field from which the related model is to be extracted.
+                      It must be an object that potentially contains attributes like
+                      `related_model` or `rel`.
+        :return: The related model associated with the provided field, or None if
+                 no such model is found.
+        """
         model = None
         if hasattr(field, "related_model") and field.related_model:
             model = field.related_model
@@ -49,12 +125,43 @@ class ReadFrameDask:
 
     @classmethod
     def get_base_cache_key(cls, model):
+        """
+        Generates a base cache key for caching purposes.
+
+        This method constructs a base cache key that can be used in conjunction with
+        Django models to uniquely identify cache entries. The key is formatted to
+        include the app label and model name, ensuring that cache entries are
+        namespaced accordingly.
+
+        :param model: A Django model instance for which the base cache key is generated.
+        :type model: Model
+        :return: The string template for the base cache key, where `%s` can be replaced
+                 with specific identifiers to create unique keys.
+        :rtype: str
+        """
         return (
             f"dask_{model._meta.app_label}_{cls.get_model_name(model)}_%s_rendering"
         )
 
     @classmethod
     def replace_pk(cls, model):
+        """
+        Generates a function that replaces primary keys in a pandas Series with their
+        corresponding cached values or database-retrieved representations.
+
+        The function uses a cache mechanism to retrieve pre-stored values for primary
+        keys in the series. If some primary keys are not found in the cache, it queries
+        the database for their representations, updates the cache, and replaces the
+        primary keys in the series accordingly.
+
+        :param model: The Django model class associated with the primary keys to be
+            processed.
+        :type model: Type[Model]
+
+        :return: A function that takes a pandas Series of primary keys as input and
+            returns a Series with replaced values based on cache or database retrieval.
+        :rtype: callable
+        """
         base_cache_key = cls.get_base_cache_key(model)
 
         def get_cache_key_from_pk(pk):
@@ -84,6 +191,20 @@ class ReadFrameDask:
 
     @classmethod
     def build_update_functions(cls, fieldnames, fields):
+        """
+        This method is responsible for building update functions based on the provided
+        fieldnames and fields. It performs validation for the field type, checks for
+        specific conditions such as `choices` or `ForeignKey` field types, and generates
+        a generator of update functions for the given fieldnames and fields.
+
+        :param fieldnames: A list of field names to be processed.
+        :type fieldnames: list[str]
+        :param fields: A list of field objects corresponding to the fieldnames.
+        :type fields: list[Field]
+        :return: A generator yielding tuples where the first element is a fieldname,
+                 and the second element is the corresponding update function or None.
+        :rtype: generator[tuple[str, Callable | None]]
+        """
         for fieldname, field in zip(fieldnames, fields):
             if not isinstance(field, Field):
                 yield fieldname, None
@@ -96,13 +217,38 @@ class ReadFrameDask:
 
     @classmethod
     def update_with_verbose(cls, df, fieldnames, fields):
+        """
+        Updates the provided dataframe by applying transformation functions to specified fields.
+        The method iterates over the provided field names and their corresponding functions, applying
+        each transformation function to its related column in the dataframe.
+
+        :param df: The input dataframe to be updated.
+        :param fieldnames: A list of field names in the dataframe that need to be updated.
+        :param fields: A list of transformation functions or mappings corresponding to the field names.
+        :return: The dataframe with updated fields.
+        """
         for fieldname, function in cls.build_update_functions(fieldnames, fields):
             if function is not None:
                 df[fieldname] = df[fieldname].map_partitions(lambda x: function(x))
 
     @classmethod
     def to_fields(cls, qs, fieldnames):
-        """Get fields from a queryset based on the given fieldnames."""
+        """
+        Converts field names from a queryset into corresponding field objects, resolving relationships
+        and related objects if necessary. This method is typically used to yield fully-resolved field
+        objects for further interaction.
+
+        :param qs: A QuerySet object from which the fields are resolved. This object provides access
+                   to the model and its metadata from which the fields are retrieved.
+        :type qs: QuerySet
+
+        :param fieldnames: A list of field name strings. These can include nested fields separated by
+                           double underscores (__) to denote relationships or subfields.
+        :type fieldnames: List[str]
+
+        :return: A generator that yields resolved field objects corresponding to the provided field names.
+        :rtype: Generator[Field, None, None]
+        """
         for fieldname in fieldnames:
             model = qs.model
             for fieldname_part in fieldname.split("__"):
@@ -125,6 +271,18 @@ class ReadFrameDask:
 
     @staticmethod
     def is_values_queryset(qs):
+        """
+        Determines whether the provided queryset is a values queryset.
+
+        This method checks if the `_iterable_class` attribute of the queryset corresponds
+        to `django.db.models.query.ValuesIterable`. If an exception occurs during the check,
+        the method returns `False`.
+
+        :param qs: The queryset to be checked.
+        :type qs: django.db.models.query.QuerySet
+        :return: A boolean indicating whether the queryset is a values queryset.
+        :rtype: bool
+        """
         try:
             return qs._iterable_class == django.db.models.query.ValuesIterable
         except:
@@ -132,7 +290,24 @@ class ReadFrameDask:
 
     @staticmethod
     def object_to_dict(obj, fields=None):
-        """Convert a Django model instance to a dictionary based on specified fields."""
+        """
+        Converts an object to a dictionary representation.
+
+        This static method transforms an object's attributes into a dictionary.
+        If no specific fields are provided, all attribute key-value pairs are
+        included. The "_state" attribute, if present, is safely removed in this
+        case. When specific fields are supplied, only those fields are included
+        in the resulting dictionary.
+
+        :param obj: The object to be serialized into a dictionary. This object
+            must have the `__dict__` attribute available.
+        :param fields: A list of strings representing the attribute names to
+            include in the dictionary. If None or not provided, all attributes
+            are included except for "_state".
+        :return: A dictionary representation of the object's attributes. If the
+            provided object is None, an empty dictionary is returned.
+        :rtype: dict
+        """
         if obj is None:
             return {}  # Return an empty dictionary if obj is None
         if not fields:
@@ -142,7 +317,25 @@ class ReadFrameDask:
 
     @staticmethod
     def infer_dtypes_from_django(qs):
-        """Infers Dask data types based on Django queryset model fields, with support for nullable integers."""
+        """
+        Infer dtypes from a Django QuerySet model and annotated fields.
+
+        This method infers the appropriate data types (dtypes) for a given
+        Django QuerySet (`qs`) based on the fields defined in its model and
+        any annotated fields included in the QuerySet. The function maps
+        Django model field types to corresponding dtypes compatible with
+        Dask or Pandas dataframes.
+
+        - Fields in the model are identified through their metadata.
+        - Reverse relationships and non-concrete fields are ignored.
+        - Annotated fields are processed separately and default to object
+          dtype if their type cannot be determined.
+
+        :param qs: Django QuerySet whose model is used to infer dtypes.
+        :type qs: QuerySet
+        :return: A mapping of field names to inferred dtypes.
+        :rtype: dict
+        """
         django_to_dask_dtype = {
             'AutoField': 'Int64',  # Use nullable integer
             'BigAutoField': 'Int64',
@@ -189,6 +382,21 @@ class ReadFrameDask:
         return dtypes
 
     def read_frame(self, fillna_value=None):
+        """
+        Reads a Django QuerySet and returns a dask DataFrame by iterating over the QuerySet in chunks. It
+        handles data type inference, missing values, timezone awareness, and creates partitions to form a
+        single dask DataFrame efficiently.
+
+        This method includes functionality for managing missing values, inferring data types from Django fields,
+        and handling timezone-aware datetime objects. It processes data in chunks to optimize memory usage and
+        supports converting chunks into pandas DataFrames before combining them into a unified dask DataFrame.
+
+        :param fillna_value: The value to fill NaN values in the DataFrame. If None, NaNs are not filled.
+        :type fillna_value: Any
+        :return: A dask DataFrame constructed from the QuerySet after processing and combining all
+                 its partitions.
+        :rtype: dask.dataframe.DataFrame
+        """
         qs = self.qs
         coerce_float = self.coerce_float
         verbose = self.verbose

sibi_dst/df_helper/backends/django/_load_from_db.py

@@ -10,9 +10,57 @@ from sibi_dst.utils import Logger
 
 
 class DjangoLoadFromDb:
+    """
+    Handles loading data from a Django database into a Dask DataFrame, with support for filtering
+    and column type conversion.
+
+    This class is designed to interface with Django ORM models, allowing data querying and mapping
+    Django model fields to Dask DataFrame columns. It accommodates filtering logic provided via
+    parameters and ensures that excessive data is not accidentally loaded when no filters are applied.
+
+    :ivar connection_config: Configuration for the database connection, including the Django model
+        and connection details.
+    :type connection_config: Any
+    :ivar query_config: Configuration for the query, including the number of records to retrieve.
+    :type query_config: Any
+    :ivar params_config: Configuration for query parameters, including filters and DataFrame options.
+    :type params_config: Any
+    :ivar logger: Logger instance used for debugging and reporting runtime information.
+    :type logger: Logger
+    :ivar debug: Indicates whether debug mode is active for verbose logging.
+    :type debug: bool
+    :ivar df: Dask DataFrame to hold the loaded query results.
+    :type df: dd.DataFrame
+    """
     df: dd.DataFrame
 
     def __init__(self, db_connection, db_query, db_params, logger, **kwargs):
+        """
+        This class initializes and configures a database connection along with the
+        specified query and parameters. It ensures the required model is defined
+        and sets up logging. Additional configurations can be provided via keyword
+        arguments.
+
+        :param db_connection: The configuration object representing the database
+            connection details.
+        :type db_connection: Any
+        :param db_query: The configuration or object for defining the database
+            query.
+        :type db_query: Any
+        :param db_params: The configuration or object for defining parameters
+            to be passed to the query.
+        :type db_params: Any
+        :param logger: An instance of a logging class used to log debug or
+            error messages, defaults to the class's default logger if not
+            specified.
+        :type logger: Any, optional
+        :param kwargs: Additional keyword arguments for custom configurations
+            like `debug`. These can include optional parameters to be parsed by
+            `params_config`.
+        :type kwargs: dict
+        :raises ValueError: If no model is specified in the given database
+            connection configuration.
+        """
         self.connection_config = db_connection
         self.debug = kwargs.pop('debug', False)
         self.logger = logger or Logger.default_logger(logger_name=self.__class__.__name__)
@@ -27,11 +75,35 @@ class DjangoLoadFromDb:
         self.params_config.parse_params(kwargs)
 
     def build_and_load(self):
+        """
+        Builds and loads data into a DataFrame by invoking the `_build_and_load` method.
+        This is a utility method designed to perform specific operations for constructing
+        and preparing the data. The loaded data will then be assigned to the instance
+        attribute `df`.
+
+        :param self: Reference to the current instance of the class.
+        :type self: object
+
+        :return: DataFrame containing the built and loaded data.
+        """
         self.df = self._build_and_load()
         # self.df = self._convert_columns(self.df)
         return self.df
 
     def _build_and_load(self) -> dd.DataFrame:
+        """
+        Builds and loads a Dask DataFrame based on the provided query and configuration. This method queries the data
+        model using the specified connection, applies filters if provided, and converts the query result into a
+        Dask DataFrame. If filters are not provided, only the first `n_records` entries are processed to avoid
+        unintentionally loading the entire table.
+
+        :raises Exception: If an error occurs while loading the query, it logs the error and initializes an
+            empty Dask DataFrame.
+
+        :return: A Dask DataFrame containing the queried data. If no filters or valid results are provided,
+            an empty Dask DataFrame is returned.
+        :rtype: dd.DataFrame
+        """
         query = self.connection_config.model.objects.using(self.connection_config.connection_name)
         if not self.params_config.filters:
             # IMPORTANT: if no filters are provided show only the first n_records
@@ -54,6 +126,22 @@ class DjangoLoadFromDb:
 
     @staticmethod
     def __build_query_objects(filters: dict, use_exclude: bool):
+        """
+        Constructs and returns a composite Q object based on the provided `filters` dictionary.
+        The function determines whether to include or exclude the filter conditions in the final
+        query based on the `use_exclude` parameter. If `use_exclude` is False, the filters are
+        directly added to the composite Q object. If `use_exclude` is True, the negation of
+        the filters is added instead.
+
+        :param filters: A dictionary containing filter conditions where keys represent field names
+            and values represent the conditions to be applied.
+        :type filters: dict
+        :param use_exclude: A boolean flag determining whether to exclude (`True`) or include
+            (`False`) the provided filter conditions.
+        :type use_exclude: bool
+        :return: A composite Q object that aggregates the filters based on the given conditions.
+        :rtype: Q
+        """
         q_objects = Q()
         for key, value in filters.items():
             if not use_exclude:
@@ -64,10 +152,17 @@ class DjangoLoadFromDb:
 
     def _convert_columns(self, df: dd.DataFrame) -> dd.DataFrame:
         """
-        Convert the data types of columns in a Dask DataFrame based on the field type in the Django model.
+        [DEPRECATED] Convert the data types of columns in a Dask DataFrame based on the field type in the Django model.
+
+        This function is deprecated and will be removed in a future release. The method converts the data
+        types of columns in a Dask DataFrame to match their corresponding field types defined in a Django model.
+        It emits warnings and logs deprecation notes. The conversions are applied lazily and partition-wise
+        to support distributed computation.
 
         :param df: Dask DataFrame whose columns' data types are to be converted.
+        :type df: dd.DataFrame
         :return: Dask DataFrame with converted column data types.
+        :rtype: dd.DataFrame
         """
         """
             [DEPRECATED] Convert the data types of columns in a Dask DataFrame based on the field type in the Django model.