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

sibi_dst/df_helper/_df_helper.py

@@ -91,7 +91,7 @@ class DfHelper:
         self.filesystem_options = kwargs.pop('filesystem_options', {})
         kwargs.setdefault("live", True)
         kwargs.setdefault("logger", self.logger)
-        kwargs.setdefault("fs", fsspec.filesystem('file'))
+        self.fs =kwargs.setdefault("fs", fsspec.filesystem('file'))
         self.__post_init(**kwargs)
 
     def __str__(self):
@@ -208,6 +208,18 @@ class DfHelper:
                 return asyncio.run(self.__load_from_http(**options))
 
     def __load_from_sqlalchemy(self, **options):
+        """
+        Loads data from an SQLAlchemy database source into a dataframe. The method processes
+        the loaded data and applies post-processing to transform it into the desired structure.
+        If the operation fails, an empty pandas DataFrame is created as a fallback.
+
+        :param options: Additional keyword arguments to configure the data loading process.
+            These options can include configurations such as 'debug' and other parameters
+            required by the `SqlAlchemyLoadFromDb` class.
+        :type options: dict
+        :return: A dataframe containing the data loaded from the SQLAlchemy database.
+        :rtype: dask.dataframe.DataFrame
+        """
         try:
             options.setdefault("debug", self.debug)
             db_loader = SqlAlchemyLoadFromDb(
@@ -228,6 +240,17 @@ class DfHelper:
         return self.df
 
     def __load_from_db(self, **options) -> Union[pd.DataFrame, dd.DataFrame]:
+        """
+        Loads data from a Django database using a specific backend query mechanism. Processes the loaded data
+        and applies further post-processing before returning the dataframe. If the operation fails, an
+        empty dataframe with a single partition is returned instead.
+
+        :param options: Additional settings for the database loading process, which include optional configurations
+            like debug mode, among others.
+        :type options: dict
+        :return: A dataframe containing the loaded data either as a Pandas or Dask dataframe.
+        :rtype: Union[pd.DataFrame, dd.DataFrame]
+        """
         try:
             options.setdefault("debug", self.debug)
             db_loader = DjangoLoadFromDb(
@@ -248,7 +271,18 @@ class DfHelper:
         return self.df
 
     async def __load_from_http(self, **options) -> Union[pd.DataFrame, dd.DataFrame]:
-        """Delegate asynchronous HTTP data loading to HttpDatabackend plugin."""
+        """
+        Loads data asynchronously from an HTTP source using the configured HTTP plugin.
+        If the HTTP plugin is not properly configured, this method logs a debug message and
+        returns an empty Dask DataFrame. If an exception occurs during data fetching, the error
+        is logged and an empty Dask DataFrame with one partition is returned.
+
+        :param options: Additional keyword arguments that are passed to the HTTP plugin for
+                        fetching the data.
+        :returns: A DataFrame object that can either be a pandas or a Dask DataFrame. When the
+                  fetching operation fails, it defaults to returning an empty Dask DataFrame
+                  with a single partition.
+        """
         if not self.backend_http:
             self.logger.debug("HTTP plugin not configured properly.")
             return dd.from_pandas(pd.DataFrame(), npartitions=1)
@@ -339,12 +373,45 @@ class DfHelper:
 
             self.logger.debug("Processing of loaded data completed.")
 
-    def save_to_parquet(self, parquet_filename: Optional[str] = None):
-        ps = ParquetSaver(self.df, self.parquet_storage_path, self.logger)
+    def save_to_parquet(self, parquet_filename: Optional[str] = None, **kwargs):
+        """
+        Save the dataframe result to a Parquet file using specified configurations.
+
+        This method leverages the ParquetSaver class to store the dataframe result
+        into a Parquet file. It also provides functionality for overriding the default
+        filesystem (`fs`) and storage path (`parquet_storage_path`). The method logs
+        details about the saving operation for debugging purposes.
+
+        :param parquet_filename: The name of the Parquet file to save the dataframe to.
+                                  If not provided, a default name will be used.
+        :param kwargs: Additional arguments to customize the saving process. These may
+                       include:
+                       - `fs`: Filesystem to be used for saving Parquet files. If not
+                         provided, defaults to the instance's filesystem attribute.
+                       - `parquet_storage_path`: The root path in the filesystem where
+                         Parquet files should be saved. If not provided, defaults to
+                         the instance's attribute for storage path.
+        :return: None
+        """
+        fs = kwargs.pop('fs', self.fs)
+        parquet_storage_path = kwargs.pop('parquet_storage_path', self.parquet_storage_path)
+        ps = ParquetSaver(df_result=self.df, parquet_storage_path=parquet_storage_path, logger=self.logger, fs=fs)
         ps.save_to_parquet(parquet_filename)
-        self.logger.debug(f"Parquet saved to {parquet_filename} in parquet storage: {self.parquet_storage_path}.")
+        self.logger.debug(f"Parquet saved to {parquet_filename} in parquet storage: {parquet_storage_path}.")
 
     def save_to_clickhouse(self, **credentials):
+        """
+        Saves the current DataFrame to ClickHouse using the provided credentials. This
+        method first checks if the DataFrame is empty. If it is empty, the method logs
+        a debug message and does not proceed with saving. Otherwise, it initializes
+        a ClickHouseWriter instance and uses it to save the DataFrame to ClickHouse,
+        logging a debug message upon successful completion.
+
+        :param credentials: Credentials required to connect to ClickHouse as keyword
+            arguments.
+        :type credentials: dict
+        :return: None
+        """
         if self.df.map_partitions(len).compute().sum() == 0:
             self.logger.debug("Cannot write to clickhouse since Dataframe is empty")
             return
@@ -353,6 +420,21 @@ class DfHelper:
         self.logger.debug("Save to ClickHouse completed.")
 
     def __load_from_parquet(self, **options) -> Union[pd.DataFrame, dd.DataFrame]:
+        """
+        Loads data from parquet files into a DataFrame, applies provided filters, and handles exceptions.
+
+        This method leverages a backend-specific implementation to load data from parquet files into a
+        DataFrame. If additional options are provided and the data is successfully loaded, filters are
+        applied to the DataFrame using a filter handler. Errors during this process are handled gracefully
+        by logging the issue and returning an empty Dask DataFrame.
+
+        :param options: A dictionary of filter options to be applied to the DataFrame.
+        :type options: dict
+
+        :return: A DataFrame containing the loaded and filtered data. If the operation fails, an empty
+            Dask DataFrame is returned.
+        :rtype: Union[pd.DataFrame, dd.DataFrame]
+        """
         try:
             self.df = self.backend_parquet.load_files()
             if options and self.df is not None:
@@ -368,6 +450,27 @@ class DfHelper:
             return dd.from_pandas(pd.DataFrame(), npartitions=1)
 
     def load_period(self, **kwargs):
+        """
+        Loads a period with specified parameters.
+
+        This method acts as a wrapper around the private ``__load_period`` method. It
+        accepts arbitrary keyword arguments that are passed directly to the private
+        method for execution. The purpose of allowing keyword arguments is to permit
+        flexible configuration or parameterization for loading a specific period, based
+        on the internal implementation of the private ``__load_period`` method.
+
+        Note:
+        The arguments and return values are entirely determined by the private
+        method's behavior. This method is intentionally designed to mask details
+        of the internal logic behind the abstraction.
+
+        :param kwargs: Arbitrary keyword arguments to parameterize the internal logic
+            of loading a period. The specific keys and values expected by the
+            ``__load_period`` method depend on its own internal implementation.
+        :return: The result of calling the private ``__load_period`` method with the
+            provided keyword arguments. The return type is dependent on the internal
+            implementation of ``__load_period``.
+        """
         return self.__load_period(**kwargs)
 
     def __load_period(self, **kwargs):

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,

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'
     }

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