OxUtils

Production-ready utilities for Django applications in the Oxiliere ecosystem.

Features

• 🔐 JWT Authentication - RS256 with JWKS caching
• 📝 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

pip install oxutils

uv add oxutils

Quick Start

1. Configure Django Settings

# 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

OXI_SERVICE_NAME=my-service
OXI_JWT_JWKS_URL=https://auth.example.com/.well-known/jwks.json

3. Usage Examples

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


# 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 - Configuration reference
• JWT - Authentication
• Audit - Change tracking
• Logging - Structured logs
• Mixins - Model/service mixins
• Celery - Task processing

Additional Modules

• Currency - Exchange rates management
• PDF - PDF generation with WeasyPrint
• Oxiliere - Multi-tenant architecture

Requirements

• Python 3.12+
• Django 5.0+
• PostgreSQL (recommended)

Development

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:

make migrations
# or
uv run make_migrations.py

See MIGRATIONS.md for detailed documentation.

Optional Dependencies

# 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

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

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

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

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

# 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

Support

• Issues: GitHub Issues
• Email: dev@oxiliere.com

Made with ❤️ by Oxiliere