Installation

Requirements

Chanx has the following core dependencies:

  • Python 3.11+

  • Pydantic 2.0+

  • Structlog

  • PyHumps (for camelCase conversion)

  • Typing Extensions

Framework-specific dependencies are installed automatically based on which extra you choose.

Installing Chanx

For Django Channels Projects

pip install "chanx[channels]"

This installs:

  • Pydantic 2.0+ (validation)

  • Django 5.0+

  • Django Channels 4.0+

  • Django REST Framework 3.0+

  • Core dependencies (pyhumps, structlog, typing-extensions)

For FastAPI and Other ASGI Frameworks

pip install "chanx[fast_channels]"

This installs:

  • Pydantic 2.0+ (validation)

  • FastAPI 0.117+

  • fast-channels 1.0+

  • Core dependencies (pyhumps, structlog, typing-extensions)

For Client Generator CLI + Generated Clients

If you need both the CLI tool (for generating clients) and the ability to use generated clients:

# Using pip
pip install "chanx[cli,client]"

# Using uv (recommended approach)
uv add chanx[client]           # Runtime dependency
uv add --group dev chanx[cli]  # Development dependency

This installs:

  • Runtime (client): Pydantic 2.0+, websockets

  • Development (cli): click, httpx, jinja2, pyyaml (for code generation)

For Using Generated Clients Only

If you only need to use a generated client (not generate new ones):

# Using pip
pip install "chanx[client]"

# Using uv
uv add chanx[client]

This installs only:

  • Pydantic 2.0+ (for message validation)

  • websockets (for WebSocket connectivity)

No CLI tools, no server dependencies - just what's needed to run the generated client code.

Install from Source

git clone https://github.com/huynguyengl99/chanx.git
cd chanx
pip install -e ".[channels]"  # For Django
# or
pip install -e ".[fast_channels]"  # For FastAPI

Framework Setup

Django Channels Setup

  1. Add necessary apps to your INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'rest_framework',
    'channels',
    'chanx.channels',
    # ...
]

  1. Configure Chanx in your Django settings:

# settings.py
CHANX = {
    'CAMELIZE': False,  # Set to True for camelCase conversion
    'SEND_COMPLETION': False,  # Set to True for testing
    'LOG_WEBSOCKET_MESSAGE': True,
    # ...
}

FastAPI Setup

  1. Create a base consumer class:

# base_consumer.py
from chanx.fast_channels.websocket import AsyncJsonWebsocketConsumer

class BaseConsumer(AsyncJsonWebsocketConsumer):
    # Configure per your needs
    send_completion = False
    log_websocket_message = True
    channel_layer_alias = "default"

  1. Import and use in your consumers:

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

@channel(name="chat")
class ChatConsumer(BaseConsumer):
    @ws_handler
    async def handle_ping(self, message: PingMessage) -> PongMessage:
        return PongMessage()

Configuration Options

camelCase Conversion

Chanx includes automatic camelCase conversion. Enable it in your configuration:

# Django settings.py
CHANX = {
    'CAMELIZE': True,
    # ...
}

# Or for other frameworks, in your base consumer
class BaseConsumer(AsyncJsonWebsocketConsumer):
    camelize = True

CLI Usage

Once installed, you can use the client generator CLI with local files or URLs:

# Generate from local file (JSON or YAML)
chanx generate-client --schema asyncapi.json --output ./my_client
chanx generate-client --schema asyncapi.yaml --output ./my_client

# Generate directly from URL (no download needed)
chanx generate-client --schema http://localhost:8000/asyncapi.json --output ./my_client
chanx generate-client --schema https://api.example.com/asyncapi.yaml --output ./my_client

# With custom formatter
chanx generate-client --schema asyncapi.json --output ./my_client --formatter "black"

See Client Generator for complete CLI documentation.

Next Steps

Now that you have Chanx installed, proceed to: