Skip to Content
CoreRegistry

Registry System - Lazy Import Management

The Registry System is Django-CFG’s centralized import management system. It provides organized lazy loading of all components, minimizing startup time and memory usage.

Overview

The Registry System provides:

  • 📦 Lazy Loading - Import components only when first accessed
  • 🏗️ Organized Structure - Components grouped by functionality
  • ⚡ Zero Startup Cost - No imports until actually needed
  • 🛡️ Type Safety - Full type hints and IDE autocomplete support

How It Works

Django-CFG uses Python’s __getattr__ mechanism for lazy imports:

# django_cfg/__init__.py
from .registry import DJANGO_CFG_REGISTRY
 
def __getattr__(name: str):
    """Lazy import mechanism using registry pattern."""
    if name in DJANGO_CFG_REGISTRY:
        module_path, class_name = DJANGO_CFG_REGISTRY[name]
        import importlib
        module = importlib.import_module(module_path)
        return getattr(module, class_name)
    raise AttributeError(f"module 'django_cfg' has no attribute '{name}'")

This means:

  • No import until use: from django_cfg import DjangoConfig doesn’t load the module
  • First access loads: Only when you instantiate DjangoConfig() is it imported
  • Subsequent accesses cached: Python caches the import after first load

Registry Structure

Django-CFG uses multiple specialized registries combined into one:

DJANGO_CFG_REGISTRY = {
    **CORE_REGISTRY,        # Core components (config, exceptions, etc.)
    **SERVICES_REGISTRY,    # Service integrations (email, telegram, ngrok)
    **THIRD_PARTY_REGISTRY, # Third-party integrations (unfold, DRF, etc.)
    **MODULES_REGISTRY,     # Utility modules and functions
    **EXCEPTIONS_REGISTRY,  # Exception classes
}

Registry Categories

1. Core Registry (CORE_REGISTRY)

Essential Django-CFG components:

CORE_REGISTRY = {
    # Core configuration
    "DjangoConfig": ("django_cfg.core.config", "DjangoConfig"),
    "StartupInfoMode": ("django_cfg.core.config", "StartupInfoMode"),
 
    # Core exceptions
    "ConfigurationError": ("django_cfg.core.exceptions", "ConfigurationError"),
    "ValidationError": ("django_cfg.core.exceptions", "ValidationError"),
    "DatabaseError": ("django_cfg.core.exceptions", "DatabaseError"),
    "CacheError": ("django_cfg.core.exceptions", "CacheError"),
    "EnvironmentError": ("django_cfg.core.exceptions", "EnvironmentError"),
 
    # Infrastructure models
    "DatabaseConfig": ("django_cfg.models.infrastructure.database", "DatabaseConfig"),
    "CacheConfig": ("django_cfg.models.infrastructure.cache", "CacheConfig"),
    "SecurityConfig": ("django_cfg.models.infrastructure.security", "SecurityConfig"),
    "LoggingConfig": ("django_cfg.models.infrastructure.logging", "LoggingConfig"),
 
    # Security
    "AxesConfig": ("django_cfg.models.django.axes", "AxesConfig"),
    "CryptoFieldsConfig": ("django_cfg.models.django.crypto_fields", "CryptoFieldsConfig"),
 
    # API
    "LimitsConfig": ("django_cfg.models.api.limits", "LimitsConfig"),
    "ApiKeys": ("django_cfg.models.api.keys", "ApiKeys"),
    "JWTConfig": ("django_cfg.models.api.jwt", "JWTConfig"),
    "GitHubOAuthConfig": ("django_cfg.models.api.oauth", "GitHubOAuthConfig"),
    "TwoFactorConfig": ("django_cfg.models.api.twofactor", "TwoFactorConfig"),
 
    # Background tasks
    "DjangoRQConfig": ("django_cfg.models.django.django_rq", "DjangoRQConfig"),
    "RQQueueConfig": ("django_cfg.models.django.django_rq", "RQQueueConfig"),
 
    # Pagination
    "DefaultPagination": ("django_cfg.middleware.pagination", "DefaultPagination"),
    "LargePagination": ("django_cfg.middleware.pagination", "LargePagination"),
    "SmallPagination": ("django_cfg.middleware.pagination", "SmallPagination"),
    "NoPagination": ("django_cfg.middleware.pagination", "NoPagination"),
 
    # Routing & Testing
    "DynamicRouter": ("django_cfg.routing.routers", "DynamicRouter"),
    "SmartTestRunner": ("django_cfg.testing.runners", "SmartTestRunner"),
    "FastTestRunner": ("django_cfg.testing.runners", "FastTestRunner"),
 
    # Utils
    "HealthService": ("django_cfg.modules.django_health", "HealthService"),
    "get_ticket_url": ("django_cfg.core.utils.url_helpers", "get_ticket_url"),
    "get_otp_url": ("django_cfg.core.utils.url_helpers", "get_otp_url"),
}

2. Services Registry (SERVICES_REGISTRY)

Service integrations and modules:

SERVICES_REGISTRY = {
    # Email services
    "EmailConfig": ("django_cfg.models.services", "EmailConfig"),
    "DjangoEmailService": ("django_cfg.modules.django_email", "DjangoEmailService"),
    "send_email": ("django_cfg.modules.django_email", "send_email"),
    "send_admin_email": ("django_cfg.modules.django_email", "send_admin_email"),
    "send_admin_notification": ("django_cfg.modules.django_email", "send_admin_notification"),
 
    # Telegram services
    "TelegramConfig": ("django_cfg.models.services", "TelegramConfig"),
    "DjangoTelegram": ("django_cfg.modules.django_telegram", "DjangoTelegram"),
    "send_telegram_message": ("django_cfg.modules.django_telegram", "send_telegram_message"),
    "send_telegram_photo": ("django_cfg.modules.django_telegram", "send_telegram_photo"),
 
    # Ngrok services
    "NgrokConfig": ("django_cfg.models.ngrok", "NgrokConfig"),
    "NgrokManager": ("django_cfg.modules.django_ngrok", "NgrokManager"),
    "start_tunnel": ("django_cfg.modules.django_ngrok", "start_tunnel"),
    "stop_tunnel": ("django_cfg.modules.django_ngrok", "stop_tunnel"),
    "get_tunnel_url": ("django_cfg.modules.django_ngrok", "get_tunnel_url"),
 
    # Logging services
    "DjangoLogger": ("django_cfg.modules.django_logging", "DjangoLogger"),
    "get_logger": ("django_cfg.modules.django_logging", "get_logger"),
 
    # Database Backup
}

3. Third-Party Registry (THIRD_PARTY_REGISTRY)

External integrations:

THIRD_PARTY_REGISTRY = {
    # OpenAPI Client Generation
    "OpenAPIClientConfig": ("django_cfg.models.django.openapi", "OpenAPIClientConfig"),
    "OpenAPIGroupConfig": ("django_cfg.modules.django_client.core.config", "OpenAPIGroupConfig"),
 
    # Unfold Admin
    "UnfoldConfig": ("django_cfg.modules.django_unfold.models.config", "UnfoldConfig"),
    "UnfoldTheme": ("django_cfg.modules.django_unfold.models.config", "UnfoldTheme"),
    "UnfoldThemeConfig": ("django_cfg.modules.django_unfold.models.config", "UnfoldThemeConfig"),
    "UnfoldColors": ("django_cfg.modules.django_unfold.models.config", "UnfoldColors"),
    "NavigationItem": ("django_cfg.modules.django_unfold.models.navigation", "NavigationItem"),
    "NavigationSection": ("django_cfg.modules.django_unfold.models.navigation", "NavigationSection"),
    "SiteDropdownItem": ("django_cfg.modules.django_unfold.models.dropdown", "SiteDropdownItem"),
 
    # Django REST Framework
    "DRFConfig": ("django_cfg.models.api.drf", "DRFConfig"),
    "SpectacularConfig": ("django_cfg.models.api.drf", "SpectacularConfig"),
    "SwaggerUISettings": ("django_cfg.models.api.drf", "SwaggerUISettings"),
    "RedocUISettings": ("django_cfg.models.api.drf", "RedocUISettings"),
 
    # Constance
    "ConstanceConfig": ("django_cfg.models.django.constance", "ConstanceConfig"),
    "ConstanceField": ("django_cfg.models.django.constance", "ConstanceField"),
 
    # Material Icons
    "Icons": ("django_cfg.modules.django_admin.icons", "Icons"),
    "IconCategories": ("django_cfg.modules.django_admin.icons", "IconCategories"),
}

4. Modules Registry (MODULES_REGISTRY)

Utility modules and integrations:

MODULES_REGISTRY = {
    # URL integration
    "add_django_cfg_urls": ("django_cfg.core.integration", "add_django_cfg_urls"),
    "get_django_cfg_urls_info": ("django_cfg.core.integration", "get_django_cfg_urls_info"),
    "set_current_config": ("django_cfg.core.config", "set_current_config"),
 
    # Centrifugo WebSocket
    "DjangoCfgCentrifugoConfig": ("django_cfg.apps.integrations.centrifugo.services.client.config", "DjangoCfgCentrifugoConfig"),
 
    # gRPC
    "GRPCConfig": ("django_cfg.models.api.grpc", "GRPCConfig"),
    "GRPCServerConfig": ("django_cfg.models.api.grpc", "GRPCServerConfig"),
 
    # Streamlit Admin
    "StreamlitAdminConfig": ("django_cfg.modules.streamlit_admin", "StreamlitAdminConfig"),
 
    # Import/Export
    "ImportForm": ("django_cfg.modules.django_import_export", "ImportForm"),
    "ExportForm": ("django_cfg.modules.django_import_export", "ExportForm"),
    "ImportExportMixin": ("django_cfg.modules.django_import_export", "ImportExportMixin"),
    "ImportExportModelAdmin": ("django_cfg.modules.django_import_export", "ImportExportModelAdmin"),
 
    # Django Admin configuration
    "AdminConfig": ("django_cfg.modules.django_admin", "AdminConfig"),
    "FieldConfig": ("django_cfg.modules.django_admin", "FieldConfig"),
    "FieldsetConfig": ("django_cfg.modules.django_admin", "FieldsetConfig"),
}

5. Exceptions Registry (EXCEPTIONS_REGISTRY)

Exception classes:

EXCEPTIONS_REGISTRY = {
    "DjangoCfgException": ("django_cfg.core.exceptions", "DjangoCfgException"),
    "ConfigurationError": ("django_cfg.core.exceptions", "ConfigurationError"),
    "ValidationError": ("django_cfg.core.exceptions", "ValidationError"),
    "EnvironmentError": ("django_cfg.core.exceptions", "EnvironmentError"),
}

Usage

Importing Components

All registered components can be imported directly from django_cfg:

# Import configuration classes
from django_cfg import DjangoConfig, DatabaseConfig, CacheConfig
 
# Import service modules
from django_cfg import DjangoEmailService, send_email, send_telegram_message
 
# Import exceptions
from django_cfg import ConfigurationError, ValidationError
 
# Import utilities
from django_cfg import DynamicRouter, HealthService, get_logger

Lazy Loading Benefit

The lazy loading system means your app only imports what it uses:

# This import is instant - no modules loaded yet
from django_cfg import DjangoConfig, EmailConfig, TelegramConfig
 
# Only when you USE a component does it get loaded
config = DjangoConfig(...)  # Now DjangoConfig module is loaded
 
# EmailConfig and TelegramConfig are still not loaded
# until you actually use them

Checking Available Components

You can see all available components in __all__:

import django_cfg
print(django_cfg.__all__)
# ['DjangoConfig', 'DatabaseConfig', 'EmailConfig', 'send_email', ...]

Best Practices

1. Import What You Need

Only import the components you actually use:

# Good: Import only what you need
from django_cfg import DjangoConfig, DatabaseConfig
 
# Avoid: Don't import everything
from django_cfg import *  # Loads all components

2. Use Type Hints

All registry components have full type hints:

from django_cfg import DjangoConfig, DatabaseConfig, EmailConfig
from typing import Optional
 
class MyConfig(DjangoConfig):
    project_name: str = "My Project"
    email: Optional[EmailConfig] = None

3. Handle Import Errors

Components may have optional dependencies:

try:
    from django_cfg import GRPCConfig
except ImportError:
    GRPCConfig = None  # grpcio not installed

Extending the Registry

To add custom components to your project, you can create your own registry pattern:

# myapp/registry.py
MY_APP_REGISTRY = {
    "MyService": ("myapp.services", "MyService"),
    "MyConfig": ("myapp.config", "MyConfig"),
}
 
# myapp/__init__.py
from .registry import MY_APP_REGISTRY
 
def __getattr__(name: str):
    if name in MY_APP_REGISTRY:
        module_path, class_name = MY_APP_REGISTRY[name]
        import importlib
        module = importlib.import_module(module_path)
        return getattr(module, class_name)
    raise AttributeError(f"module 'myapp' has no attribute '{name}'")
 
__all__ = list(MY_APP_REGISTRY.keys())
Last updated on
Django IntegrationRouting

Django-CFG documentation — a modern, type-safe Django framework with Pydantic v2 configuration.

Documentation

Frontend

Resources

Company

© 2026 Django-CFG. MIT Licensed.GitHub ↗