Extension Configuration Reference

Quick reference guide for configuring extensions in your Django-CFG project. This page documents the settings you can customize in your extension __cfg__.py files.

User Reference This is a practical guide for configuring extensions, not for building them.

Extension Base Classes

Django-CFG provides two base settings classes for different extension types.

BaseExtensionSettings (App Extensions)

For Django app extensions in extensions/apps/. These are full Django apps with models, views, and URL routing. To disable an app extension, comment out or remove the settings = ... line in __cfg__.py.

Fields:

Field	Type	Default	Description
`admin_enabled`	`bool`	`True`	Show in admin interface
`middleware_classes`	`list[str]`	`[]`	Middleware classes to add to MIDDLEWARE
`navigation`	`Optional[NavigationSection]`	`None`	Admin navigation section
`constance_fields`	`list[ConstanceField]`	`[]`	Dynamic settings via django-constance
`schedules`	`list[RQScheduleConfig]`	`[]`	RQ scheduled tasks
`url_prefix`	`Optional[str]`	`None`	URL path segment override
`url_namespace`	`Optional[str]`	`None`	Django URL namespace

BaseModuleSettings (Module Extensions)

For utility module extensions in extensions/modules/. These are non-app Python modules without models or URL routing.

Fields:

Field	Type	Default	Description
`enabled`	`bool`	`True`	Enable or disable the module


from django_cfg.extensions.configs.modules import BaseModuleSettings
 
class MyUtilitySettings(BaseModuleSettings):
    enabled: bool = True  # Module active

The enabled field only exists on BaseModuleSettings. App extensions (BaseExtensionSettings) do not have this field — disable them by removing the settings object.

admin_enabled

Type: bool Default: True

Show app extension in Django admin interface. Only available on BaseExtensionSettings.


class SupportSettings(BaseExtensionSettings):
    admin_enabled: bool = True  # Shows in admin sidebar

Usage:


# Hide from admin (but keep extension enabled)
admin_enabled: bool = False

Common Extension Configurations

Payments Extension

File: extensions/apps/payments/__cfg__.py


from django_cfg.extensions.configs.apps import BaseExtensionSettings
 
class PaymentsSettings(BaseExtensionSettings):
    # Crypto Payment API Configuration
    crypto_api_key: str = env.payments_api_keys.crypto_api_key
    crypto_webhook_secret: str = env.payments_api_keys.crypto_webhook_secret
 
    # Admin integration
    admin_enabled: bool = True
 
settings = PaymentsSettings()

Environment Variables:


PAYMENTS_API_KEYS__CRYPTO_API_KEY=your-api-key
PAYMENTS_API_KEYS__CRYPTO_WEBHOOK_SECRET=your-secret

Leads Extension

File: extensions/apps/leads/__cfg__.py


from django_cfg.extensions.configs.apps import BaseExtensionSettings
 
class LeadsSettings(BaseExtensionSettings):
    # Notification settings
    telegram_enabled: bool = True
    email_enabled: bool = True
 
    # Telegram configuration
    telegram_bot_token: str = env.telegram.bot_token
 
    # Email configuration
    notification_email: str = env.leads.notification_email
 
settings = LeadsSettings()

Available Settings:

Setting	Type	Default	Description
`telegram_enabled`	`bool`	`True`	Send Telegram notifications
`email_enabled`	`bool`	`True`	Send email notifications
`telegram_bot_token`	`str`	Required	Telegram bot token
`notification_email`	`str`	Required	Email for lead notifications

Environment Variables:


TELEGRAM__BOT_TOKEN=your-telegram-bot-token
LEADS__NOTIFICATION_EMAIL=[email protected]

Support Extension

File: extensions/apps/support/__cfg__.py


from django_cfg.extensions.configs.apps import BaseExtensionSettings
 
class SupportSettings(BaseExtensionSettings):
    # Ticket management
    ticket_auto_assign: bool = True
    sla_tracking_enabled: bool = True
    sla_hours: int = 24
 
    # Features
    live_chat_enabled: bool = False
    knowledge_base_integration: bool = True
 
settings = SupportSettings()

Available Settings:

Setting	Type	Default	Description
`ticket_auto_assign`	`bool`	`True`	Auto-assign tickets to team members
`sla_tracking_enabled`	`bool`	`True`	Track SLA compliance
`sla_hours`	`int`	`24`	SLA response time in hours
`live_chat_enabled`	`bool`	`False`	Enable live chat widget
`knowledge_base_integration`	`bool`	`True`	Integrate with knowledge base

File: extensions/apps/newsletter/__cfg__.py


from django_cfg.extensions.configs.apps import BaseExtensionSettings
 
class NewsletterSettings(BaseExtensionSettings):
    # Default settings
    from_email: str = "[email protected]"
    from_name: str = "Your Company Newsletter"
 
    # Features
    double_opt_in: bool = True
    unsubscribe_link_required: bool = True
 
settings = NewsletterSettings()

Available Settings:

Setting	Type	Default	Description
`from_email`	`str`	Required	Sender email address
`from_name`	`str`	Required	Sender display name
`double_opt_in`	`bool`	`True`	Require email confirmation
`unsubscribe_link_required`	`bool`	`True`	Include unsubscribe link

Environment Variables

Naming Convention

Extension settings load from environment variables using nested structure with double underscores:

Pattern: {SECTION}__{SUBSECTION}__{VARIABLE}

Examples:


# Payments
PAYMENTS_API_KEYS__CRYPTO_API_KEY=key
 
# Leads
LEADS__NOTIFICATION_EMAIL=[email protected]
 
# Support
SUPPORT__SLA_HOURS=24
 
# Newsletter
NEWSLETTER__FROM_EMAIL=[email protected]

Loading from .env

Create a .env file in your project root:


# .env
 
# Payments Extension
PAYMENTS_API_KEYS__CRYPTO_API_KEY=your-crypto-api-key
PAYMENTS_API_KEYS__CRYPTO_WEBHOOK_SECRET=your-secret
 
# Leads Extension
TELEGRAM__BOT_TOKEN=your-telegram-bot-token
LEADS__NOTIFICATION_EMAIL=[email protected]
 
# Support Extension
SUPPORT__SLA_HOURS=48
 
# Newsletter Extension
NEWSLETTER__FROM_EMAIL=[email protected]
NEWSLETTER__FROM_NAME=Your Company Newsletter

Accessing in Code


# extensions/apps/payments/__cfg__.py
from core.environment import env
 
class PaymentsSettings(BaseExtensionSettings):
    # Auto-loads from ENV > .env > defaults
    crypto_api_key: str = env.payments_api_keys.crypto_api_key

Feature Flags

Extensions support feature flags for toggling functionality:

Example: Toggle Features


# extensions/apps/support/__cfg__.py
class SupportSettings(BaseExtensionSettings):
    # Core features
    ticket_system_enabled: bool = True        # ✅ Enabled
    live_chat_enabled: bool = False           # ❌ Disabled
    sla_tracking_enabled: bool = True         # ✅ Enabled
 
    # Integrations
    telegram_notifications: bool = True        # ✅ Enabled
    slack_notifications: bool = False          # ❌ Disabled

Environment-Based Flags

Toggle features per environment:


import os
 
class SupportSettings(BaseExtensionSettings):
    # Enable live chat only in production
    live_chat_enabled: bool = (
        os.getenv('ENVIRONMENT') == 'production'
    )
 
    # Enable SLA tracking only in production
    sla_tracking_enabled: bool = (
        os.getenv('ENVIRONMENT') != 'development'
    )

Extension URL Configuration

Extensions auto-register URLs, but you can verify the patterns:

Default URL Patterns

Extensions auto-register URLs based on urls*.py files found in the extension directory:

URL File	Mounted At	Description
`urls.py`	`/cfg/{name}/`	Main API endpoints
`urls_admin.py`	`/cfg/{name}/admin/`	Admin API endpoints
`urls_system.py`	`/cfg/{name}/system/`	System API endpoints
`urls_<custom>.py`	`/cfg/{name}/<custom>/`	Custom endpoint groups

Examples by extension:

Extension	URL Pattern	Example
Payments	`/cfg/payments/`	`http://localhost:8000/cfg/payments/api/`
Leads	`/cfg/leads/`	`http://localhost:8000/cfg/leads/api/`
Support	`/cfg/support/`	`http://localhost:8000/cfg/support/api/`
Newsletter	`/cfg/newsletter/`	`http://localhost:8000/cfg/newsletter/api/`

You can override the path segment with url_prefix or the namespace with url_namespace in your extension settings.

Testing URLs


# Payments API
curl http://localhost:8000/cfg/payments/api/
 
# Leads API
curl http://localhost:8000/cfg/leads/api/
 
# Support API
curl http://localhost:8000/cfg/support/api/tickets/

Extensions can add custom admin navigation:

How It Works

Extensions with admin_enabled: bool = True automatically appear in admin sidebar.

The extension’s navigation is defined in its base settings (you don’t need to configure this):


# This is defined in BaseExtensionSettings (you inherit it)
navigation = NavigationSection(
    title="Payments",
    icon=Icons.PAYMENT,
    items=[
        NavigationItem(
            title="Transactions",
            app="payments",
            model="transaction",
        ),
    ],
)

Hiding from Admin

To hide an extension from admin navigation:


class PaymentsSettings(BaseExtensionSettings):
    admin_enabled: bool = False  # Won't show in sidebar

Common Patterns

Pattern 1: API Keys from Environment


class PaymentsSettings(BaseExtensionSettings):
    # Load from .env
    crypto_api_key: str = env.payments_api_keys.crypto_api_key
 
    # With fallback
    backup_api_key: str = env.payments.backup_key or "default-key"

Pattern 2: Environment-Specific Config


import os
 
class PaymentsSettings(BaseExtensionSettings):
    # Production vs Development
    crypto_api_key: str = (
        env.payments.prod_key
        if os.getenv('ENVIRONMENT') == 'production'
        else env.payments.sandbox_key
    )
 
    # Debug mode
    debug_payments: bool = (os.getenv('DEBUG', 'False') == 'True')

Pattern 3: Feature Toggles


class SupportSettings(BaseExtensionSettings):
    # Enable/disable features
    live_chat: bool = False          # Coming soon
    ticket_system: bool = True       # Production ready
    knowledge_base: bool = True      # Production ready
    ai_assistant: bool = False       # Beta testing

Pattern 4: Validation


from pydantic import field_validator
 
class PaymentsSettings(BaseExtensionSettings):
    sla_hours: int = 24
 
    @field_validator('sla_hours')
    def validate_sla(cls, v):
        if v < 1 or v > 168:  # 1 hour to 1 week
            raise ValueError('SLA must be between 1 and 168 hours')
        return v

Troubleshooting Settings

Setting Not Applied

Problem: Changed setting but no effect

Solution:


# 1. Restart Django (settings load at startup)
python manage.py runserver
 
# 2. Verify in shell
python manage.py shell
>>> from extensions.apps.payments.__cfg__ import settings
>>> settings.crypto_api_key
'your-expected-key'

Environment Variable Not Loading

Problem: env.something not found

Solution:


# 1. Check .env exists
ls -la .env
 
# 2. Check variable name (use double underscores)
cat .env | grep PAYMENTS
 
# 3. Restart Django after .env changes

Type Error

Problem: TypeError: expected str, got None

Solution:


# Provide defaults or make optional
class PaymentsSettings(BaseExtensionSettings):
    # With default
    api_timeout: int = 30
 
    # Optional (can be None)
    backup_key: Optional[str] = None

Quick Reference

Common Extension Settings

Extension	Key Settings	Environment Variables
Payments	`crypto_api_key`	`PAYMENTS_API_KEYS__CRYPTO_API_KEY`
Leads	`telegram_enabled`, `email_enabled`	`TELEGRAM__BOT_TOKEN`, `LEADS__NOTIFICATION_EMAIL`
Support	`sla_hours`, `ticket_auto_assign`	`SUPPORT__SLA_HOURS`
Newsletter	`from_email`, `from_name`	`NEWSLETTER__FROM_EMAIL`

All App Extensions Support

✅ admin_enabled: bool - Show in admin
✅ middleware_classes, navigation, constance_fields, schedules - Advanced integration
✅ url_prefix, url_namespace - URL customization
✅ Environment variable loading
✅ Type validation with Pydantic
✅ Auto-discovery and registration (via __cfg__.py or legacy __manifest__.py)

Module Extensions Support

✅ enabled: bool - Enable/disable module
✅ Environment variable loading
✅ Type validation with Pydantic

Next Steps

Backend Extensions Migration Guide Troubleshooting

Pro Tip: Documentation in Code Each extension’s base settings class has detailed docstrings. Check the source code for complete field documentation:


from django_cfg.extensions.configs.apps import BaseExtensionSettings
help(BaseExtensionSettings)

Extension Configuration Reference

Extension Base Classes

BaseExtensionSettings (App Extensions)

BaseModuleSettings (Module Extensions)

admin_enabled

Common Extension Configurations

Payments Extension

Leads Extension

Support Extension

Newsletter Extension

Environment Variables

Naming Convention

Loading from .env

Accessing in Code

Feature Flags

Example: Toggle Features

Environment-Based Flags

Extension URL Configuration

Default URL Patterns

Testing URLs

Admin Navigation

How It Works

Navigation Structure

Hiding from Admin

Common Patterns

Pattern 1: API Keys from Environment

Pattern 2: Environment-Specific Config

Pattern 3: Feature Toggles

Pattern 4: Validation

Troubleshooting Settings

Setting Not Applied

Environment Variable Not Loading

Type Error

Quick Reference

Common Extension Settings

All App Extensions Support

Module Extensions Support

Next Steps

Documentation

Frontend

Resources

Company