winidjango 1.0.4__py3-none-any.whl → 2.0.31__py3-none-any.whl

winidjango/__init__.py

@@ -1,6 +1,7 @@
 """__init__ module."""
 
 import logging
+from pathlib import Path
 
 import django
 import django_stubs_ext
@@ -11,8 +12,14 @@ logger = logging.getLogger(__name__)
 django_stubs_ext.monkeypatch()
 logger.info("Monkeypatched django-stubs")
 
+
+logger = logging.getLogger(__name__)
+
+
+# Configure Django settings for tests if not already configured
 if not settings.configured:
-    logger.info("Configuring minimal django settings")
+    logger.info("Configuring minimal django settings for tests")
+    installed_apps = ["tests"] if Path("tests").exists() else []
     settings.configure(
         DATABASES={
             "default": {
@@ -20,6 +27,8 @@ if not settings.configured:
                 "NAME": ":memory:",
             }
         },
-        INSTALLED_APPS=["tests"],
+        INSTALLED_APPS=installed_apps,
+        USE_TZ=True,
     )
     django.setup()
+    logger.info("Django setup complete")

winidjango/dev/configs/configs.py

@@ -2,3 +2,17 @@
 
 All subclasses of ConfigFile in the configs package are automatically called.
 """
+
+from pyrig.dev.configs.pyproject import PyprojectConfigFile as PyrigPyprojectConfigFile
+
+
+class PyprojectConfigFile(PyrigPyprojectConfigFile):
+    """Pyproject.toml config file."""
+
+    @classmethod
+    def get_standard_dev_dependencies(cls) -> list[str]:
+        """Get the standard dev dependencies."""
+        dev_dependencies = super().get_standard_dev_dependencies()
+        dev_dependencies.extend(["django-stubs", "pytest-django"])
+
+        return sorted(dev_dependencies)

winidjango/dev/tests/fixtures/__init__.py

@@ -0,0 +1 @@
+"""__init__ module."""

winidjango/main.py

@@ -1,18 +1,8 @@
 """Main entrypoint for the project."""
 
-import pyrig
-
 
 def main() -> None:
     """Main entrypoint for the project."""
-    msg = f"""Add your projects entrypoint code to this function.
-This function is automatically added to your cli by {pyrig.__name__}.
-You can call it with
-`poetry run your-pkg-name main`
-or via
-`python -m your-pkg-name`.
-"""
-    raise NotImplementedError(msg)
 
 
 if __name__ == "__main__":

winidjango/resources/__init__.py

@@ -0,0 +1 @@
+"""__init__ module."""

winidjango/src/__init__.py

@@ -1,3 +1,14 @@
-"""src package."""
+"""src package.
 
-"""__init__ module."""
+This package exposes the project's internal modules used by the
+command-line utilities and database helpers. It exists primarily so
+that code under `winidjango/src` can be imported using the
+`winidjango.src` package path in other modules and tests.
+
+The package itself contains the following subpackages:
+- `commands` - management command helpers and base classes
+- `db` - database utilities and model helpers
+
+Consumers should import the specific submodules they need rather than
+relying on side effects from this package's import-time execution.
+"""

winidjango/src/commands/__init__.py

@@ -1 +1,8 @@
-"""__init__ module."""
+"""Utilities and base classes for management commands.
+
+The `commands` package contains base command classes and helpers used to
+implement Django management commands in the project. Subpackages and
+modules under `commands` provide reusable patterns for argument handling,
+logging and common command behaviors so that individual commands can focus
+on their business logic.
+"""

winidjango/src/commands/base/__init__.py

@@ -1 +1,7 @@
-"""__init__ module."""
+"""Base helpers and abstractions for management commands.
+
+This package provides a common abstract base class used by project
+management commands. The base class centralizes argument handling,
+standard options (dry-run, batching, timeouts, etc.) and integrates
+logging behavior used throughout the commands package.
+"""

winidjango/src/commands/base/base.py

@@ -1,8 +1,11 @@
-"""Command utilities for Django.
-
-This module provides utility functions for working with Django commands,
-including command execution and output handling. These utilities help with
-managing and automating Django command-line tasks.
+"""Utilities and an abstract base class for Django management commands.
+
+This module defines :class:`ABCBaseCommand`, a reusable abstract base
+that combines Django's ``BaseCommand`` with the project's logging
+mixins and standard argument handling. The base class implements a
+template method pattern so concrete commands only need to implement the
+abstract extension points for providing command-specific arguments and
+business logic.
 """
 
 import logging
@@ -17,41 +20,19 @@ logger = logging.getLogger(__name__)
 
 
 class ABCBaseCommand(ABCLoggingMixin, BaseCommand):
-    """Abstract base class for Django management commands with logging and validation.
-
-    This class serves as a foundation for creating Django management commands that
-    require abstract method implementation enforcement and automatic logging.
-    It combines Django's BaseCommand with ABCImplementationLoggingMixin to provide
-    both command functionality and development-time validation.
-
-    The class implements a template method pattern where common argument handling
-    and execution flow are managed by final methods, while specific implementations
-    are defined through abstract methods that subclasses must implement.
-
-    Key Features:
-        - Automatic logging of method calls with performance tracking
-        - Compile-time validation that all abstract methods are implemented
-        - Structured argument handling with base and custom arguments
-        - Template method pattern for consistent command execution flow
-
-    Inheritance Order:
-        The order of inheritance is critical: ABCImplementationLoggingMixin must
-        come before BaseCommand because Django's BaseCommand doesn't call
-        super().__init__(), so the mixin's metaclass initialization must happen
-        first to ensure proper class construction.
-
-    Example:
-        >>> class MyCommand(ABCBaseCommand):
-        ...     def add_command_arguments(self, parser):
-        ...         parser.add_argument('--my-option', help='Custom option')
-        ...
-        ...     def handle_command(self, *args, **options):
-        ...         self.stdout.write('Executing my command')
-
-    Note:
-        - All methods are automatically logged with performance tracking
-        - Subclasses must implement add_command_arguments and handle_command
-        - The @final decorator prevents overriding of template methods
+    """Abstract base class for management commands with logging and standard options.
+
+    The class wires common behavior such as base arguments (dry-run,
+    batching, timeouts) and provides extension points that concrete
+    commands must implement: :meth:`add_command_arguments` and
+    :meth:`handle_command`.
+
+    Notes:
+        - Inheritance order matters: the logging mixin must precede
+          ``BaseCommand`` so mixin initialization occurs as expected.
+        - The base class follows the template method pattern; concrete
+          commands should not override :meth:`add_arguments` or
+          :meth:`handle` but implement the abstract hooks instead.
     """
 
     class Options:
@@ -67,25 +48,14 @@ class ABCBaseCommand(ABCLoggingMixin, BaseCommand):
         PROCESSES = "processes"
 
     def add_arguments(self, parser: ArgumentParser) -> None:
-        """Configure command-line arguments for the Django management command.
-
-        This method implements the template method pattern by first adding common
-        base arguments that are used across multiple commands, then delegating
-        to the abstract add_command_arguments method for command-specific arguments.
+        """Configure command-line arguments for the command.
 
-        The @final decorator prevents subclasses from overriding this method,
-        ensuring consistent argument handling across all commands while still
-        allowing customization through the abstract method.
+        Adds common base arguments (dry-run, force, delete, timeout,
+        batching and concurrency options) and then delegates to
+        :meth:`add_command_arguments` for command-specific options.
 
         Args:
-            parser (ArgumentParser): Django's argument parser instance used to
-                define command-line options and arguments for the command.
-
-        Note:
-            - This method is final and cannot be overridden by subclasses
-            - Common arguments are added first via _add_arguments()
-            - Custom arguments are added via the abstract add_command_arguments()
-            - Subclasses must implement add_command_arguments() for specific needs
+            parser (ArgumentParser): The argument parser passed by Django.
         """
         # add base args that are used in most commands
         self.base_add_arguments(parser)
@@ -94,24 +64,10 @@ class ABCBaseCommand(ABCLoggingMixin, BaseCommand):
         self.add_command_arguments(parser)
 
     def base_add_arguments(self, parser: ArgumentParser) -> None:
-        """Add common command-line arguments used across multiple commands.
-
-        This method defines base arguments that are commonly used across different
-        Django management commands. These arguments provide standard functionality
-        like dry-run mode, verbosity control, and batch processing options.
-
-        The method is final to ensure consistent base argument handling, while
-        command-specific arguments are handled through the abstract
-        add_command_arguments method.
+        """Add the project's standard command-line arguments to ``parser``.
 
         Args:
-            parser (ArgumentParser): Django's argument parser instance to which
-                common arguments should be added.
-
-        Note:
-            - Provides standard arguments for dry-run, verbosity, and batch processing
-            - The @final decorator prevents subclasses from overriding this method
-            - Command-specific arguments should be added via add_command_arguments()
+            parser (ArgumentParser): The argument parser passed by Django.
         """
         parser.add_argument(
             f"--{self.Options.DRY_RUN}",
@@ -168,138 +124,61 @@ class ABCBaseCommand(ABCLoggingMixin, BaseCommand):
 
     @abstractmethod
     def add_command_arguments(self, parser: ArgumentParser) -> None:
-        """Add command-specific arguments to the argument parser.
-
-        This abstract method must be implemented by subclasses to define
-        command-specific command-line arguments. It is called after common
-        base arguments are added, allowing each command to customize its
-        argument interface while maintaining consistent base functionality.
+        """Define command-specific arguments.
 
-        Subclasses should use this method to add arguments specific to their
-        command's functionality, such as file paths, configuration options,
-        or operational flags.
+        Implement this hook to add options and positional arguments that are
+        specific to the concrete management command.
 
         Args:
-            parser (ArgumentParser): Django's argument parser instance to which
-                command-specific arguments should be added.
-
-        Example:
-            >>> def add_command_arguments(self, parser):
-            ...     parser.add_argument(
-            ...         '--input-file',
-            ...         type=str,
-            ...         required=True,
-            ...         help='Path to input file'
-            ...     )
-            ...     parser.add_argument(
-            ...         '--output-format',
-            ...         choices=['json', 'csv', 'xml'],
-            ...         default='json',
-            ...         help='Output format for results'
-            ...     )
-
-        Note:
-            - This method is abstract and must be implemented by subclasses
-            - Called after _add_arguments() adds common base arguments
-            - Should focus on command-specific functionality only
+            parser (ArgumentParser): The argument parser passed by Django.
         """
 
     def handle(self, *args: Any, **options: Any) -> None:
-        """Execute the Django management command using template method pattern.
-
-        This method implements the main execution flow for the command by first
-        calling common handling logic through _handle(), then delegating to
-        the command-specific implementation via handle_command().
+        """Orchestrate command execution.
 
-        The @final decorator ensures this execution pattern cannot be overridden,
-        maintaining consistent command execution flow while allowing customization
-        through the abstract handle_command method.
+        Performs shared pre-processing by calling :meth:`base_handle` and
+        then delegates to :meth:`handle_command` which must be implemented
+        by subclasses.
 
         Args:
-            *args: Positional arguments passed from Django's command execution.
-            **options: Keyword arguments containing parsed command-line options
-                and their values as defined by add_arguments().
-
-        Note:
-            - This method is final and cannot be overridden by subclasses
-            - Common handling logic is executed first via _handle()
-            - Command-specific logic is executed via abstract handle_command()
-            - All method calls are automatically logged with performance tracking
+            *args: Positional arguments forwarded from Django.
+            **options: Parsed command-line options.
         """
         self.base_handle(*args, **options)
         self.handle_command()
 
     def base_handle(self, *args: Any, **options: Any) -> None:
-        """Execute common handling logic shared across all commands.
+        """Perform common pre-processing for commands.
 
-        This method is intended to contain common processing logic that should
-        be executed before command-specific handling. Currently, it serves as
-        a placeholder for future common functionality such as logging setup,
-        validation, or shared initialization.
-
-        The method is final to ensure consistent common handling across all
-        commands, while command-specific logic is handled through the abstract
-        handle_command method.
+        Stores the incoming arguments and options on the instance for use
+        by :meth:`handle_command` and subclasses.
 
         Args:
-            *args: Positional arguments passed from Django's command execution.
-                Currently unused but reserved for future common processing.
-            **options: Keyword arguments containing parsed command-line options.
-                Currently unused but reserved for future common processing.
-
-        Note:
-            - Examples might include logging setup, database connection validation, etc.
-            - The @final decorator prevents subclasses from overriding this method
-            - Called before handle_command() in the template method pattern
+            *args: Positional arguments forwarded from Django.
+            **options: Parsed command-line options.
         """
         self.args = args
         self.options = options
 
     @abstractmethod
     def handle_command(self) -> None:
-        """Execute command-specific logic and functionality.
+        """Run the command-specific behavior.
 
-        This abstract method must be implemented by subclasses to define the
-        core functionality of the Django management command. It is called after
-        common handling logic is executed, allowing each command to implement
-        its specific business logic while benefiting from shared infrastructure.
+        This abstract hook should be implemented by concrete commands to
+        perform the command's main work. Implementations should read
+        ``self.args`` and ``self.options`` which were set in
+        :meth:`base_handle`.
+        """
 
-        This method should contain the main logic that the command is designed
-        to perform, such as data processing, database operations, file manipulation,
-        or any other command-specific tasks.
+    def get_option(self, option: str) -> Any:
+        """Retrieve a parsed command option by key.
 
         Args:
-            None, args and options are stored in self.args and self.options
-
-        Example:
-            >>> def handle_command(self):
-            ...     args, options = self.args, self.options
-            ...     input_file = options['input_file']
-            ...     dry_run = options['dry_run']  # Base argument
-            ...     batch_size = options['batch_size']  # Base argument
-            ...     quiet = options['quiet']  # Base argument
-            ...
-            ...     if dry_run:
-            ...         self.stdout.write('Dry run mode - no changes will be made')
-            ...
-            ...     if not quiet:
-            ...         msg = f'Processing {input_file} in batches of {batch_size}'
-            ...         self.stdout.write(msg)
-            ...
-            ...     # Perform command-specific operations
-            ...     self.process_file(input_file, batch_size, dry_run)
-            ...
-            ...     if not quiet:
-            ...         self.stdout.write('Command completed successfully')
-
-        Note:
-            - This method is abstract and must be implemented by subclasses
-            - Called after _handle() executes common logic
-            - Should contain the main functionality of the command
-            - All method calls are automatically logged with performance tracking
-            - Use self.stdout.write() for output instead of print()
-        """
+            option (str): The option key to retrieve from ``self.options``.
 
-    def get_option(self, option: str) -> Any:
-        """Get an option from the command options."""
+        Returns:
+            Any: The value for the requested option. If the option is not
+                present a ``KeyError`` will be raised (matching how Django
+                exposes options in management commands).
+        """
         return self.options[option]

winidjango/src/commands/import_data.py

@@ -1,6 +1,20 @@
-"""Import command for Django.
-
-A base class for importing data from a source to the database.
+"""Import command base class and utilities.
+
+This module defines a reusable base command for importing tabular data
+into Django models. Implementations should provide a concrete source
+ingestion (for example, reading from CSV or an external API), a
+cleaning/normalization step implemented by a `CleaningDF` subclass, and
+mapping logic that groups cleaned data into model instances that can be
+bulk-created.
+
+The base command centralizes the typical flow:
+1. Read raw data (``handle_import``)
+2. Wrap and clean the data using a `CleaningDF` subclass
+3. Convert the cleaned frame into per-model bulks
+4. Persist bulks using the project's bulk create helpers
+
+Using this base class ensures a consistent import lifecycle and
+reduces duplicated boilerplate across different import implementations.
 """
 
 import logging
@@ -18,49 +32,72 @@ logger = logging.getLogger(__name__)
 
 
 class ImportDataBaseCommand(ABCBaseCommand):
-    """Base class for importing data from a source to the database.
+    """Abstract base for data-import Django management commands.
+
+    Subclasses must implement the ingestion, cleaning-class selection,
+    and mapping of cleaned rows to Django model instances. The base
+    implementation wires these pieces together and calls the project's
+    bulk creation helper to persist the data.
 
-    This class provides a standardized way to import data from a source to the database.
-    It uses the cleaning df cls to clean the data and then imports it to the database.
+    Implementors typically only need to override the three abstract
+    methods documented below.
     """
 
     @abstractmethod
     def handle_import(self) -> pl.DataFrame:
-        """Handle importing the data from the source.
+        """Read raw data from the import source.
 
-        The data is possibly dirty and the job of this class to standardize the process
-        of importing the data.
+        This method should read data from whatever source the concrete
+        command targets (files, remote APIs, etc.) and return it as a
+        ``polars.DataFrame``. No cleaning should be performed here;
+        cleaning is handled by the cleaning `CleaningDF` returned from
+        ``get_cleaning_df_cls``.
+
+        Returns:
+            pl.DataFrame: Raw (uncleaned) tabular data to be cleaned and
+                mapped to model instances.
         """
 
     @abstractmethod
     def get_cleaning_df_cls(self) -> type[CleaningDF]:
-        """You will define a child of a cleaning df cls and return it.
+        """Return the `CleaningDF` subclass used to normalize the data.
+
+        The returned class will be instantiated with the raw DataFrame
+        returned from :meth:`handle_import` and must provide the
+        transformations required to prepare data for mapping into model
+        instances.
 
-        The cleaning df cls is responsible for cleaning the data.
-        See: winiutils.src.data.dataframe.cleaning.CleaningDF
+        Returns:
+            type[CleaningDF]: A subclass of ``CleaningDF`` that performs
+                the necessary normalization and validation.
         """
 
     @abstractmethod
     def get_bulks_by_model(
         self, df: pl.DataFrame
     ) -> dict[type[Model], Iterable[Model]]:
-        """Get the bulks of data to import by model.
+        """Map the cleaned DataFrame to model-instance bulks.
 
-        The data is cleaned and ready to be imported to the database.
-        You need to return a dictionary mapping model classes to lists of instances
-        to create.
+        The implementation should inspect the cleaned DataFrame and
+        return a mapping where keys are Django model classes and values
+        are iterables of unsaved model instances (or dataclass-like
+        objects accepted by the project's bulk-creation utility).
 
         Args:
-            df (pl.DataFrame): The cleaned data to import.
-                Is passed from handle_command() automatically.
+            df (pl.DataFrame): The cleaned and normalized DataFrame.
+
+        Returns:
+            dict[type[Model], Iterable[Model]]: Mapping from model classes
+                to iterables of instances that should be created.
         """
 
     def handle_command(self) -> None:
-        """Execute the import command.
+        """Execute the full import lifecycle.
 
-        This method handles the import process from start to finish.
-        It imports the data with handle_import(), cleans it with the cleaning df cls,
-        and then imports it to the database.
+        This template method reads raw data via :meth:`handle_import`,
+        wraps it with the cleaning class returned by
+        :meth:`get_cleaning_df_cls` and then persists the resulting
+        model bulks returned by :meth:`get_bulks_by_model`.
         """
         data_df = self.handle_import()
 
@@ -70,7 +107,11 @@ class ImportDataBaseCommand(ABCBaseCommand):
         self.import_to_db()
 
     def import_to_db(self) -> None:
-        """Import the cleaned data to the database."""
+        """Persist prepared model bulks to the database.
+
+        Calls the project's `bulk_create_bulks_in_steps` helper with the
+        mapping returned from :meth:`get_bulks_by_model`.
+        """
         bulks_by_model = self.get_bulks_by_model(df=self.cleaning_df.df)
 
         bulk_create_bulks_in_steps(bulks_by_model)

winidjango/src/db/__init__.py

@@ -1 +1,7 @@
-"""__init__ module."""
+"""Database utilities and common model helpers used in the project.
+
+This package contains helpers for working with Django models, such as
+topological sorting of model classes according to foreign-key
+dependencies, a lightweight model hashing helper, and a project-wide
+``BaseModel`` that adds common timestamp fields.
+"""