winipedia-django 0.2.0__tar.gz

winipedia_django-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Winipedia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

winipedia_django-0.2.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: winipedia-django
+Version: 0.2.0
+Summary: A utils package for django
+License-Expression: MIT
+License-File: LICENSE
+Author: Winipedia
+Author-email: win.steveker@gmx.de
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: django (>=5.2.7,<6.0.0)
+Requires-Dist: winipedia-utils (>=0.2.10,<0.3.0)
+Description-Content-Type: text/markdown
+
+# winipedia_django
+A utils package for django
+

winipedia_django-0.2.0/README.md

@@ -0,0 +1,2 @@
+# winipedia_django
+A utils package for django

winipedia_django-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "winipedia-django"
+version = "0.2.0"
+description = "A utils package for django"
+authors = [
+    {name = "Winipedia",email = "win.steveker@gmx.de"}
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "winipedia-utils (>=0.2.10,<0.3.0)",
+    "django (>=5.2.7,<6.0.0)"
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "ruff (>=0.14.1,<0.15.0)",
+    "pre-commit (>=4.3.0,<5.0.0)",
+    "mypy (>=1.18.2,<2.0.0)",
+    "pytest (>=8.4.2,<9.0.0)",
+    "bandit (>=1.8.6,<2.0.0)",
+    "types-setuptools (>=80.9.0.20250822,<81.0.0.0)",
+    "types-tqdm (>=4.67.0.20250809,<5.0.0.0)",
+    "types-defusedxml (>=0.7.0.20250822,<0.8.0.0)",
+    "types-pyyaml (>=6.0.12.20250915,<7.0.0.0)",
+    "pytest-mock (>=3.15.1,<4.0.0)",
+    "django-stubs (>=5.2.7,<6.0.0)"
+]
+
+[tool.ruff]
+exclude = [".*", "**/migrations/*.py"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["D203", "D213", "COM812", "ANN401"]
+fixable = ["ALL"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+show_error_codes = true
+files = "."
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.bandit]

winipedia_django-0.2.0/winipedia_django/__init__.py

@@ -0,0 +1,23 @@
+"""__init__ module."""
+
+import django
+import django_stubs_ext
+from django.conf import settings
+from winipedia_utils.logging.logger import get_logger
+
+logger = get_logger(__name__)
+
+django_stubs_ext.monkeypatch()
+logger.info("Monkeypatched django-stubs")
+
+if not settings.configured:
+    logger.info("Configuring minimal django settings")
+    settings.configure(
+        DATABASES={
+            "default": {
+                "ENGINE": "django.db.backends.sqlite3",
+                "NAME": ":memory:",
+            }
+        },
+    )
+    django.setup()

winipedia_django-0.2.0/winipedia_django/bulk.py

@@ -0,0 +1,538 @@
+"""Bulk utilities for Django models.
+
+This module provides utility functions for working with Django models,
+including bulk operations and validation. These utilities help with
+efficiently managing large amounts of data in Django applications.
+"""
+
+from collections import defaultdict
+from collections.abc import Callable, Generator, Iterable
+from functools import partial
+from itertools import islice
+from typing import TYPE_CHECKING, Any, Literal, cast, get_args
+
+from django.db import router, transaction
+from django.db.models import (
+    Field,
+    Model,
+    QuerySet,
+)
+from django.db.models.deletion import Collector
+from winipedia_utils.concurrent.multithreading import multithread_loop
+from winipedia_utils.logging.logger import get_logger
+
+from winipedia_django.database import (
+    hash_model_instance,
+    topological_sort_models,
+)
+
+if TYPE_CHECKING:
+    from django.contrib.contenttypes.fields import GenericForeignKey
+    from django.db.models.fields.related import ForeignObjectRel
+
+logger = get_logger(__name__)
+
+MODE_TYPES = Literal["create", "update", "delete"]
+MODES = get_args(MODE_TYPES)
+
+MODE_CREATE = MODES[0]
+MODE_UPDATE = MODES[1]
+MODE_DELETE = MODES[2]
+
+STANDARD_BULK_SIZE = 1000
+
+
+def bulk_create_in_steps(
+    model: type[Model],
+    bulk: Iterable[Model],
+    step: int = STANDARD_BULK_SIZE,
+) -> list[Model]:
+    """Create model instances from bulk and saves them to the database in steps.
+
+    Takes a list of model instances and creates them in the database in steps.
+    This is useful when you want to create a large number of objects
+    in the database. It also uses multithreading to speed up the process.
+
+    Args:
+        model (type[Model]): The Django model class to create.
+        bulk (Iterable[Model]): a list of model instances to create.
+        step (int, optional): The step size of the bulk creation.
+                              Defaults to STANDARD_BULK_SIZE.
+
+    Returns:
+        list[Model]: a list of created objects.
+    """
+    return cast(
+        "list[Model]",
+        bulk_method_in_steps(model=model, bulk=bulk, step=step, mode=MODE_CREATE),
+    )
+
+
+def bulk_update_in_steps(
+    model: type[Model],
+    bulk: Iterable[Model],
+    update_fields: list[str],
+    step: int = STANDARD_BULK_SIZE,
+) -> int:
+    """Update model instances in the database in steps using multithreading.
+
+    Takes a list of model instances and updates them in the database in chunks.
+    This is useful when you want to update a large number of objects efficiently.
+    Uses multithreading to speed up the process by processing chunks in parallel.
+
+    Args:
+        model (type[Model]): The Django model class to update.
+        bulk (Iterable[Model]): A list of model instances to update.
+        update_fields (list[str]): List of field names to update on the models.
+        step (int, optional): The step size for bulk updates.
+                              Defaults to STANDARD_BULK_SIZE.
+
+    Returns:
+        int: Total number of objects updated across all chunks.
+    """
+    return cast(
+        "int",
+        bulk_method_in_steps(
+            model=model, bulk=bulk, step=step, mode=MODE_UPDATE, fields=update_fields
+        ),
+    )
+
+
+def bulk_delete_in_steps(
+    model: type[Model], bulk: Iterable[Model], step: int = STANDARD_BULK_SIZE
+) -> tuple[int, dict[str, int]]:
+    """Delete model instances from the database in steps using multithreading.
+
+    Takes a list of model instances and deletes them from the database in chunks.
+    This is useful when you want to delete a large number of objects efficiently.
+    Uses multithreading to speed up the process by processing chunks in parallel.
+    Also handles cascade deletions according to model relationships.
+
+    Args:
+        model (type[Model]): The Django model class to update.
+        bulk (Iterable[Model]): A list of model instances to delete.
+        step (int, optional): The step size for bulk deletions.
+                              Defaults to STANDARD_BULK_SIZE.
+
+    Returns:
+        tuple[int, dict[str, int]]: A tuple containing the
+                                    total count of deleted objects
+            and a dictionary mapping model names to their deletion counts.
+    """
+    return cast(
+        "tuple[int, dict[str, int]]",
+        bulk_method_in_steps(
+            model=model,
+            bulk=bulk,
+            step=step,
+            mode=MODE_DELETE,
+        ),
+    )
+
+
+def bulk_method_in_steps(
+    model: type[Model],
+    bulk: Iterable[Model],
+    step: int,
+    mode: MODE_TYPES,
+    **kwargs: Any,
+) -> int | tuple[int, dict[str, int]] | list[Model]:
+    """Execute bulk operations on model instances in steps with transaction handling.
+
+    This is the core function that handles bulk create, update, or delete operations
+    by dividing the work into manageable chunks and processing them with multithreading.
+    It includes transaction safety checks and delegates to the atomic version.
+
+    Args:
+        model (type[Model]): The Django model class to perform operations on.
+        bulk (Iterable[Model]): A list of model instances to process.
+        step (int): The step size for chunking the bulk operations.
+        mode (MODE_TYPES): The operation mode - 'create', 'update', or 'delete'.
+        **kwargs: Additional keyword arguments passed to the bulk operation methods.
+
+    Returns:
+        None | int | tuple[int, dict[str, int]] | list[Model]:
+        The result depends on mode:
+            - create: list of created model instances
+            - update: integer count of updated objects
+            - delete: tuple of (total_count, count_by_model_dict)
+            - None if bulk is empty
+    """
+    # check if we are inside a transaction.atomic block
+    _in_atomic_block = transaction.get_connection().in_atomic_block
+    if _in_atomic_block:
+        logger.info(
+            "BE CAREFUL USING BULK OPERATIONS INSIDE A BROADER TRANSACTION BLOCK. "
+            "BULKING WITH BULKS THAT DEPEND ON EACH OTHER CAN CAUSE "
+            "INTEGRITY ERRORS OR POTENTIAL OTHER ISSUES."
+        )
+    return bulk_method_in_steps_atomic(
+        model=model, bulk=bulk, step=step, mode=mode, **kwargs
+    )
+
+
+@transaction.atomic
+def bulk_method_in_steps_atomic(
+    model: type[Model],
+    bulk: Iterable[Model],
+    step: int,
+    mode: MODE_TYPES,
+    **kwargs: Any,
+) -> int | tuple[int, dict[str, int]] | list[Model]:
+    """Bulk create, update or delete the given list of objects in steps.
+
+    WHEN BULK CREATING OR UPDATING A BULK
+    AND THEN A SECOND BULK THAT DEPENDS ON THE FIRST BULK,
+    YOU WILL RUN INTO A INTEGRITY ERROR IF YOU DO THE
+    ENTIRE THING IN AN @transaction.atomic DECORATOR.
+    REMOVE THE DECORATORS THAT ARE HIGHER UP THAN THE ONE OF THIS FUNCTION
+    TO AVOID THIS ERROR.
+
+    Args:
+        model (type[Model]): The Django model class to perform operations on.
+        bulk (Iterable[Model]): A list of model instances to process.
+        step (int): number of objects to process in one chunk
+        mode (MODE_TYPES): The operation mode - 'create', 'update', or 'delete'.
+        **kwargs: Additional keyword arguments passed to the bulk operation methods.
+
+    Returns:
+        None | int | tuple[int, dict[str, int]] | list[Model]:
+        The result depends on mode:
+            - create: list of created model instances
+            - update: integer count of updated objects
+            - delete: tuple of (total_count, count_by_model_dict)
+            - None if bulk is empty
+    """
+    bulk_method = get_bulk_method(model=model, mode=mode, **kwargs)
+
+    chunks = get_step_chunks(bulk=bulk, step=step)
+
+    # multithreading significantly increases speed
+    result = multithread_loop(
+        process_function=bulk_method,
+        process_args=chunks,
+    )
+
+    return flatten_bulk_in_steps_result(result=result, mode=mode)
+
+
+def get_step_chunks(
+    bulk: Iterable[Model], step: int
+) -> Generator[tuple[list[Model]], None, None]:
+    """Yield chunks of the given size from the bulk.
+
+    Args:
+        bulk (Iterable[Model]): The bulk to chunk.
+        step (int): The size of each chunk.
+
+    Yields:
+        Generator[list[Model], None, None]: Chunks of the bulk.
+    """
+    bulk = iter(bulk)
+    while True:
+        chunk = list(islice(bulk, step))
+        if not chunk:
+            break
+        yield (chunk,)  # bc concurrent_loop expects a tuple of args
+
+
+def get_bulk_method(
+    model: type[Model], mode: MODE_TYPES, **kwargs: Any
+) -> Callable[[list[Model]], list[Model] | int | tuple[int, dict[str, int]]]:
+    """Get the appropriate bulk method function based on the operation mode.
+
+    Creates and returns a function that performs the specified bulk operation
+    (create, update, or delete) on a chunk of model instances. The returned
+    function is configured with the provided kwargs.
+
+    Args:
+        model (type[Model]): The Django model class to perform operations on.
+        mode (MODE_TYPES): The operation mode - 'create', 'update', or 'delete'.
+        **kwargs: Additional keyword arguments to pass to the bulk operation method.
+
+    Raises:
+        ValueError: If the mode is not one of the valid MODE_TYPES.
+
+    Returns:
+        Callable[[list[Model]], Any]: A function that performs the bulk operation
+            on a chunk of model instances.
+    """
+    bulk_method: Callable[[list[Model]], list[Model] | int | tuple[int, dict[str, int]]]
+    if mode == MODE_CREATE:
+
+        def bulk_create_chunk(chunk: list[Model]) -> list[Model]:
+            return model.objects.bulk_create(objs=chunk, **kwargs)
+
+        bulk_method = bulk_create_chunk
+    elif mode == MODE_UPDATE:
+
+        def bulk_update_chunk(chunk: list[Model]) -> int:
+            return model.objects.bulk_update(objs=chunk, **kwargs)
+
+        bulk_method = bulk_update_chunk
+    elif mode == MODE_DELETE:
+
+        def bulk_delete_chunk(chunk: list[Model]) -> tuple[int, dict[str, int]]:
+            return bulk_delete(model=model, objs=chunk, **kwargs)
+
+        bulk_method = bulk_delete_chunk
+    else:
+        msg = f"Invalid method. Must be one of {MODES}"
+        raise ValueError(msg)
+
+    return bulk_method
+
+
+def flatten_bulk_in_steps_result(
+    result: list[Any], mode: str
+) -> int | tuple[int, dict[str, int]] | list[Model]:
+    """Flatten and aggregate results from multithreaded bulk operations.
+
+    Processes the results returned from parallel bulk operations and aggregates
+    them into the appropriate format based on the operation mode. Handles
+    different return types for create, update, and delete operations.
+
+    Args:
+        result (list[Any]): List of results from each chunk operation.
+        mode (str): The operation mode - 'create', 'update', or 'delete'.
+
+    Raises:
+        ValueError: If the mode is not one of the valid operation modes.
+
+    Returns:
+        None | int | tuple[int, dict[str, int]] | list[Model]: Aggregated result:
+            - update: sum of updated object counts
+            - delete: tuple of (total_count, count_by_model_dict)
+            - create: flattened list of all created objects
+    """
+    if mode == MODE_UPDATE:
+        # formated as [1000, 1000, ...]
+        # since django 4.2 bulk_update returns the count of updated objects
+        return int(sum(result))
+    if mode == MODE_DELETE:
+        # formated as [(count, {model_name: count, model_cascade_name: count}), ...]
+        # join the results to get the total count of deleted objects
+        total_count = 0
+        count_sum_by_model: defaultdict[str, int] = defaultdict(int)
+        for count_sum, count_by_model in result:
+            total_count += count_sum
+            for model_name, count in count_by_model.items():
+                count_sum_by_model[model_name] += count
+        return (total_count, dict(count_sum_by_model))
+    if mode == MODE_CREATE:
+        # formated as [[obj1, obj2, ...], [obj1, obj2, ...], ...]
+        return [item for sublist in result for item in sublist]
+
+    msg = f"Invalid method. Must be one of {MODES}"
+    raise ValueError(msg)
+
+
+def bulk_delete(
+    model: type[Model], objs: Iterable[Model], **_: Any
+) -> tuple[int, dict[str, int]]:
+    """Delete model instances using Django's QuerySet delete method.
+
+    Deletes the provided model instances from the database using Django's
+    built-in delete functionality. Handles both individual model instances
+    and QuerySets, and returns deletion statistics including cascade counts.
+
+    Args:
+        model (type[Model]): The Django model class to delete from.
+        objs (list[Model]): A list of model instances to delete.
+
+    Returns:
+        tuple[int, dict[str, int]]: A tuple containing the total count of deleted
+            objects and a dictionary mapping model names to their deletion counts.
+    """
+    if not isinstance(objs, QuerySet):
+        objs = list(objs)
+        pks = [obj.pk for obj in objs]
+        query_set = model.objects.filter(pk__in=pks)
+    else:
+        query_set = objs
+
+    return query_set.delete()
+
+
+def bulk_create_bulks_in_steps(
+    bulk_by_class: dict[type[Model], Iterable[Model]],
+    step: int = STANDARD_BULK_SIZE,
+) -> dict[type[Model], list[Model]]:
+    """Create multiple bulks of different model types in dependency order.
+
+    Takes a dictionary mapping model classes to lists of instances and creates
+    them in the database in the correct order based on model dependencies.
+    Uses topological sorting to ensure foreign key constraints are satisfied.
+
+    Args:
+        bulk_by_class (dict[type[Model], list[Model]]): Dictionary mapping model classes
+            to lists of instances to create.
+        step (int, optional): The step size for bulk creation. Defaults to 1000.
+        validate (bool, optional): Whether to validate instances before creation.
+        Defaults to True.
+
+    Returns:
+        dict[type[Model], list[Model]]: Dictionary mapping model classes to lists
+            of created instances.
+    """
+    # order the bulks in order of creation depending how they depend on each other
+    models_ = list(bulk_by_class.keys())
+    ordered_models = topological_sort_models(models=models_)
+
+    results = {}
+    for model_ in ordered_models:
+        bulk = bulk_by_class[model_]
+        result = bulk_create_in_steps(model=model_, bulk=bulk, step=step)
+        results[model_] = result
+
+    return results
+
+
+def get_differences_between_bulks(
+    bulk1: list[Model],
+    bulk2: list[Model],
+    fields: "list[Field[Any, Any] | ForeignObjectRel | GenericForeignKey]",
+) -> tuple[list[Model], list[Model], list[Model], list[Model]]:
+    """Compare two bulks and return their differences and intersections.
+
+    Compares two lists of model instances by computing hashes of their field values
+    and returns the differences and intersections between them. Optionally allows
+    specifying which fields to compare and the depth of comparison for related objects.
+
+    Args:
+        bulk1 (list[Model]): First list of model instances to compare.
+        bulk2 (list[Model]): Second list of model instances to compare.
+        fields (list[Field] | None, optional): List of fields to compare.
+            Defaults to None, which compares all fields.
+        max_depth (int | None, optional): Maximum depth for comparing related objects.
+            Defaults to None.
+
+    Raises:
+        ValueError: If the two bulks contain different model types.
+
+    Returns:
+        tuple[list[Model], list[Model], list[Model], list[Model]]: A tuple containing:
+            - Objects in bulk1 but not in bulk2
+            - Objects in bulk2 but not in bulk1
+            - Objects in both bulk1 and bulk2 (from bulk1)
+            - Objects in both bulk1 and bulk2 (from bulk2)
+    """
+    if not bulk1 or not bulk2:
+        return bulk1, bulk2, [], []
+
+    if type(bulk1[0]) is not type(bulk2[0]):
+        msg = "Both bulks must be of the same model type."
+        raise ValueError(msg)
+
+    hash_model_instance_with_fields = partial(
+        hash_model_instance,
+        fields=fields,
+    )
+    # Precompute hashes and map them directly to models in a single pass for both bulks
+    hashes1 = list(map(hash_model_instance_with_fields, bulk1))
+    hashes2 = list(map(hash_model_instance_with_fields, bulk2))
+
+    # Convert keys to sets for difference operations
+    set1, set2 = set(hashes1), set(hashes2)
+
+    # Calculate differences between sets
+    # Find differences and intersection with original order preserved
+    # Important, we need to return the original objects that are the same in memory,
+    # so in_1_not_2 and in_2_not_1
+    in_1_not_2 = set1 - set2
+    in_1_not_2_list = [
+        model
+        for model, hash_ in zip(bulk1, hashes1, strict=False)
+        if hash_ in in_1_not_2
+    ]
+
+    in_2_not_1 = set2 - set1
+    in_2_not_1_list = [
+        model
+        for model, hash_ in zip(bulk2, hashes2, strict=False)
+        if hash_ in in_2_not_1
+    ]
+
+    in_1_and_2 = set1 & set2
+    in_1_and_2_from_1 = [
+        model
+        for model, hash_ in zip(bulk1, hashes1, strict=False)
+        if hash_ in in_1_and_2
+    ]
+    in_1_and_2_from_2 = [
+        model
+        for model, hash_ in zip(bulk2, hashes2, strict=False)
+        if hash_ in in_1_and_2
+    ]
+
+    return in_1_not_2_list, in_2_not_1_list, in_1_and_2_from_1, in_1_and_2_from_2
+
+
+def simulate_bulk_deletion(
+    model_class: type[Model], entries: list[Model]
+) -> dict[type[Model], set[Model]]:
+    """Simulate bulk deletion to preview what objects would be deleted.
+
+    Uses Django's Collector to simulate the deletion process and determine
+    which objects would be deleted due to cascade relationships, without
+    actually performing the deletion. Useful for previewing deletion effects.
+
+    Args:
+        model_class (type[Model]): The Django model class of the entries to delete.
+        entries (list[Model]): List of model instances to simulate deletion for.
+
+    Returns:
+        dict[type[Model], set[Model]]: Dictionary mapping model classes to sets
+            of objects that would be deleted, including cascade deletions.
+    """
+    if not entries:
+        return {}
+
+    # Initialize the Collector
+    using = router.db_for_write(model_class)
+    collector = Collector(using)
+
+    # Collect deletion cascade for all entries
+    collector.collect(entries)
+
+    # Prepare the result dictionary
+    deletion_summary: defaultdict[type[Model], set[Model]] = defaultdict(set)
+
+    # Add normal deletes
+    for model, objects in collector.data.items():
+        deletion_summary[model].update(objects)  # objects is already iterable
+
+    # Add fast deletes (explicitly expand querysets)
+    for queryset in collector.fast_deletes:
+        deletion_summary[queryset.model].update(list(queryset))
+
+    return deletion_summary
+
+
+def multi_simulate_bulk_deletion(
+    entries: dict[type[Model], list[Model]],
+) -> dict[type[Model], set[Model]]:
+    """Simulate bulk deletion for multiple model types and aggregate results.
+
+    Performs deletion simulation for multiple model types and combines the results
+    into a single summary. This is useful when you want to preview the deletion
+    effects across multiple related model types.
+
+    Args:
+        entries (dict[type[Model], list[Model]]): Dictionary mapping model classes
+            to lists of instances to simulate deletion for.
+
+    Returns:
+        dict[type[Model], set[Model]]: Dictionary mapping model classes to sets
+            of all objects that would be deleted across all simulations.
+    """
+    deletion_summaries = [
+        simulate_bulk_deletion(model, entry) for model, entry in entries.items()
+    ]
+    # join the dicts to get the total count of deleted objects
+    joined_deletion_summary = defaultdict(set)
+    for deletion_summary in deletion_summaries:
+        for model, objects in deletion_summary.items():
+            joined_deletion_summary[model].update(objects)
+
+    return dict(joined_deletion_summary)

winipedia_django-0.2.0/winipedia_django/command.py

@@ -0,0 +1,333 @@
+"""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, final
+
+from django.core.management import BaseCommand
+from winipedia_utils.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
+    """
+
+    @final
+    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._add_arguments(parser)
+
+        # add additional args that are specific to the command
+        self.add_command_arguments(parser)
+
+    @final
+    def _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(
+            "--dry-run",
+            action="store_true",
+            help="Show what would be done without actually executing the changes",
+        )
+
+        parser.add_argument(
+            "--size",
+            type=int,
+            default=None,
+            help="Size of smth in a command",
+        )
+
+        parser.add_argument(
+            "--force",
+            action="store_true",
+            help="Force an action in a command",
+        )
+
+        parser.add_argument(
+            "--delete",
+            action="store_true",
+            help="Deleting smth in a command",
+        )
+
+        parser.add_argument(
+            "--quiet",
+            action="store_true",
+            help="Suppress non-error output for cleaner automation",
+        )
+
+        parser.add_argument(
+            "--debug",
+            action="store_true",
+            help="Print debug output for detailed tracing",
+        )
+
+        parser.add_argument(
+            "--yes",
+            action="store_true",
+            help="Answer yes to all prompts",
+            default=False,
+        )
+
+        parser.add_argument(
+            "--config",
+            type=str,
+            help="A configuration setup like filepath or json string for a command",
+            default=None,
+        )
+
+        parser.add_argument(
+            "--timeout",
+            type=int,
+            help="Timeout for a command",
+            default=None,
+        )
+
+        parser.add_argument(
+            "--batch-size",
+            type=int,
+            default=None,
+            help="Number of items to process in each batch",
+        )
+
+        parser.add_argument(
+            "--no-input",
+            action="store_true",
+            help="Do not prompt for user input",
+        )
+
+        parser.add_argument(
+            "--threads",
+            type=int,
+            default=None,
+            help="Number of threads to use for processing",
+        )
+
+        parser.add_argument(
+            "--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
+        """
+
+    @final
+    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._handle(*args, **options)
+        self.handle_command(*args, **options)
+
+    @final
+    def _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
+        """
+        # log each option for the command
+        for key, value in options.items():
+            logger.info(
+                "Command '%s' - runs with option: '%s' with value: '%s'",
+                self.__class__.__name__,
+                key,
+                value,
+            )
+
+    @abstractmethod
+    def handle_command(self, *args: Any, **options: Any) -> 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:
+            *args: Positional arguments passed from Django's command execution.
+                These are typically not used in Django management commands.
+            **options: Keyword arguments containing parsed command-line options
+                and their values as defined by add_command_arguments().
+
+        Example:
+            >>> def handle_command(self, *args, **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()
+        """

winipedia_django-0.2.0/winipedia_django/database.py

@@ -0,0 +1,288 @@
+"""Database utilities for Django.
+
+This module provides utility functions for working with Django models,
+including hashing, topological sorting, and database operations.
+These utilities help with efficient and safe database interactions.
+"""
+
+from datetime import datetime
+from graphlib import TopologicalSorter
+from typing import TYPE_CHECKING, Any, Self
+
+from django.db import connection
+from django.db.models import DateTimeField, Field, Model
+from django.db.models.fields.related import ForeignKey, ForeignObjectRel
+from django.forms.models import model_to_dict
+from winipedia_utils.logging.logger import get_logger
+
+if TYPE_CHECKING:
+    from django.contrib.contenttypes.fields import GenericForeignKey
+    from django.db.models.options import Options
+
+logger = get_logger(__name__)
+
+
+def get_model_meta(model: type[Model]) -> "Options[Model]":
+    """Get the Django model metadata options object.
+
+    Retrieves the _meta attribute from a Django model class, which contains
+    metadata about the model including field definitions, table name, and
+    other model configuration options. This is a convenience wrapper around
+    accessing the private _meta attribute directly.
+
+    Args:
+        model (type[Model]): The Django model class to get metadata from.
+
+    Returns:
+        Options[Model]: The model's metadata options object containing
+            field definitions, table information, and other model configuration.
+
+    Example:
+        >>> from django.contrib.auth.models import User
+        >>> meta = get_model_meta(User)
+        >>> meta.db_table
+        'auth_user'
+        >>> len(meta.get_fields())
+        11
+    """
+    return model._meta  # noqa: SLF001
+
+
+def get_fields(
+    model: type[Model],
+) -> "list[Field[Any, Any] | ForeignObjectRel | GenericForeignKey]":
+    """Get all fields from a Django model including relationships.
+
+    Retrieves all field objects from a Django model, including regular fields,
+    foreign key relationships, reverse foreign key relationships, and generic
+    foreign keys. This provides a comprehensive view of all model attributes
+    that can be used for introspection, validation, or bulk operations.
+
+    Args:
+        model (type[Model]): The Django model class to get fields from.
+
+    Returns:
+        list[Field | ForeignObjectRel | GenericForeignKey]: A list
+            containing all field objects associated with the model, including:
+            - Regular model fields (CharField, IntegerField, etc.)
+            - Foreign key fields (ForeignKey, OneToOneField, etc.)
+            - Reverse relationship fields (ForeignObjectRel)
+            - Generic foreign key fields (GenericForeignKey)
+
+    Example:
+        >>> from django.contrib.auth.models import User
+        >>> fields = get_fields(User)
+        >>> field_names = [f.name for f in fields if hasattr(f, 'name')]
+        >>> 'username' in field_names
+        True
+        >>> 'email' in field_names
+        True
+    """
+    return get_model_meta(model).get_fields()
+
+
+def get_field_names(
+    fields: "list[Field[Any, Any] | ForeignObjectRel | GenericForeignKey]",
+) -> list[str]:
+    """Get the names of all fields from a Django model including relationships.
+
+    Retrieves the names of all field objects from a Django model, including
+    regular fields, foreign key relationships, reverse foreign key relationships,
+    and generic foreign keys. This provides a comprehensive view of all model
+    attributes that can be used for introspection, validation, or bulk operations.
+
+    Args:
+        fields (list[Field | ForeignObjectRel | GenericForeignKey]):
+            The list of field objects to get names from.
+
+    Returns:
+        list[str]: A list containing the names of all fields.
+
+    Example:
+        >>> from django.contrib.auth.models import User
+        >>> fields = get_fields(User)
+        >>> field_names = get_field_names(fields)
+        >>> 'username' in field_names
+        True
+        >>> 'email' in field_names
+        True
+    """
+    return [field.name for field in fields]
+
+
+def topological_sort_models(models: list[type[Model]]) -> list[type[Model]]:
+    """Sort Django models in dependency order using topological sorting.
+
+    Analyzes foreign key relationships between Django models and returns them
+    in an order where dependencies come before dependents. This ensures that
+    when performing operations like bulk creation or deletion, models are
+    processed in the correct order to avoid foreign key constraint violations.
+
+    The function uses Python's graphlib.TopologicalSorter to perform the sorting
+    based on ForeignKey relationships between the provided models. Only
+    relationships between models in the input list are considered.
+
+    Args:
+        models (list[type[Model]]): A list of Django model classes to sort
+            based on their foreign key dependencies.
+
+    Returns:
+        list[type[Model]]: The input models sorted in dependency order, where
+            models that are referenced by foreign keys appear before models
+            that reference them. Self-referential relationships are ignored.
+
+    Raises:
+        graphlib.CycleError: If there are circular dependencies between models
+            that cannot be resolved.
+
+    Example:
+        >>> # Assuming Author model has no dependencies
+        >>> # and Book model has ForeignKey to Author
+        >>> models = [Book, Author]
+        >>> sorted_models = topological_sort_models(models)
+        >>> sorted_models
+        [<class 'Author'>, <class 'Book'>]
+
+    Note:
+        - Only considers ForeignKey relationships, not other field types
+        - Self-referential foreign keys are ignored to avoid self-loops
+        - Only relationships between models in the input list are considered
+    """
+    ts: TopologicalSorter[type[Model]] = TopologicalSorter()
+
+    for model in models:
+        deps = {
+            field.related_model
+            for field in get_fields(model)
+            if isinstance(field, ForeignKey)
+            and isinstance(field.related_model, type)
+            and field.related_model in models
+            and field.related_model is not model
+        }
+        ts.add(model, *deps)
+
+    return list(ts.static_order())
+
+
+def execute_sql(
+    sql: str, params: dict[str, Any] | None = None
+) -> tuple[list[str], list[Any]]:
+    """Execute raw SQL query and return column names with results.
+
+    Executes a raw SQL query using Django's database connection and returns
+    both the column names and the result rows. This provides a convenient
+    way to run custom SQL queries while maintaining Django's database
+    connection management and parameter binding for security.
+
+    The function automatically handles cursor management and ensures proper
+    cleanup of database resources. Parameters are safely bound to prevent
+    SQL injection attacks.
+
+    Args:
+        sql (str): The SQL query string to execute. Can contain parameter
+            placeholders that will be safely bound using the params argument.
+        params (dict[str, Any] | None, optional): Dictionary of parameters
+            to bind to the SQL query for safe parameter substitution.
+            Defaults to None if no parameters are needed.
+
+    Returns:
+        tuple[list[str], list[Any]]: A tuple containing:
+            - list[str]: Column names from the query result
+            - list[Any]: List of result rows, where each row is a tuple
+              of values corresponding to the column names
+
+    Raises:
+        django.db.Error: If there's a database error during query execution
+        django.db.ProgrammingError: If the SQL syntax is invalid
+        django.db.IntegrityError: If the query violates database constraints
+
+    Example:
+        >>> sql = "SELECT id, username FROM auth_user WHERE is_active = %(active)s"
+        >>> params = {"active": True}
+        >>> columns, rows = execute_sql(sql, params)
+        >>> columns
+        ['id', 'username']
+        >>> rows[0]
+        (1, 'admin')
+
+    Note:
+        - Uses Django's default database connection
+        - Automatically manages cursor lifecycle
+        - Parameters are safely bound to prevent SQL injection
+        - Returns all results in memory - use with caution for large datasets
+    """
+    with connection.cursor() as cursor:
+        cursor.execute(sql=sql, params=params)
+        rows = cursor.fetchall()
+        column_names = [col[0] for col in cursor.description]
+
+    return column_names, rows
+
+
+def hash_model_instance(
+    instance: Model,
+    fields: "list[Field[Any, Any] | ForeignObjectRel | GenericForeignKey]",
+) -> int:
+    """Hash a model instance based on its field values.
+
+    Generates a hash for a Django model instance by considering the values
+    of its fields. This can be useful for comparing instances, especially
+    when dealing with related objects or complex data structures. The hash
+    is generated by recursively hashing related objects up to a specified
+    depth.
+    This is not very reliable, use with caution.
+    Only use if working with unsafed objects or bulks, as with safed
+
+    Args:
+        instance (Model): The Django model instance to hash
+        fields (list[str]): The fields to hash
+
+    Returns:
+        int: The hash value representing the instance's data
+
+    """
+    if instance.pk:
+        return hash(instance.pk)
+
+    field_names = get_field_names(fields)
+    model_dict = model_to_dict(instance, fields=field_names)
+    sorted_dict = dict(sorted(model_dict.items()))
+    values = (type(instance), tuple(sorted_dict.items()))
+    return hash(values)
+
+
+class BaseModel(Model):
+    """Base model for all models in the project.
+
+    Provides common fields and methods for all models.
+    """
+
+    created_at: DateTimeField[datetime, datetime] = DateTimeField(auto_now_add=True)
+    updated_at: DateTimeField[datetime, datetime] = DateTimeField(auto_now=True)
+
+    class Meta:
+        """Mark the model as abstract."""
+
+        # abstract does not inherit in children
+        abstract = True
+
+    def __str__(self) -> str:
+        """Base string representation of a model.
+
+        Returns:
+            str: The string representation of the model as all fields and their values.
+        """
+        fields_values = ", ".join(
+            f"{field.name}={getattr(self, field.name)}"
+            for field in get_fields(self.__class__)
+        )
+        return f"{self.__class__.__name__}({fields_values})"
+
+    def __repr__(self) -> str:
+        """Base representation of a model."""
+        return str(self)
+
+    @property
+    def meta(self) -> "Options[Self]":
+        """Get the meta options for the model."""
+        return self._meta