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

Release files for winidjango 4.15.9

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.15.9
File	Size	Uploaded
winidjango-4.15.9.tar.gz	19.8 kB	Sep 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for winidjango 4.15.9
File	Interpreter	ABI	Platform	Reset
winidjango-4.15.9-py3-none-any.whl 26.2 kB Sep 3, 2026	Python 3	none	any	Details

Total release size: 46.1 kB

Release files / winidjango-4.15.9.tar.gz

Download URL	winidjango-4.15.9.tar.gz
Size	19.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`2dfaebac310d1bb94cc74f0d399bde3354dbaf5913ff1ff3f97e0fcf730c72a0`
BLAKE2b-256 checksum How to use checksums	`df262cf0050413959a95182c8e88820be5d5b858f7ff746ea0bbfab93859ffe4`
Upload date	Sep 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","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.15.9-py3-none-any.whl

Download URL	winidjango-4.15.9-py3-none-any.whl
Size	26.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6eb4bae865511e511b7eb96ef7c969653d123175a9746837700bff2bebb19bd9`
BLAKE2b-256 checksum How to use checksums	`97eabb84ce6a657a4e2cea5a5056fcfbc7f3a9018cc45c5dba95a7766ef7c011`
Upload date	Sep 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","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}`