oxutils 0.4.2__tar.gz → 0.4.4__tar.gz

{oxutils-0.4.2 → oxutils-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxutils
-Version: 0.4.2
+Version: 0.4.4
 Summary: Production-ready utilities for Django applications in the Oxiliere ecosystem
 Keywords: django,utilities,jwt,audit,logging,celery,structlog
 Author: Edimedia Mutoke

{oxutils-0.4.2 → oxutils-0.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oxutils"
-version = "0.4.2"
+version = "0.4.4"
 description = "Production-ready utilities for Django applications in the Oxiliere ecosystem"
 readme = "README.md"
 license = "LGPL-3.0-only"

oxutils-0.4.4/src/oxutils/__init__.py

@@ -0,0 +1,53 @@
+"""OxUtils — Production-ready Django utilities for multi-tenant SaaS.
+
+Authentication & authorization:
+    - JWT authentication: Bearer, Cookie, and passive backends with JWKS support
+    - RBAC permissions: roles, groups, user grants with scope-based access
+      control (``ScopePermission``, ``ScopeAnyPermission``, etc.)
+    - Auto-discovery of permission presets from installed apps
+    - Complete auth system: registration, login/logout, password reset,
+      MFA, invitations, sessions — integrates with django-allauth
+    - Api exceptions with error codes and structured responses
+
+Multi-tenancy:
+    - django-tenants integration with ``X-Organization-ID`` header routing
+    - Tenant / tenant-user models, schema-aware middleware and caching
+    - Tenant lifecycle signals, authorization, and system-tenant fallback
+
+Infrastructure & tooling:
+    - Structured logging with correlation IDs, request metadata binding,
+      and pre-built ``LOGGING`` configuration (structlog)
+    - Audit log export to S3 with export-state tracking and status history
+    - Cursor-based pagination for Django Ninja APIs
+    - PDF generation via WeasyPrint (``Printer`` class and ``WeasyTemplateView``)
+    - Multi-currency support with rate syncing (BCC, Open Exchange Rates)
+    - Celery app with task auto-discovery and structlog integration
+    - S3 storage backend factory with env-var configuration
+
+Model utilities:
+    - Reusable mixins: UUID PK, timestamps, user tracking, slug, ordering,
+      soft-delete with field masking (``SafeDeleteModelMixin``),
+      change tracking, invoicing, and billing
+    - Custom user model with email-based auth, ``oxi_id`` linking, and audit
+    - Custom Pydantic types (``EmailApiType``, etc.)
+
+Other:
+    - HTTP header/cookie constants (oxi tokens, JWT tokens)
+    - Template context processor (site name & domain)
+    - Central pydantic-settings configuration (``oxi_settings``)
+    - Shared enums (invoice status, export status)
+    - Utility helpers: client IP detection, absolute URL building,
+      image validation, bound-request detection
+"""
+
+__version__ = "0.4.4"
+
+from oxutils.conf import AUDIT_MIDDLEWARE, UTILS_APPS
+from oxutils.settings import oxi_settings
+
+__all__ = [
+    "oxi_settings",
+    "UTILS_APPS",
+    "AUDIT_MIDDLEWARE",
+    "__version__",
+]

{oxutils-0.4.2 → oxutils-0.4.4}/src/oxutils/celery/base.py

@@ -30,6 +30,9 @@ def receiver_setup_logging(loglevel, logfile, format, colorize, **kwargs):  # pr
                "json_formatter": {
                    "()": structlog.stdlib.ProcessorFormatter,
                    "processor": structlog.processors.JSONRenderer(),
+                   "foreign_pre_chain": [
+                       structlog.processors.format_exc_info,
+                   ],
                },
                "plain_console": {
                    "()": structlog.stdlib.ProcessorFormatter,
@@ -40,6 +43,9 @@ def receiver_setup_logging(loglevel, logfile, format, colorize, **kwargs):  # pr
                    "processor": structlog.processors.KeyValueRenderer(
                         key_order=['timestamp', 'level', 'event', 'logger']
                     ),
+                   "foreign_pre_chain": [
+                       structlog.processors.format_exc_info,
+                   ],
                },
            },
            "handlers": {
@@ -88,7 +94,6 @@ def receiver_setup_logging(loglevel, logfile, format, colorize, **kwargs):  # pr
             structlog.stdlib.add_log_level,
             structlog.stdlib.PositionalArgumentsFormatter(),
             structlog.processors.StackInfoRenderer(),
-            structlog.processors.format_exc_info,
             structlog.processors.UnicodeDecoder(),
             structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
         ],

{oxutils-0.4.2 → oxutils-0.4.4}/src/oxutils/logger/settings.py

@@ -16,6 +16,9 @@ LOGGING = {
         "json_formatter": {
             "()": structlog.stdlib.ProcessorFormatter,
             "processor": structlog.processors.JSONRenderer(),
+            "foreign_pre_chain": [
+                structlog.processors.format_exc_info,
+            ],
         },
         "plain_console": {
             "()": structlog.stdlib.ProcessorFormatter,
@@ -54,7 +57,6 @@ structlog.configure(
         structlog.stdlib.add_log_level,
         structlog.stdlib.PositionalArgumentsFormatter(),
         structlog.processors.StackInfoRenderer(),
-        structlog.processors.format_exc_info,
         structlog.processors.UnicodeDecoder(),
         structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
     ],

oxutils-0.4.4/src/oxutils/permissions/__init__.py

@@ -0,0 +1 @@
+

oxutils-0.4.4/src/oxutils/permissions/apps.py

@@ -0,0 +1,23 @@
+from django.apps import AppConfig
+from django.conf import settings
+
+
+class PermissionsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "oxutils.permissions"
+
+    def ready(self):
+        """Import checks when app is ready."""
+        from . import checks  # noqa
+
+        from .presets import (
+            register_preset,
+            register_access_scopes,
+            register_access_applications,
+        )
+
+        if hasattr(settings, "PERMISSION_PRESET"):
+            register_preset(settings.PERMISSION_PRESET)
+
+        register_access_applications()
+        register_access_scopes()

{oxutils-0.4.2 → oxutils-0.4.4}/src/oxutils/permissions/checks.py

@@ -291,4 +291,40 @@ def check_permission_settings(app_configs, **kwargs):
                 )
             )
     
+    # Validate EXTRA_PERMISSIONS
+    if hasattr(settings, 'EXTRA_PERMISSIONS'):
+        extra = settings.EXTRA_PERMISSIONS
+        if not isinstance(extra, (list, tuple)):
+            errors.append(
+                Error(
+                    'EXTRA_PERMISSIONS must be a list or tuple',
+                    hint='Set EXTRA_PERMISSIONS = ["dotted.path.ToPermission", ...]',
+                    id='permissions.E019',
+                )
+            )
+        else:
+            from django.utils.module_loading import import_string
+
+            for path in extra:
+                if not isinstance(path, str):
+                    errors.append(
+                        Error(
+                            f'Each entry in EXTRA_PERMISSIONS must be a string, got {type(path).__name__}',
+                            hint='Use dotted paths like "myapp.permissions.MyPermission"',
+                            id='permissions.E020',
+                        )
+                    )
+                    continue
+                try:
+                    cls = import_string(path)
+                except ImportError:
+                    errors.append(
+                        Error(
+                            f'Cannot import "{path}" from EXTRA_PERMISSIONS',
+                            hint='Check that the module and class exist',
+                            id='permissions.E021',
+                        )
+                    )
+                    continue
+
     return errors

{oxutils-0.4.2 → oxutils-0.4.4}/src/oxutils/permissions/perms.py

@@ -1,8 +1,10 @@
+from functools import lru_cache
 from typing import Optional
 
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
 from django.http import HttpRequest
+from django.utils.module_loading import import_string
 from ninja_extra.controllers import ControllerBase
 from ninja_extra.permissions import BasePermission
 
@@ -199,3 +201,59 @@ def access_manager(actions: str):
             )
 
     return ScopePermission(perm, context)
+
+
+@lru_cache(maxsize=1)
+def extra_permissions():
+    """
+    Return the list of permission instances defined in
+    ``EXTRA_PERMISSIONS`` (settings.py).
+
+    Each entry is a dotted path to an **already instantiated** permission
+    object (e.g. a module-level singleton).  The object is imported via
+    :func:`django.utils.module_loading.import_string` and returned as-is.
+
+    The result is cached via :func:`functools.lru_cache` so that
+    ``import_string`` is only called once per process.
+
+    Example::
+
+        # myapp/permissions.py
+        from ninja_extra.permissions import BasePermission
+
+        class IsPremium(BasePermission):
+            def has_permission(self, request, controller):
+                return request.user.is_premium
+
+        IsPremium = IsPremium()   # <-- singleton instance
+
+        # settings.py
+        EXTRA_PERMISSIONS = [
+            "myapp.permissions.IsPremium",
+        ]
+
+        # controller
+        from oxutils.permissions import extra_permissions
+
+        @api_controller(
+            "/api",
+            permissions=[*extra_permissions(), ScopePermission("articles:r")],
+        )
+        class MyController:
+            ...
+    """
+    paths = getattr(settings, "EXTRA_PERMISSIONS", [])
+    if not isinstance(paths, (list, tuple)):
+        raise ImproperlyConfigured(
+            "EXTRA_PERMISSIONS must be a list or tuple of dotted paths."
+        )
+    instances = []
+    for path in paths:
+        try:
+            instance = import_string(path)
+        except ImportError as exc:
+            raise ImproperlyConfigured(
+                f"Cannot import permission from EXTRA_PERMISSIONS: {path}"
+            ) from exc
+        instances.append(instance)
+    return instances

oxutils-0.4.4/src/oxutils/permissions/presets.py

@@ -0,0 +1,131 @@
+"""
+Permission preset auto-discovery.
+
+Walk installed apps, collect their ``PERMISSION_PRESET`` dicts,
+``ACCESS_APPLICATION_NAME`` and ``ACCESS_SCOPES``, and merge them
+into the global configuration.
+
+Called from ``PermissionsConfig.ready()`` when the app registry is ready.
+"""
+
+import importlib
+
+import structlog
+from django.apps import apps
+from django.conf import settings
+
+logger = structlog.get_logger(__name__)
+
+
+def discover_app_presets() -> list[dict]:
+    """Walk installed apps and collect their ``PERMISSION_PRESET``."""
+    presets: list[dict] = []
+    for app_config in apps.get_app_configs():
+        try:
+            mod = importlib.import_module(f"{app_config.name}.permissions")
+        except (ModuleNotFoundError, ImportError):
+            continue
+
+        preset = getattr(mod, "PERMISSION_PRESET", None)
+        if not isinstance(preset, dict):
+            continue
+
+        for role in preset.get("roles", []):
+            role.setdefault("app", app_config.label)
+        for group in preset.get("groups", []):
+            group.setdefault("app", app_config.label)
+        for grant in preset.get("role_grants", []):
+            grant.setdefault("app", app_config.label)
+
+        presets.append(preset)
+        logger.info(
+            "permission_preset_discovered",
+            app=app_config.label,
+            roles=len(preset.get("roles", [])),
+            groups=len(preset.get("groups", [])),
+            grants=len(preset.get("role_grants", [])),
+        )
+
+    return presets
+
+
+def discover_access_scopes() -> list[str]:
+    """Walk installed apps and collect their ``ACCESS_SCOPES``."""
+    scopes: list[str] = []
+    for app_config in apps.get_app_configs():
+        try:
+            mod = importlib.import_module(f"{app_config.name}.permissions")
+        except (ModuleNotFoundError, ImportError):
+            continue
+
+        app_scopes = getattr(mod, "ACCESS_SCOPES", None)
+        if isinstance(app_scopes, list):
+            for scope in app_scopes:
+                if scope not in scopes:
+                    scopes.append(scope)
+                    logger.info(
+                        "access_scope_discovered",
+                        app=app_config.label,
+                        scope=scope,
+                    )
+
+    return scopes
+
+
+def discover_access_applications() -> list[str]:
+    """Walk installed apps and collect their ``ACCESS_APPLICATION_NAME``."""
+    applications: list[str] = []
+    for app_config in apps.get_app_configs():
+        try:
+            mod = importlib.import_module(f"{app_config.name}.permissions")
+        except (ModuleNotFoundError, ImportError):
+            continue
+
+        app_name = getattr(mod, "ACCESS_APPLICATION_NAME", None)
+        if isinstance(app_name, str) and app_name not in applications:
+            applications.append(app_name)
+            logger.info(
+                "access_application_discovered",
+                app=app_config.label,
+                application=app_name,
+            )
+
+    return applications
+
+
+def register_preset(base_preset: dict) -> dict:
+    """Extend *base_preset* with presets discovered from installed apps."""
+    base_roles = base_preset.setdefault("roles", [])
+    base_groups = base_preset.setdefault("groups", [])
+    base_grants = base_preset.setdefault("role_grants", [])
+
+    for preset in discover_app_presets():
+        base_roles.extend(preset.get("roles", []))
+        base_groups.extend(preset.get("groups", []))
+        base_grants.extend(preset.get("role_grants", []))
+
+    return base_preset
+
+
+def register_access_scopes() -> None:
+    """Extend ``settings.ACCESS_SCOPES`` with scopes discovered from installed apps."""
+    existing = list(getattr(settings, "ACCESS_SCOPES", []))
+
+    for scope in discover_access_scopes():
+        if scope not in existing:
+            existing.append(scope)
+
+    settings.ACCESS_SCOPES = existing
+    logger.info("access_scopes_registered", count=len(existing))
+
+
+def register_access_applications() -> None:
+    """Extend ``settings.ACCESS_APPLICATIONS`` with apps discovered from installed apps."""
+    existing = list(getattr(settings, "ACCESS_APPLICATIONS", []))
+
+    for app_name in discover_access_applications():
+        if app_name not in existing:
+            existing.append(app_name)
+
+    settings.ACCESS_APPLICATIONS = existing
+    logger.info("access_applications_registered", count=len(existing))

oxutils-0.4.2/src/oxutils/__init__.py

@@ -1,28 +0,0 @@
-"""OxUtils - Production-ready utilities for Django applications.
-
-This package provides:
-- JWT authentication with JWKS support
-- Multi-tenant architecture (django-tenants integration, middleware, signals)
-- Auth system: invitations, MFA, password reset, registration, sessions
-- Structured logging with correlation IDs
-- Audit system with S3 export
-- Celery integration
-- Django model mixins (ChangeTracker, CookieToken, SafeDelete)
-- Permission management & authorization
-- PDF generation
-- Pagination utilities
-- Currency utilities
-- Custom exceptions, enums, and type definitions
-"""
-
-__version__ = "0.4.2"
-
-from oxutils.conf import AUDIT_MIDDLEWARE, UTILS_APPS
-from oxutils.settings import oxi_settings
-
-__all__ = [
-    "oxi_settings",
-    "UTILS_APPS",
-    "AUDIT_MIDDLEWARE",
-    "__version__",
-]

oxutils-0.4.2/src/oxutils/permissions/apps.py

@@ -1,10 +0,0 @@
-from django.apps import AppConfig
-
-
-class PermissionsConfig(AppConfig):
-    default_auto_field = 'django.db.models.BigAutoField'
-    name = 'oxutils.permissions'
-    
-    def ready(self):
-        """Import checks when app is ready."""
-        from . import checks  # noqa