oxutils 0.1.5__tar.gz

oxutils-0.1.5/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: oxutils
+Version: 0.1.5
+Summary: Production-ready utilities for Django applications in the Oxiliere ecosystem
+Keywords: django,utilities,jwt,s3,audit,logging,celery,structlog
+Author: Edimedia Mutoke
+Author-email: Edimedia Mutoke <eddycondor07@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Dist: boto3>=1.41.5
+Requires-Dist: celery>=5.5.3
+Requires-Dist: cryptography>=46.0.3
+Requires-Dist: django-auditlog>=3.3.0
+Requires-Dist: django-celery-results>=2.6.0
+Requires-Dist: django-extensions>=4.1
+Requires-Dist: django-ninja>=1.5.0
+Requires-Dist: django-ninja-extra>=0.30.6
+Requires-Dist: django-storages[s3]>=1.14.6
+Requires-Dist: django-structlog[celery]>=10.0.0
+Requires-Dist: jwcrypto>=1.5.6
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: requests>=2.32.5
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/oxiliere/oxutils/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/oxiliere/oxutils/tree/main/docs
+Project-URL: Homepage, https://github.com/oxiliere/oxutils
+Project-URL: Issues, https://github.com/oxiliere/oxutils/issues
+Project-URL: Repository, https://github.com/oxiliere/oxutils
+Description-Content-Type: text/markdown
+
+# OxUtils
+
+**Production-ready utilities for Django applications in the Oxiliere ecosystem.**
+
+[![PyPI version](https://img.shields.io/pypi/v/oxutils.svg)](https://pypi.org/project/oxutils/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
+[![Django 5.0+](https://img.shields.io/badge/django-5.0+-green.svg)](https://www.djangoproject.com/)
+[![Tests](https://img.shields.io/badge/tests-201%20passed-success.svg)](tests/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+## Features
+
+- 🔐 **JWT Authentication** - RS256 with JWKS caching
+- 📦 **S3 Storage** - Static, media, private, and log backends
+- 📝 **Structured Logging** - JSON logs with automatic request tracking
+- 🔍 **Audit System** - Change tracking with S3 export
+- ⚙️ **Celery Integration** - Pre-configured task processing
+- 🛠️ **Django Mixins** - UUID, timestamps, user tracking
+- ⚡ **Custom Exceptions** - Standardized API errors
+- 🎨 **Context Processors** - Site name and domain for templates
+- 💱 **Currency Module** - Multi-source exchange rates (BCC/OXR)
+- 📄 **PDF Generation** - WeasyPrint integration for Django
+- 🏢 **Multi-Tenant** - PostgreSQL schema-based isolation
+
+---
+
+## Installation
+
+```bash
+pip install oxutils
+```
+
+```bash
+uv add oxutils
+```
+
+## Quick Start
+
+### 1. Configure Django Settings
+
+```python
+# settings.py
+from oxutils.conf import UTILS_APPS, AUDIT_MIDDLEWARE
+
+INSTALLED_APPS = [
+    *UTILS_APPS,  # structlog, auditlog, celery_results
+    # your apps...
+]
+
+MIDDLEWARE = [
+    *AUDIT_MIDDLEWARE,  # RequestMiddleware, Auditlog
+    # your middleware...
+]
+```
+
+### 2. Environment Variables
+
+```bash
+OXI_SERVICE_NAME=my-service
+OXI_JWT_JWKS_URL=https://auth.example.com/.well-known/jwks.json
+OXI_USE_STATIC_S3=True
+OXI_STATIC_STORAGE_BUCKET_NAME=my-bucket
+```
+
+### 3. Usage Examples
+
+```python
+# JWT Authentication
+from oxutils.jwt.client import verify_token
+payload = verify_token(token)
+
+# Structured Logging
+import structlog
+logger = structlog.get_logger(__name__)
+logger.info("user_action", user_id=user_id)
+
+# S3 Storage
+from oxutils.s3.storages import PrivateMediaStorage
+class Document(models.Model):
+    file = models.FileField(storage=PrivateMediaStorage())
+
+# Model Mixins
+from oxutils.models.base import BaseModelMixin
+class Product(BaseModelMixin):  # UUID + timestamps + is_active
+    name = models.CharField(max_length=255)
+
+# Custom Exceptions
+from oxutils.exceptions import NotFoundException
+raise NotFoundException(detail="User not found")
+
+# Context Processors
+# settings.py
+TEMPLATES = [{
+    'OPTIONS': {
+        'context_processors': [
+            'oxutils.context.site_name_processor.site_name',
+        ],
+    },
+}]
+# Now {{ site_name }} and {{ site_domain }} are available in templates
+```
+
+## Documentation
+
+### Core Modules
+- **[Settings](docs/settings.md)** - Configuration reference
+- **[JWT](docs/jwt.md)** - Authentication
+- **[S3](docs/s3.md)** - Storage backends
+- **[Audit](docs/audit.md)** - Change tracking
+- **[Logging](docs/logger.md)** - Structured logs
+- **[Mixins](docs/mixins.md)** - Model/service mixins
+- **[Celery](docs/celery.md)** - Task processing
+
+### Additional Modules
+- **[Currency](docs/currency.md)** - Exchange rates management
+- **[PDF](docs/pdf.md)** - PDF generation with WeasyPrint
+- **[Oxiliere](docs/oxiliere.md)** - Multi-tenant architecture
+
+## Requirements
+
+- Python 3.12+
+- Django 5.0+
+- PostgreSQL (recommended)
+
+## Development
+
+```bash
+git clone https://github.com/oxiliere/oxutils.git
+cd oxutils
+uv sync
+uv run pytest  # 201 tests passing, 4 skipped
+```
+
+### Creating Migrations
+
+To generate Django migrations for the audit module:
+
+```bash
+make migrations
+# or
+uv run make_migrations.py
+```
+
+See [MIGRATIONS.md](MIGRATIONS.md) for detailed documentation.
+
+## Optional Dependencies
+
+```bash
+# Multi-tenant support
+uv add oxutils[oxiliere]
+
+# PDF generation
+uv add oxutils[pdf]
+
+# Development tools
+uv add oxutils[dev]
+```
+
+## Advanced Examples
+
+### JWT with Django Ninja
+
+```python
+from ninja import NinjaAPI
+from ninja.security import HttpBearer
+from oxutils.jwt.client import verify_token
+
+class JWTAuth(HttpBearer):
+    def authenticate(self, request, token):
+        try:
+            return verify_token(token)
+        except:
+            return None
+
+api = NinjaAPI(auth=JWTAuth())
+
+@api.get("/protected")
+def protected(request):
+    return {"user_id": request.auth['sub']}
+```
+
+### Audit Log Export
+
+```python
+from oxutils.audit.export import export_logs_from_date
+from datetime import datetime, timedelta
+
+from_date = datetime.now() - timedelta(days=7)
+export = export_logs_from_date(from_date=from_date)
+print(f"Exported to {export.data.url}")
+```
+
+### Currency Exchange Rates
+
+```python
+from oxutils.currency.models import CurrencyState
+
+# Sync rates from BCC (with OXR fallback)
+state = CurrencyState.sync()
+
+# Get latest rates
+latest = CurrencyState.objects.latest()
+usd_rate = latest.currencies.get(code='USD').rate
+eur_rate = latest.currencies.get(code='EUR').rate
+```
+
+### PDF Generation
+
+```python
+from oxutils.pdf.printer import Printer
+from oxutils.pdf.views import WeasyTemplateView
+
+# Standalone PDF generation
+printer = Printer(
+    template_name='invoice.html',
+    context={'invoice': invoice},
+    stylesheets=['css/invoice.css']
+)
+pdf_bytes = printer.write_pdf()
+
+# Class-based view
+class InvoicePDFView(WeasyTemplateView):
+    template_name = 'invoice.html'
+    pdf_filename = 'invoice.pdf'
+    pdf_stylesheets = ['css/invoice.css']
+```
+
+### Multi-Tenant Setup
+
+```python
+# settings.py
+TENANT_MODEL = "oxiliere.Tenant"
+MIDDLEWARE = [
+    'oxutils.oxiliere.middleware.TenantMainMiddleware',  # First!
+    # other middleware...
+]
+
+# All requests must include X-Organization-ID header
+# Data is automatically isolated per tenant schema
+```
+
+## License
+
+Apache 2.0 License - see [LICENSE](LICENSE)
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/oxiliere/oxutils/issues)
+- **Email**: dev@oxiliere.com
+
+---
+
+**Made with ❤️ by Oxiliere**

oxutils-0.1.5/README.md

@@ -0,0 +1,254 @@
+# OxUtils
+
+**Production-ready utilities for Django applications in the Oxiliere ecosystem.**
+
+[![PyPI version](https://img.shields.io/pypi/v/oxutils.svg)](https://pypi.org/project/oxutils/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
+[![Django 5.0+](https://img.shields.io/badge/django-5.0+-green.svg)](https://www.djangoproject.com/)
+[![Tests](https://img.shields.io/badge/tests-201%20passed-success.svg)](tests/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+## Features
+
+- 🔐 **JWT Authentication** - RS256 with JWKS caching
+- 📦 **S3 Storage** - Static, media, private, and log backends
+- 📝 **Structured Logging** - JSON logs with automatic request tracking
+- 🔍 **Audit System** - Change tracking with S3 export
+- ⚙️ **Celery Integration** - Pre-configured task processing
+- 🛠️ **Django Mixins** - UUID, timestamps, user tracking
+- ⚡ **Custom Exceptions** - Standardized API errors
+- 🎨 **Context Processors** - Site name and domain for templates
+- 💱 **Currency Module** - Multi-source exchange rates (BCC/OXR)
+- 📄 **PDF Generation** - WeasyPrint integration for Django
+- 🏢 **Multi-Tenant** - PostgreSQL schema-based isolation
+
+---
+
+## Installation
+
+```bash
+pip install oxutils
+```
+
+```bash
+uv add oxutils
+```
+
+## Quick Start
+
+### 1. Configure Django Settings
+
+```python
+# settings.py
+from oxutils.conf import UTILS_APPS, AUDIT_MIDDLEWARE
+
+INSTALLED_APPS = [
+    *UTILS_APPS,  # structlog, auditlog, celery_results
+    # your apps...
+]
+
+MIDDLEWARE = [
+    *AUDIT_MIDDLEWARE,  # RequestMiddleware, Auditlog
+    # your middleware...
+]
+```
+
+### 2. Environment Variables
+
+```bash
+OXI_SERVICE_NAME=my-service
+OXI_JWT_JWKS_URL=https://auth.example.com/.well-known/jwks.json
+OXI_USE_STATIC_S3=True
+OXI_STATIC_STORAGE_BUCKET_NAME=my-bucket
+```
+
+### 3. Usage Examples
+
+```python
+# JWT Authentication
+from oxutils.jwt.client import verify_token
+payload = verify_token(token)
+
+# Structured Logging
+import structlog
+logger = structlog.get_logger(__name__)
+logger.info("user_action", user_id=user_id)
+
+# S3 Storage
+from oxutils.s3.storages import PrivateMediaStorage
+class Document(models.Model):
+    file = models.FileField(storage=PrivateMediaStorage())
+
+# Model Mixins
+from oxutils.models.base import BaseModelMixin
+class Product(BaseModelMixin):  # UUID + timestamps + is_active
+    name = models.CharField(max_length=255)
+
+# Custom Exceptions
+from oxutils.exceptions import NotFoundException
+raise NotFoundException(detail="User not found")
+
+# Context Processors
+# settings.py
+TEMPLATES = [{
+    'OPTIONS': {
+        'context_processors': [
+            'oxutils.context.site_name_processor.site_name',
+        ],
+    },
+}]
+# Now {{ site_name }} and {{ site_domain }} are available in templates
+```
+
+## Documentation
+
+### Core Modules
+- **[Settings](docs/settings.md)** - Configuration reference
+- **[JWT](docs/jwt.md)** - Authentication
+- **[S3](docs/s3.md)** - Storage backends
+- **[Audit](docs/audit.md)** - Change tracking
+- **[Logging](docs/logger.md)** - Structured logs
+- **[Mixins](docs/mixins.md)** - Model/service mixins
+- **[Celery](docs/celery.md)** - Task processing
+
+### Additional Modules
+- **[Currency](docs/currency.md)** - Exchange rates management
+- **[PDF](docs/pdf.md)** - PDF generation with WeasyPrint
+- **[Oxiliere](docs/oxiliere.md)** - Multi-tenant architecture
+
+## Requirements
+
+- Python 3.12+
+- Django 5.0+
+- PostgreSQL (recommended)
+
+## Development
+
+```bash
+git clone https://github.com/oxiliere/oxutils.git
+cd oxutils
+uv sync
+uv run pytest  # 201 tests passing, 4 skipped
+```
+
+### Creating Migrations
+
+To generate Django migrations for the audit module:
+
+```bash
+make migrations
+# or
+uv run make_migrations.py
+```
+
+See [MIGRATIONS.md](MIGRATIONS.md) for detailed documentation.
+
+## Optional Dependencies
+
+```bash
+# Multi-tenant support
+uv add oxutils[oxiliere]
+
+# PDF generation
+uv add oxutils[pdf]
+
+# Development tools
+uv add oxutils[dev]
+```
+
+## Advanced Examples
+
+### JWT with Django Ninja
+
+```python
+from ninja import NinjaAPI
+from ninja.security import HttpBearer
+from oxutils.jwt.client import verify_token
+
+class JWTAuth(HttpBearer):
+    def authenticate(self, request, token):
+        try:
+            return verify_token(token)
+        except:
+            return None
+
+api = NinjaAPI(auth=JWTAuth())
+
+@api.get("/protected")
+def protected(request):
+    return {"user_id": request.auth['sub']}
+```
+
+### Audit Log Export
+
+```python
+from oxutils.audit.export import export_logs_from_date
+from datetime import datetime, timedelta
+
+from_date = datetime.now() - timedelta(days=7)
+export = export_logs_from_date(from_date=from_date)
+print(f"Exported to {export.data.url}")
+```
+
+### Currency Exchange Rates
+
+```python
+from oxutils.currency.models import CurrencyState
+
+# Sync rates from BCC (with OXR fallback)
+state = CurrencyState.sync()
+
+# Get latest rates
+latest = CurrencyState.objects.latest()
+usd_rate = latest.currencies.get(code='USD').rate
+eur_rate = latest.currencies.get(code='EUR').rate
+```
+
+### PDF Generation
+
+```python
+from oxutils.pdf.printer import Printer
+from oxutils.pdf.views import WeasyTemplateView
+
+# Standalone PDF generation
+printer = Printer(
+    template_name='invoice.html',
+    context={'invoice': invoice},
+    stylesheets=['css/invoice.css']
+)
+pdf_bytes = printer.write_pdf()
+
+# Class-based view
+class InvoicePDFView(WeasyTemplateView):
+    template_name = 'invoice.html'
+    pdf_filename = 'invoice.pdf'
+    pdf_stylesheets = ['css/invoice.css']
+```
+
+### Multi-Tenant Setup
+
+```python
+# settings.py
+TENANT_MODEL = "oxiliere.Tenant"
+MIDDLEWARE = [
+    'oxutils.oxiliere.middleware.TenantMainMiddleware',  # First!
+    # other middleware...
+]
+
+# All requests must include X-Organization-ID header
+# Data is automatically isolated per tenant schema
+```
+
+## License
+
+Apache 2.0 License - see [LICENSE](LICENSE)
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/oxiliere/oxutils/issues)
+- **Email**: dev@oxiliere.com
+
+---
+
+**Made with ❤️ by Oxiliere**

oxutils-0.1.5/pyproject.toml

@@ -0,0 +1,111 @@
+[project]
+name = "oxutils"
+version = "0.1.5"
+description = "Production-ready utilities for Django applications in the Oxiliere ecosystem"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Edimedia Mutoke", email = "eddycondor07@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = ["django", "utilities", "jwt", "s3", "audit", "logging", "celery", "structlog"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Django",
+    "Framework :: Django :: 5.0",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "boto3>=1.41.5",
+    "celery>=5.5.3",
+    "cryptography>=46.0.3",
+    "django-auditlog>=3.3.0",
+    "django-celery-results>=2.6.0",
+    "django-extensions>=4.1",
+    "django-ninja>=1.5.0",
+    "django-ninja-extra>=0.30.6",
+    "django-storages[s3]>=1.14.6",
+    "django-structlog[celery]>=10.0.0",
+    "jwcrypto>=1.5.6",
+    "pydantic-settings>=2.12.0",
+    "pyjwt>=2.10.1",
+    "requests>=2.32.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/oxiliere/oxutils"
+Documentation = "https://github.com/oxiliere/oxutils/tree/main/docs"
+Repository = "https://github.com/oxiliere/oxutils"
+Issues = "https://github.com/oxiliere/oxutils/issues"
+Changelog = "https://github.com/oxiliere/oxutils/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.workspace]
+members = [
+    ".",
+]
+
+[tool.uv.sources]
+oxutils = { workspace = true }
+
+[dependency-groups]
+currency = [
+    "bcc-rates>=1.1.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-django>=4.8.0",
+    "pytest-cov>=4.1.0",
+    "pytest-mock>=3.12.0",
+    "coverage>=7.4.0",
+    "pillow>=12.0.0",
+    "ruff>=0.8.0",
+]
+oxiliere = [
+    "django-cacheops>=7.2",
+    "django-tenants>=3.9.0",
+]
+pdf = [
+    "weasyprint>=67.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+exclude = [
+    ".git",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+]
+
+[tool.pytest.ini_options]
+pythonpath = [".", "src"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short --ds=tests.settings"
+testpaths = ["tests"]

oxutils-0.1.5/src/oxutils/__init__.py

@@ -0,0 +1,23 @@
+"""OxUtils - Production-ready utilities for Django applications.
+
+This package provides:
+- JWT authentication with JWKS support
+- S3 storage backends (static, media, private, logs)
+- Structured logging with correlation IDs
+- Audit system with S3 export
+- Celery integration
+- Django model mixins
+- Custom exceptions
+"""
+
+__version__ = "0.1.5"
+
+from oxutils.settings import oxi_settings
+from oxutils.conf import UTILS_APPS, AUDIT_MIDDLEWARE
+
+__all__ = [
+    "oxi_settings",
+    "UTILS_APPS",
+    "AUDIT_MIDDLEWARE",
+    "__version__",
+]

oxutils-0.1.5/src/oxutils/apps.py

@@ -0,0 +1,14 @@
+from django.apps import AppConfig
+from django.utils.translation import gettext_lazy as _
+
+
+
+class OxutilsConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'oxutils'
+    verbose_name = _("Oxiliere Utilities")
+
+    def ready(self):
+        import oxutils.logger.receivers
+        
+        return super().ready()

oxutils-0.1.5/src/oxutils/audit/__init__.py

@@ -0,0 +1,20 @@
+"""
+Oxutils Audit Module
+
+Provides audit log export functionality with S3 storage.
+"""
+
+# Models are imported lazily to avoid AppRegistryNotReady errors
+# Use: from oxutils.audit.models import LogExportState, LogExportHistory
+
+__all__ = [
+    'LogExportState',
+    'LogExportHistory',
+]
+
+def __getattr__(name):
+    """Lazy import of models to avoid AppRegistryNotReady errors."""
+    if name in __all__:
+        from oxutils.audit.models import LogExportState, LogExportHistory
+        return locals()[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")