Settings Reference

Chanx can be configured through Django’s settings module. All Chanx settings are contained within a single CHANX dictionary in your project’s settings file.

Configuration Options

Here’s an overview of all available settings and their default values:

# settings.py
CHANX = {
    'MESSAGE_ACTION_KEY': 'action',
    'SEND_COMPLETION': False,
    'SEND_MESSAGE_IMMEDIATELY': True,
    'SEND_AUTHENTICATION_MESSAGE': True,
    'LOG_RECEIVED_MESSAGE': True,
    'LOG_SENT_MESSAGE': True,
    'LOG_IGNORED_ACTIONS': ['ping', 'pong'],
    'WEBSOCKET_BASE_URL': 'ws://localhost:8000',
}

Settings Details

Setting	Default	Description
`MESSAGE_ACTION_KEY`	`"action"`	Key name for the action field in messages, used as the discriminator for message types
`SEND_COMPLETION`	`False`	Whether to send completion messages after processing a client message, should set it to True for testing and False for the other environments.
`SEND_MESSAGE_IMMEDIATELY`	`True`	Whether to send message immediately rather than wait to the end of the processing to send together.
`SEND_AUTHENTICATION_MESSAGE`	`True`	Whether to send authentication status message after connection authentication
`LOG_RECEIVED_MESSAGE`	`True`	Whether to log received WebSocket messages
`LOG_SENT_MESSAGE`	`True`	Whether to log sent WebSocket messages
`LOG_IGNORED_ACTIONS`	`[]`	List of message actions that should not be logged (e.g., frequent messages like heartbeats)
`WEBSOCKET_BASE_URL`	`"ws://localhost:8000"`	Default WebSocket URL for discovery and playground usage

Using Settings in Code

Chanx’s settings are accessible through the chanx_settings object:

from chanx.settings import chanx_settings

# Access a setting
action_key = chanx_settings.MESSAGE_ACTION_KEY

# Check if completion messages are enabled
if chanx_settings.SEND_COMPLETION:
    # Do something

Overriding Settings in Tests

Chanx provides utilities for temporarily overriding settings in tests:

from chanx.utils.settings import override_chanx_settings, settings_context

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

# Using context manager
async def test_with_custom_settings():
    with settings_context(SEND_AUTHENTICATION_MESSAGE=False):
        # SEND_AUTHENTICATION_MESSAGE will be False within this block
        ...

Default Settings Source

The default settings are defined in chanx.settings.MySetting as a dataclass:

@dataclass
class MySetting:
    """
    Configuration settings for Chanx websocket framework.

    This dataclass defines all available configuration options with their default values.
    These settings can be overridden through Django's settings with the CHANX dictionary.

    Attributes:
        MESSAGE_ACTION_KEY: Key name for action field in messages (default: "action")
        SEND_COMPLETION: Whether to send completion messages after processing (default: False)
        SEND_MESSAGE_IMMEDIATELY: Whether to yield control after sending messages (default: True)
        SEND_AUTHENTICATION_MESSAGE: Whether to send auth status after connection (default: True)
        LOG_RECEIVED_MESSAGE: Whether to log received messages (default: True)
        LOG_SENT_MESSAGE: Whether to log sent messages (default: True)
        LOG_IGNORED_ACTIONS: Message actions that should not be logged (default: empty list)
        WEBSOCKET_BASE_URL: Default WebSocket URL for discovery (default: "ws://localhost:8000")
        user_settings: Internal field used by APISettings
    """

    MESSAGE_ACTION_KEY: str = "action"
    SEND_COMPLETION: bool = False
    SEND_MESSAGE_IMMEDIATELY: bool = True
    SEND_AUTHENTICATION_MESSAGE: bool = True

    LOG_RECEIVED_MESSAGE: bool = True
    LOG_SENT_MESSAGE: bool = True
    LOG_IGNORED_ACTIONS: Iterable[str] = dataclasses.field(default_factory=list)

    WEBSOCKET_BASE_URL: str = "ws://localhost:8000"

    # Add this field to satisfy the type checker
    # It will be used by APISettings but isn't part of the real dataclass structure
    user_settings: dict[str, Any] = dataclasses.field(default_factory=dict)