Configuration

Chanx Settings

Chanx can be configured through the CHANX dictionary in your Django settings. Below is a complete list of available settings with their default values:

# settings.py
CHANX = {
    # Message configuration
    'MESSAGE_ACTION_KEY': 'action',  # Key name for action field in messages
    'CAMELIZE': False,  # Whether to camelize/decamelize messages for JavaScript clients

    # Completion messages
    'SEND_COMPLETION': False,  # Whether to send completion message after processing

    # Messaging behavior
    'SEND_MESSAGE_IMMEDIATELY': True,  # Whether to yield control after sending messages (send message immediately)
    'SEND_AUTHENTICATION_MESSAGE': True,  # Whether to send auth status after connection

    # Logging configuration
    'LOG_RECEIVED_MESSAGE': True,  # Whether to log received messages
    'LOG_SENT_MESSAGE': True,  # Whether to log sent messages
    'LOG_IGNORED_ACTIONS': [],  # Message actions to ignore in logs

    # Playground configuration
    'WEBSOCKET_BASE_URL': 'ws://localhost:8000'  # Default WebSocket URL for playground
}

Settings Reference

Message Configuration

MESSAGE_ACTION_KEY (default: "action"): Key name for the action field in messages, used for discriminated unions.
CAMELIZE (default: False): Whether to convert between camelCase (for JavaScript clients) and snake_case (for Python).

Completion Messages

SEND_COMPLETION (default: False): Whether to send a completion message after processing a client message.

Messaging Behavior

SEND_MESSAGE_IMMEDIATELY (default: True): Whether to yield control after sending messages (send message immediately).
SEND_AUTHENTICATION_MESSAGE (default: True): Whether to send authentication status after connection.

Logging Configuration

LOG_RECEIVED_MESSAGE (default: True): Whether to log received messages.
LOG_SENT_MESSAGE (default: True): Whether to log sent messages.
LOG_IGNORED_ACTIONS (default: []): Message actions that should not be logged.

Playground Configuration

WEBSOCKET_BASE_URL (default: "ws://localhost:8000"): Default WebSocket URL for playground.

Environment-Specific Settings

Development

For development, you might want to use these settings:

# settings/dev.py
CHANX = {
    'SEND_COMPLETION': False,
    'LOG_RECEIVED_MESSAGE': True,
    'LOG_SENT_MESSAGE': True,
    'WEBSOCKET_BASE_URL': 'ws://localhost:8000',
}

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {
            "hosts": [os.environ.get('REDIS_URL', 'redis://localhost:6379/0')],
        },
    },
}

Testing

For testing, it's recommended to use these settings:

# settings/test.py
CHANX = {
    'SEND_COMPLETION': True,  # Important for receive_all_json() to work
    'SEND_AUTHENTICATION_MESSAGE': True,
    'LOG_RECEIVED_MESSAGE': False,  # Reduce noise in tests
    'LOG_SENT_MESSAGE': False,  # Reduce noise in tests
}

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels.layers.InMemoryChannelLayer"
    }
}

Production

For production, consider these settings:

# settings/prod.py
CHANX = {
    'SEND_COMPLETION': False,
    'SEND_MESSAGE_IMMEDIATELY': True,
    'LOG_RECEIVED_MESSAGE': True,
    'LOG_SENT_MESSAGE': True,
    'LOG_IGNORED_ACTIONS': ['ping', 'pong'],  # Reduce noise from heartbeats
    'WEBSOCKET_BASE_URL': 'wss://your-domain.com',
}

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {
            "hosts": [os.environ.get('REDIS_URL', 'redis://localhost:6379/0')],
        },
    },
}

Optional Dependencies

Some Chanx features require additional packages. You can install these along with Chanx using extras:

# Install with camelCase conversion support
pip install chanx[camel-case]

This installs the pyhumps package which is required when using the CAMELIZE setting. Without this package enabling the setting will raise a runtime error.

Overriding Settings in Tests

Chanx provides utilities for temporarily overriding settings in tests:

from chanx.utils.settings import override_chanx_settings

# Using decorator for a test function
@override_chanx_settings(SEND_COMPLETION=True)
async def test_completion_message():
    # SEND_COMPLETION will be True within this test
    ...

Next Steps

Now that you understand Chanx's configuration options, proceed to the Quick Start guide to set up your project and create your first WebSocket consumer.