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
Metadata
1 maintainer
Release files for winidjango 4.15.48
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| winidjango-4.15.48.tar.gz | 20.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| winidjango-4.15.48-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 46.3 kB
Release files / winidjango-4.15.48.tar.gz
| Download URL | winidjango-4.15.48.tar.gz |
|---|---|
| Size | 20.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
607c9322be8877fff89be90dc758fb52f7ca2394c88d9a350109d0529bf0f064
|
|
BLAKE2b-256 checksum How to use checksums |
2ebee9f52463b414e33066ad9c529cd2d31d53918a9a230ca3a9cb13f2bf8e42
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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.48-py3-none-any.whl
| Download URL | winidjango-4.15.48-py3-none-any.whl |
|---|---|
| Size | 26.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8869b8203409cfdfe21ae4fc361418b8d254df85c3c18cd23d73d01084aba849
|
|
BLAKE2b-256 checksum How to use checksums |
7e3a935b702a9351b9879a903e8112c9713a9621c462cd61779d285995b3ac40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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}
|
