winidjango
A utility package for django
Table of Contents
- 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-safemetaproperty - 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:
djangodjango-stubs-extwiniutils
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
winidjango-4.14.25.tar.gz
(19.2 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file winidjango-4.14.25.tar.gz.
File metadata
- Download URL: winidjango-4.14.25.tar.gz
- Upload date:
- Size: 19.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
516481f9eb0aa8c8cfb8f671b4a25f32f0e27c7abe69f4c84e250f2f69a06cff
|
|
| MD5 |
b90d5fbf1b78febd5d0f3541f53c8e0a
|
|
| BLAKE2b-256 |
eba5d7d62d9d3cbfcf5d0583ecd1132d33b71731fea5e41e4b83844aef7e2ce6
|
File details
Details for the file winidjango-4.14.25-py3-none-any.whl.
File metadata
- Download URL: winidjango-4.14.25-py3-none-any.whl
- Upload date:
- Size: 25.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5537e877a8cfe21bf3412f3d9e2fb2392badbe88dd659564b010a836deef7bf0
|
|
| MD5 |
0ca16e89e445248a9242e48bdde94263
|
|
| BLAKE2b-256 |
e2bd5f0e8d0033fd64eca6b7cd241a5e9058d150fdf81a43058cd7ec80fb91cd
|
