winidjango

A utility package for django

Features
Installation
Quick Start
Documentation
Requirements
Development
Testing
Contributing
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

pip install winidjango

Or using uv:

uv add winidjango

Quick Start

Bulk Operations

from winidjango.core.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

from winidjango.core.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

from winidjango.core.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

from winidjango.core.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

from winidjango.core.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/ directory:

Database Utilities
- Bulk operations, model utilities, and SQL helpers
Management Commands - Command framework and data import patterns
API Reference - Complete API documentation

Requirements

Python: 3.12+
Django: Compatible with modern Django versions
Dependencies:
- django
- django-stubs-ext
- winiutils

Development

Setup

# 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

# Run type checking
mypy .

# Run linting
ruff check .

# Run security checks
bandit -r winidjango

# Format code
ruff format .

Testing

# 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.

Fork the repository
Create your feature branch (git switch -c feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License, see the LICENSE file for details.

Acknowledgments

Built with pyrig - Python project scaffolding tool
Integrates with winiutils - General Python utilities

Metadata

Release files for winidjango 4.16.11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for winidjango 4.16.11
File	Size	Uploaded	Provenance
winidjango-4.16.11.tar.gz	21.5 kB	Oct 24, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for winidjango 4.16.11
File	Interpreter	ABI	Platform	Reset
winidjango-4.16.11-py3-none-any.whl 26.4 kB Oct 24, 2026 Without provenance	Python 3	none	any	Details

Total release size: 47.9 kB

Release files / winidjango-4.16.11.tar.gz

Download URL	winidjango-4.16.11.tar.gz
Size	21.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`18b3a93ada4e5dd4ee432f8a76fccd418c5279257d7162d72371766de7289706`
BLAKE2b-256 checksum How to use checksums	`2cb7b4ee8a91434b2b7a8338feb003de64f660daa8a64b8fbb11ec00cb6aa571`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / winidjango-4.16.11-py3-none-any.whl

Download URL	winidjango-4.16.11-py3-none-any.whl
Size	26.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f934e0ed64cc93af7d1193a78e01660e715c3ed8ae9b87c34a019f403e0c94b7`
BLAKE2b-256 checksum How to use checksums	`d22c1e3b5a3d506a5637c5236f1217ddd260c562056bca7c4f3643b2b9c3294d`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Security for winidjango 4.16.11

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.