Configuration#

General Configuration (All Frameworks)#

You configure chanx by creating a base consumer class and setting class attributes. This approach works across all frameworks (Django, FastAPI, and other ASGI frameworks).

Creating a Base Consumer

# For Django Channels
from chanx.channels.websocket import AsyncJsonWebsocketConsumer

# For FastAPI / other ASGI frameworks
from chanx.fast_channels.websocket import AsyncJsonWebsocketConsumer

class BaseConsumer(AsyncJsonWebsocketConsumer):
    # Message behavior
    send_completion = False  # Whether to send completion message after processing
    send_message_immediately = True  # Whether to yield control after sending messages
    log_websocket_message = True  # Whether to log websocket messages
    log_ignored_actions = []  # Message actions to ignore in logs

    # Message formatting
    camelize = False  # Whether to convert between camelCase and snake_case
    error_format = "standard"  # "pydantic" for raw Pydantic error lists
    discriminator_field = "action"  # Field used for message type discrimination

    # Channel layer configuration (required for non-Django frameworks)
    channel_layer_alias = "default"  # Channel layer alias to use

    # Authentication (optional)
    # authenticator_class = MyAuthenticator  # Set authenticator class
    # authenticator: MyAuthenticator  # Type hint for authenticator

Using Your Base Consumer

from chanx.core.decorators import ws_handler, channel
from .base_consumer import BaseConsumer

@channel(name="chat")
class ChatConsumer(BaseConsumer):
    # Override settings for this specific consumer if needed
    send_completion = True
    log_ignored_actions = ["ping", "pong"]

    @ws_handler
    async def handle_chat(self, message: ChatMessage) -> None:
        await self.broadcast_message(...)

Authentication Configuration

from chanx.channels.authenticator import DjangoAuthenticator
from rest_framework.permissions import IsAuthenticated

class MyAuthenticator(DjangoAuthenticator):
    permission_classes = [IsAuthenticated]
    queryset = MyModel.objects.all()
    obj: MyModel  # Type hint for the authenticated object

class MyConsumer(BaseConsumer):
    authenticator_class = MyAuthenticator
    authenticator: MyAuthenticator  # Type hint for better IDE support

Configurable Attributes Reference#

Message Behavior

  • send_completion (bool): Whether to send completion message after processing (default: False)

  • send_message_immediately (bool | None): Whether to yield control after sending messages (default: True)

  • log_websocket_message (bool | None): Whether to log websocket messages (default: False)

  • log_ignored_actions (Collection[str]): Message actions to ignore in logs (default: [])

  • cancel_handlers_on_disconnect (ClassVar[bool]): Cancel the connection's in-flight handlers when it disconnects, for handlers doing long work only their caller wants (default: False)

Message Formatting

  • camelize (ClassVar[bool]): Whether to convert between camelCase and snake_case (default: False)

  • error_format (ClassVar[str]): Shape of error payloads: "standard" or "pydantic" (default: "standard"). See Errors.

  • discriminator_field (ClassVar[str]): Field used for message type discrimination (default: "action")

Channel Layer

  • channel_layer_alias (ClassVar[str]): Channel layer alias to use. Required for non-Django frameworks. For Django, you can skip this and it will use default, or specify to use the right channel layer.

Authentication

  • authenticator_class (type[BaseAuthenticator] | None): Authenticator class to instantiate (default: None)

  • authenticator (BaseAuthenticator | None): Type hint for the active authenticator instance

Django-Specific Configuration#

For Django projects, you can use the CHANX settings dictionary in addition to or instead of creating a base consumer class. Note: CHANX settings apply to Django only.

# settings.py
CHANX = {
    # Message configuration
    'MESSAGE_ACTION_KEY': 'action',  # Field used for message type discrimination
    'CAMELIZE': False,  # Whether to convert between camelCase and snake_case
    'ERROR_FORMAT': 'standard',  # 'pydantic' for raw Pydantic error lists

    # 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
    'LOG_WEBSOCKET_MESSAGE': True,  # Whether to log websocket messages
    'LOG_IGNORED_ACTIONS': [],  # Message actions to ignore in logs

    # AsyncAPI documentation settings
    'ASYNCAPI_TITLE': 'AsyncAPI Documentation',
    'ASYNCAPI_DESCRIPTION': '',
    'ASYNCAPI_VERSION': '1.0.0',
    'ASYNCAPI_SERVER_URL': None,
    'ASYNCAPI_SERVER_PROTOCOL': None,
    'ASYNCAPI_SERVERS': None,  # AsyncAPI Server Objects by name
    'ASYNCAPI_SECURITY_SCHEMES': None,  # AsyncAPI Security Scheme Objects by name
    'ASYNCAPI_DOCS_JS_URL': None,  # Docs page script (default: pinned unpkg release)
    'ASYNCAPI_DOCS_CSS_URL': None,  # Docs page stylesheet (default: pinned unpkg release)
    'ASYNCAPI_DOCS_JS_INTEGRITY': None,  # SRI hash for a custom script URL
    'ASYNCAPI_DOCS_CSS_INTEGRITY': None,  # SRI hash for a custom stylesheet URL
}

Using Django Settings

You can use CHANX settings for some attributes instead of creating a base consumer:

from chanx.channels.websocket import AsyncJsonWebsocketConsumer

class MyConsumer(AsyncJsonWebsocketConsumer):
    # These will use CHANX settings automatically
    # send_completion, camelize, etc. read from settings

    # You can still override specific settings
    log_ignored_actions = ["ping", "pong"]

    # Django automatically uses 'default' channel layer
    # authenticator_class = MyAuthenticator  # Set if needed

Environment-Specific Configuration Examples#

Testing Configuration

For testing, it's recommended to enable completion messages:

# Django settings/test.py
CHANX = {
    'SEND_COMPLETION': True,  # Important for receive_all_messages() to work
    'LOG_WEBSOCKET_MESSAGE': False,  # Reduce noise in tests
    'LOG_IGNORED_ACTIONS': [],
}

# Or for FastAPI/other frameworks, in base consumer
from chanx.fast_channels.websocket import AsyncJsonWebsocketConsumer

class BaseConsumer(AsyncJsonWebsocketConsumer):
    send_completion = True  # Enable for testing
    log_websocket_message = False  # Reduce test noise

Production Configuration

For production, consider performance and logging:

# Django settings/prod.py
CHANX = {
    'SEND_COMPLETION': False,
    'LOG_WEBSOCKET_MESSAGE': True,
    'LOG_IGNORED_ACTIONS': ['ping', 'pong'],  # Reduce noise from heartbeats
}

# Or for FastAPI/other frameworks
from chanx.fast_channels.websocket import AsyncJsonWebsocketConsumer

class BaseConsumer(AsyncJsonWebsocketConsumer):
    send_completion = False
    log_websocket_message = True
    log_ignored_actions = ['ping', 'pong']

Framework-Specific Examples

# FastAPI example
import os
from chanx.fast_channels.websocket import AsyncJsonWebsocketConsumer

class BaseConsumer(AsyncJsonWebsocketConsumer):
    send_completion = bool(os.environ.get("SEND_COMPLETION", False))
    channel_layer_alias = "default"  # Required for non-Django

# Django example - uses CHANX settings automatically
from chanx.channels.websocket import AsyncJsonWebsocketConsumer as DjangoAsyncJsonWebsocketConsumer

class DjangoConsumer(DjangoAsyncJsonWebsocketConsumer):
    # Uses CHANX settings automatically
    authenticator_class = MyDjangoAuthenticator

Next Steps#

Now that you understand chanx's configuration options, proceed to the quick start:

  • Quick Start - Build your first consumer on Django or FastAPI