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

winidjango/src/db/models.py

@@ -1,8 +1,9 @@
-"""Database utilities for Django.
+"""Database utilities and lightweight model helpers.
 
-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.
+This module provides helpers used across the project when manipulating
+Django models: ordering models by foreign-key dependencies, creating a
+deterministic hash for unsaved instances, and a project-wide
+``BaseModel`` that exposes common timestamp fields.
 """
 
 from datetime import datetime
@@ -84,23 +85,26 @@ def hash_model_instance(
     instance: Model,
     fields: "list[Field[Any, Any] | ForeignObjectRel | GenericForeignKey]",
 ) -> int:
-    """Hash a model instance based on its field values.
+    """Compute a deterministic hash for a model instance.
 
-    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
+    The function returns a hash suitable for comparing unsaved model
+    instances by their field values. If the instance has a primary key
+    (``instance.pk``) that key is hashed and returned immediately; this
+    keeps comparisons cheap for persisted objects.
 
     Args:
-        instance (Model): The Django model instance to hash
-        fields (list[str]): The fields to hash
+        instance (Model): The Django model instance to hash.
+        fields (list[Field | ForeignObjectRel | GenericForeignKey]):
+            Field objects that should be included when computing the hash.
 
     Returns:
-        int: The hash value representing the instance's data
+        int: Deterministic integer hash of the instance. For persisted
+            instances this is ``hash(instance.pk)``.
 
+    Notes:
+        - The returned hash is intended for heuristic comparisons (e.g.
+          deduplication in import pipelines) and is not cryptographically
+          secure. Use with care when relying on absolute uniqueness.
     """
     if instance.pk:
         return hash(instance.pk)
@@ -113,9 +117,11 @@ def hash_model_instance(
 
 
 class BaseModel(Model):
-    """Base model for all models in the project.
+    """Abstract base model containing common fields and helpers.
 
-    Provides common fields and methods for all models.
+    Concrete models can inherit from this class to get consistent
+    ``created_at`` and ``updated_at`` timestamp fields and convenient
+    string representations.
     """
 
     created_at: DateTimeField[datetime, datetime] = DateTimeField(auto_now_add=True)
@@ -128,10 +134,13 @@ class BaseModel(Model):
         abstract = True
 
     def __str__(self) -> str:
-        """Base string representation of a model.
+        """Return a concise human-readable representation.
+
+        The default shows the model class name and primary key which is
+        useful for logging and interactive debugging.
 
         Returns:
-            str: The string representation of the model as all fields and their values.
+            str: Short representation, e.g. ``MyModel(123)``.
         """
         return f"{self.__class__.__name__}({self.pk})"
 
@@ -141,5 +150,9 @@ class BaseModel(Model):
 
     @property
     def meta(self) -> "Options[Self]":
-        """Get the meta options for the model."""
+        """Return the model's ``_meta`` options object.
+
+        This property is a small convenience wrapper used to make access
+        sites slightly more explicit in code and improve typing in callers.
+        """
         return self._meta

winidjango/src/db/sql.py

@@ -1,4 +1,14 @@
-"""Module for database operations with sql."""
+"""Low-level helper to execute raw SQL against Django's database.
+
+This module exposes :func:`execute_sql` which runs a parameterized SQL
+query using Django's database connection and returns column names and
+rows. It is intended for one-off queries where ORM abstractions are
+insufficient or when reading complex reports from the database.
+
+The helper uses Django's connection cursor context manager to ensure
+resources are cleaned up correctly. Results are fetched into memory so
+avoid using it for very large result sets.
+"""
 
 from typing import Any
 
@@ -7,51 +17,23 @@ from django.db import connection
 
 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.
+) -> tuple[list[str], list[tuple[Any, ...]]]:
+    """Execute a SQL statement and return column names and rows.
 
     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.
+        sql (str): SQL statement possibly containing named placeholders
+            (``%(name)s``) for database binding.
+        params (dict[str, Any] | None): Optional mapping of parameters to
+            bind to the query.
 
     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
-        Empty list if no results are returned
+        Tuple[List[str], List[Tuple[Any, ...]]]: A tuple where the first
+        element is the list of column names (empty list if the statement
+        returned no rows) and the second element is a list of row tuples.
 
     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
+        django.db.Error: Propagates underlying database errors raised by
+            Django's database backend.
     """
     with connection.cursor() as cursor:
         cursor.execute(sql=sql, params=params)

winidjango-2.0.31.dist-info/METADATA

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: winidjango
+Version: 2.0.31
+Summary: A utils package for django
+Author: Winipedia
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: django
+Requires-Dist: django-stubs-ext
+Requires-Dist: winiutils
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# winidjango
+
+<!-- tooling -->
+[![pyrig](https://img.shields.io/badge/built%20with-pyrig-3776AB?logo=buildkite&logoColor=black)](https://github.com/Winipedia/pyrig)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://pre-commit.com/)
+<!-- code-quality -->
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)[![mypy](https://img.shields.io/badge/type%20checked-mypy-039dfc.svg)](https://mypy-lang.org/)
+[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![pytest](https://img.shields.io/badge/tested%20with-pytest-46a2f1.svg?logo=pytest)](https://pytest.org/)
+[![codecov](https://codecov.io/gh/Winipedia/winidjango/branch/main/graph/badge.svg)](https://codecov.io/gh/Winipedia/winidjango)
+<!-- package-info -->
+[![PyPI](https://img.shields.io/pypi/v/winidjango?logo=pypi&logoColor=white)](https://pypi.org/project/winidjango/)
+[![Python](https://img.shields.io/badge/python-3.12|3.13|3.14-blue.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/github/license/Winipedia/winidjango)](https://github.com/Winipedia/winidjango/blob/main/LICENSE)
+<!-- ci/cd -->
+[![CI](https://img.shields.io/github/actions/workflow/status/Winipedia/winidjango/health_check.yaml?label=CI&logo=github)](https://github.com/Winipedia/winidjango/actions/workflows/health_check.yaml)
+[![CD](https://img.shields.io/github/actions/workflow/status/Winipedia/winidjango/release.yaml?label=CD&logo=github)](https://github.com/Winipedia/winidjango/actions/workflows/release.yaml)
+
+
+---
+
+> A utils package for django
+
+---
+
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Requirements](#requirements)
+- [Development](#development)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+### 🚀 High-Performance Bulk Operations
+- **Multithreaded Processing**: Parallel execution of database operations for maximum speed
+- **Automatic Chunking**: Configurable batch sizes (default: 1000) for memory-efficient processing
+- **Transaction Safety**: Atomic operations with intelligent transaction management
+- **Dependency Resolution**: Automatic topological sorting for foreign key relationships
+
+### 🛠️ Database Utilities
+- **Bulk Create/Update/Delete**: Process thousands of records efficiently
+- **Deletion Simulation**: Preview cascade effects before executing destructive operations
+- **Bulk Comparison**: Detect differences between datasets with field-level hashing
+- **Raw SQL Execution**: Safe parameter binding with automatic cursor management
+
+### 📦 Model Utilities
+- **BaseModel**: Abstract base with `created_at`, `updated_at`, and type-safe `meta` property
+- **Topological Sorting**: Automatic dependency ordering for model operations
+- **Field Introspection**: Type-safe utilities for working with model fields
+
+### 🎯 Management Command Framework
+- **ABCBaseCommand**: Template method pattern with automatic logging
+- **ImportDataBaseCommand**: Structured data import with Polars integration
+- **Built-in Arguments**: Standard options for dry-run, batch size, threading, and more
+- **Type Safety**: Full type hints with abstract method enforcement
+
+## Installation
+
+```bash
+pip install winidjango
+```
+
+Or using `uv`:
+
+```bash
+uv add winidjango
+```
+
+## Quick Start
+
+### Bulk Operations
+
+```python
+from winidjango.src.db.bulk import bulk_create_in_steps
+
+# Create 10,000 records in batches of 1000
+authors = [Author(name=f"Author {i}") for i in range(10000)]
+created = bulk_create_in_steps(Author, authors, step=1000)
+```
+
+### Automatic Dependency Resolution
+
+```python
+from winidjango.src.db.bulk import bulk_create_bulks_in_steps
+
+# Create related models in correct order automatically
+results = bulk_create_bulks_in_steps({
+    Author: authors,
+    Book: books,      # Created after Author
+    Review: reviews,  # Created after Book
+})
+```
+
+### Deletion Simulation
+
+```python
+from winidjango.src.db.bulk import simulate_bulk_deletion
+
+# Preview what would be deleted
+deletion_preview = simulate_bulk_deletion(Author, authors_to_delete)
+print(f"Would delete {len(deletion_preview[Author])} authors")
+print(f"Would cascade delete {len(deletion_preview[Book])} books")
+```
+
+### Custom Management Command
+
+```python
+from winidjango.src.commands.base.base import ABCBaseCommand
+from argparse import ArgumentParser
+
+class MyCommand(ABCBaseCommand):
+    def add_command_arguments(self, parser: ArgumentParser) -> None:
+        parser.add_argument('--input-file', type=str, required=True)
+
+    def handle_command(self) -> None:
+        input_file = self.get_option('input_file')
+        dry_run = self.get_option('dry_run')  # Built-in
+
+        if dry_run:
+            self.stdout.write('Dry run mode')
+
+        # Your logic here
+```
+
+### Data Import Command
+
+```python
+from winidjango.src.commands.import_data import ImportDataBaseCommand
+import polars as pl
+
+class ImportUsersCommand(ImportDataBaseCommand):
+    def handle_import(self) -> pl.DataFrame:
+        return pl.read_csv("users.csv")
+
+    def get_cleaning_df_cls(self) -> type[CleaningDF]:
+        return MyCleaningDF
+
+    def get_bulks_by_model(self, df: pl.DataFrame) -> dict[type[Model], Iterable[Model]]:
+        users = [User(name=row["name"]) for row in df.iter_rows(named=True)]
+        return {User: users}
+```
+
+## Documentation
+
+Comprehensive documentation is available in the [`docs/`](docs/) directory:
+
+- **[Database Utilities](docs/db.md)** - Bulk operations, model utilities, and SQL helpers
+- **[Management Commands](docs/commands.md)** - Command framework and data import patterns
+- **[API Reference](docs/index.md)** - Complete API documentation
+
+## Requirements
+
+- **Python**: 3.12+
+- **Django**: Compatible with modern Django versions
+- **Dependencies**:
+  - `django`
+  - `django-stubs-ext`
+  - `winiutils`
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Winipedia/winidjango.git
+cd winidjango
+
+# Install dependencies
+uv sync
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+### Code Quality
+
+This project uses:
+- **mypy**: Strict type checking
+- **ruff**: Linting and formatting
+- **bandit**: Security analysis
+- **pytest**: Testing framework
+
+```bash
+# Run type checking
+mypy .
+
+# Run linting
+ruff check .
+
+# Run security checks
+bandit -r winidjango
+
+# Format code
+ruff format .
+```
+
+## Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=winidjango
+
+# Run specific test file
+pytest tests/test_winidjango/test_src/test_db/test_bulk.py
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [pyrig](https://github.com/Winipedia/pyrig) - Python project scaffolding tool
+- Integrates with [winiutils](https://github.com/Winipedia/winiutils) - General Python utilities
+
+---

winidjango-2.0.31.dist-info/RECORD

@@ -0,0 +1,27 @@
+winidjango/__init__.py,sha256=pxCy4ywQWxN3MKjm9U2vcIDz-nsvDLgNzsE9IOq15DQ,823
+winidjango/dev/__init__.py,sha256=XHsbmjiaGom-KX-S3leCY9cJD3aP9p_0X6xYMcdkHBU,23
+winidjango/dev/builders/__init__.py,sha256=XHsbmjiaGom-KX-S3leCY9cJD3aP9p_0X6xYMcdkHBU,23
+winidjango/dev/cli/__init__.py,sha256=XHsbmjiaGom-KX-S3leCY9cJD3aP9p_0X6xYMcdkHBU,23
+winidjango/dev/cli/subcommands.py,sha256=iurWZwJwEKAfGpfjkn1YOhnRbIruCB4ouE-8R_Lh3JY,228
+winidjango/dev/configs/__init__.py,sha256=XHsbmjiaGom-KX-S3leCY9cJD3aP9p_0X6xYMcdkHBU,23
+winidjango/dev/configs/configs.py,sha256=N85kVaRHCHXc-ny0jbuYQwTcrxQJx_X_BcG30IcyrGw,586
+winidjango/dev/tests/__init__.py,sha256=XHsbmjiaGom-KX-S3leCY9cJD3aP9p_0X6xYMcdkHBU,23
+winidjango/dev/tests/fixtures/__init__.py,sha256=XHsbmjiaGom-KX-S3leCY9cJD3aP9p_0X6xYMcdkHBU,23
+winidjango/main.py,sha256=TdxQpUtNZIiYCsEdysMlQW-1UNy0__WTax-Ot5E2eYQ,144
+winidjango/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+winidjango/resources/__init__.py,sha256=XHsbmjiaGom-KX-S3leCY9cJD3aP9p_0X6xYMcdkHBU,23
+winidjango/src/__init__.py,sha256=LOIpCo9zHZCs_ifeiw3PLILm6ik1hyIHJNC9gYir1Eg,569
+winidjango/src/commands/__init__.py,sha256=5rI9IBYLsGpwbdxPzEP21EWlRFC0-6EzTm3NRc758Fk,376
+winidjango/src/commands/base/__init__.py,sha256=ZpOXolcoL9RnhppgzKqF0581gcLcsjin8hydYUd_QZc,320
+winidjango/src/commands/base/base.py,sha256=SeJxHiH_YA2J0bEhGGScniXcwekFLUB8MmdCTJ5hGik,6162
+winidjango/src/commands/import_data.py,sha256=kQatdfQ7HRH2VFSwmVGx6s4J7AAh2FKatTEqWLQDScI,4354
+winidjango/src/db/__init__.py,sha256=x1zuU0bJMuPxqhBAW6g7Ob8BrcC0wyW_NlLn9S4ZaqI,323
+winidjango/src/db/bulk.py,sha256=5mJyGyt3vtu8cf-xji3dd2zxAU5eH0tuV85RjXIMriw,20110
+winidjango/src/db/fields.py,sha256=sa_qe36rQoh7zzsgbadsREKYOqzgx0WDar5tPdZ4rpE,2098
+winidjango/src/db/models.py,sha256=LBdN1pbG4jp_yy_pEKdXxNd05ZXAVCkj7srvO-UE1vw,5750
+winidjango/src/db/sql.py,sha256=MMiJyc8uhJ_4VcN2s6i8koNfvDKxsSv3Gpb_kD-01IE,1638
+winidjango-2.0.31.dist-info/licenses/LICENSE,sha256=o316mE2gGzd__JT69p7S_zlOmKiHh8YjpImCCcWyTvM,1066
+winidjango-2.0.31.dist-info/WHEEL,sha256=xDCZ-UyfvkGuEHPeI7BcJzYKIZzdqN8A8o1M5Om8IyA,79
+winidjango-2.0.31.dist-info/entry_points.txt,sha256=qM1ENsRWSLulhF8Cy92TeHW-4v8SAgzkRW7hNHXHG-4,55
+winidjango-2.0.31.dist-info/METADATA,sha256=s5VV6RvdhZvKXCiOTvHlsuoNPVzGKBWo-LmqGMoUNfU,8263
+winidjango-2.0.31.dist-info/RECORD,,

winidjango-2.0.31.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.17
+Root-Is-Purelib: true
+Tag: py3-none-any

winidjango-2.0.31.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+winidjango = pyrig.dev.cli.cli:main
+

winidjango/dev/artifacts/builder/builder.py

@@ -1,4 +0,0 @@
-"""Build script.
-
-All subclasses of Builder in the builds package are automatically called.
-"""