winidjango 2.0.11__py3-none-any.whl

winidjango/__init__.py

@@ -0,0 +1,34 @@
+"""__init__ module."""
+
+import logging
+from pathlib import Path
+
+import django
+import django_stubs_ext
+from django.conf import settings
+
+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 for tests")
+    installed_apps = ["tests"] if Path("tests").exists() else []
+    settings.configure(
+        DATABASES={
+            "default": {
+                "ENGINE": "django.db.backends.sqlite3",
+                "NAME": ":memory:",
+            }
+        },
+        INSTALLED_APPS=installed_apps,
+        USE_TZ=True,
+    )
+    django.setup()
+    logger.info("Django setup complete")

winidjango/dev/__init__.py

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

winidjango/dev/artifacts/__init__.py

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

winidjango/dev/artifacts/builders/__init__.py

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

winidjango/dev/artifacts/resources/__init__.py

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

winidjango/dev/cli/__init__.py

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

winidjango/dev/cli/subcommands.py

@@ -0,0 +1,6 @@
+"""Subcommands for the CLI.
+
+They will be automatically imported and added to the CLI
+IMPORTANT: All funcs in this file will be added as subcommands.
+So best to define the logic elsewhere and just call it here in a wrapper.
+"""

winidjango/dev/configs/__init__.py

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

winidjango/dev/configs/configs.py

@@ -0,0 +1,18 @@
+"""Configs for pyrig.
+
+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/__init__.py

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

winidjango/dev/tests/fixtures/__init__.py

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

winidjango/dev/tests/fixtures/fixture.py

@@ -0,0 +1,7 @@
+"""Fixtures for testing.
+
+This module provides custom fixtures for pytest that can be pluued into tests
+across the entire test suite.
+All fixtures defined under the fixtures package are auto plugged in automatically
+by pyrig via the pytest_plugins mechanism.
+"""

winidjango/dev/tests/fixtures/scopes/__init__.py

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

winidjango/dev/tests/fixtures/scopes/class_.py

@@ -0,0 +1,8 @@
+"""Class-level test fixtures and utilities.
+
+These fixtures in this module are automatically applied to all test classes
+through pytest's autouse mechanism. Pyrig automatically adds this module to
+pytest_plugins in conftest.py. However you still have decorate the fixture
+with @autouse_class_fixture from pyrig.src.testing.fixtures or with pytest's
+autouse mechanism @pytest.fixture(scope="class", autouse=True).
+"""

winidjango/dev/tests/fixtures/scopes/function.py

@@ -0,0 +1,8 @@
+"""Function-level test fixtures and utilities.
+
+These fixtures in this module are automatically applied to all test functions
+through pytest's autouse mechanism. Pyrig automatically adds this module to
+pytest_plugins in conftest.py. However you still have decorate the fixture
+with @autouse_function_fixture from pyrig.src.testing.fixtures or with pytest's
+autouse mechanism @pytest.fixture(scope="function", autouse=True).
+"""

winidjango/dev/tests/fixtures/scopes/module.py

@@ -0,0 +1,8 @@
+"""Module-level test fixtures and utilities.
+
+These fixtures in this module are automatically applied to all test modules
+through pytest's autouse mechanism. Pyrig automatically adds this module to
+pytest_plugins in conftest.py. However you still have decorate the fixture
+with @autouse_module_fixture from pyrig.src.testing.fixtures or with pytest's
+autouse mechanism @pytest.fixture(scope="module", autouse=True).
+"""

winidjango/dev/tests/fixtures/scopes/package.py

@@ -0,0 +1,8 @@
+"""Package-level test fixtures and utilities.
+
+These fixtures in this module are automatically applied to all test packages
+through pytest's autouse mechanism. Pyrig automatically adds this module to
+pytest_plugins in conftest.py. However you still have decorate the fixture
+with @autouse_package_fixture from pyrig.src.testing.fixtures or with pytest's
+autouse mechanism @pytest.fixture(scope="package", autouse=True).
+"""

winidjango/dev/tests/fixtures/scopes/session.py

@@ -0,0 +1,8 @@
+"""Session-level test fixtures and utilities.
+
+These fixtures in this module are automatically applied to the test session
+through pytest's autouse mechanism. Pyrig automatically adds this module to
+pytest_plugins in conftest.py. However you still have decorate the fixture
+with @autouse_session_fixture from pyrig.src.testing.fixtures or with pytest's
+autouse mechanism @pytest.fixture(scope="session", autouse=True).
+"""

winidjango/main.py

@@ -0,0 +1,19 @@
+"""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
+`your-pkg-name main`
+or via
+`python -m your-pkg-name`.
+"""
+    raise NotImplementedError(msg)
+
+
+if __name__ == "__main__":
+    main()

winidjango/src/__init__.py

@@ -0,0 +1 @@
+"""src package."""

winidjango/src/commands/__init__.py

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

winidjango/src/commands/base/__init__.py

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

winidjango/src/commands/base/base.py

@@ -0,0 +1,305 @@
+"""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.
+"""
+
+import logging
+from abc import abstractmethod
+from argparse import ArgumentParser
+from typing import Any
+
+from django.core.management import BaseCommand
+from winiutils.src.oop.mixins.mixin import ABCLoggingMixin
+
+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
+    """
+
+    class Options:
+        """Just a container class for hard coding the option keys."""
+
+        DRY_RUN = "dry_run"
+        FORCE = "force"
+        DELETE = "delete"
+        YES = "yes"
+        TIMEOUT = "timeout"
+        BATCH_SIZE = "batch_size"
+        THREADS = "threads"
+        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.
+
+        The @final decorator prevents subclasses from overriding this method,
+        ensuring consistent argument handling across all commands while still
+        allowing customization through the abstract method.
+
+        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
+        """
+        # add base args that are used in most commands
+        self.base_add_arguments(parser)
+
+        # add additional args that are specific to the command
+        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.
+
+        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.add_argument(
+            f"--{self.Options.DRY_RUN}",
+            action="store_true",
+            help="Show what would be done without actually executing the changes",
+        )
+
+        parser.add_argument(
+            f"--{self.Options.FORCE}",
+            action="store_true",
+            help="Force an action in a command",
+        )
+
+        parser.add_argument(
+            f"--{self.Options.DELETE}",
+            action="store_true",
+            help="Deleting smth in a command",
+        )
+
+        parser.add_argument(
+            f"--{self.Options.YES}",
+            action="store_true",
+            help="Answer yes to all prompts",
+            default=False,
+        )
+
+        parser.add_argument(
+            f"--{self.Options.TIMEOUT}",
+            type=int,
+            help="Timeout for a command",
+            default=None,
+        )
+
+        parser.add_argument(
+            f"--{self.Options.BATCH_SIZE}",
+            type=int,
+            default=None,
+            help="Number of items to process in each batch",
+        )
+
+        parser.add_argument(
+            f"--{self.Options.THREADS}",
+            type=int,
+            default=None,
+            help="Number of threads to use for processing",
+        )
+
+        parser.add_argument(
+            f"--{self.Options.PROCESSES}",
+            type=int,
+            default=None,
+            help="Number of processes to use for processing",
+        )
+
+    @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.
+
+        Subclasses should use this method to add arguments specific to their
+        command's functionality, such as file paths, configuration options,
+        or operational flags.
+
+        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
+        """
+
+    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().
+
+        The @final decorator ensures this execution pattern cannot be overridden,
+        maintaining consistent command execution flow while allowing customization
+        through the abstract handle_command method.
+
+        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
+        """
+        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.
+
+        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.
+
+        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
+        """
+        self.args = args
+        self.options = options
+
+    @abstractmethod
+    def handle_command(self) -> None:
+        """Execute command-specific logic and functionality.
+
+        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 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.
+
+        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()
+        """
+
+    def get_option(self, option: str) -> Any:
+        """Get an option from the command options."""
+        return self.options[option]

winidjango/src/commands/import_data.py

@@ -0,0 +1,76 @@
+"""Import command for Django.
+
+A base class for importing data from a source to the database.
+"""
+
+import logging
+from abc import abstractmethod
+from collections.abc import Iterable
+
+import polars as pl
+from django.db.models import Model
+from winiutils.src.data.dataframe.cleaning import CleaningDF
+
+from winidjango.src.commands.base.base import ABCBaseCommand
+from winidjango.src.db.bulk import bulk_create_bulks_in_steps
+
+logger = logging.getLogger(__name__)
+
+
+class ImportDataBaseCommand(ABCBaseCommand):
+    """Base class for importing data from a source to the database.
+
+    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.
+    """
+
+    @abstractmethod
+    def handle_import(self) -> pl.DataFrame:
+        """Handle importing the data from the source.
+
+        The data is possibly dirty and the job of this class to standardize the process
+        of importing the data.
+        """
+
+    @abstractmethod
+    def get_cleaning_df_cls(self) -> type[CleaningDF]:
+        """You will define a child of a cleaning df cls and return it.
+
+        The cleaning df cls is responsible for cleaning the data.
+        See: winiutils.src.data.dataframe.cleaning.CleaningDF
+        """
+
+    @abstractmethod
+    def get_bulks_by_model(
+        self, df: pl.DataFrame
+    ) -> dict[type[Model], Iterable[Model]]:
+        """Get the bulks of data to import by model.
+
+        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.
+
+        Args:
+            df (pl.DataFrame): The cleaned data to import.
+                Is passed from handle_command() automatically.
+        """
+
+    def handle_command(self) -> None:
+        """Execute the import command.
+
+        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.
+        """
+        data_df = self.handle_import()
+
+        cleaning_df_cls = self.get_cleaning_df_cls()
+        self.cleaning_df = cleaning_df_cls(data_df)
+
+        self.import_to_db()
+
+    def import_to_db(self) -> None:
+        """Import the cleaned data to the database."""
+        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

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