Django Channels Integration
============================

Chanx provides seamless integration with Django Channels, including WebSocket consumers,
AsyncAPI documentation views, DRF authentication, and testing utilities.

.. module:: chanx.channels

WebSocket Consumer
------------------
.. module:: chanx.channels.websocket

.. autoclass:: chanx.channels.websocket.AsyncJsonWebsocketConsumer
   :members:


Views
-----
.. module:: chanx.channels.views

.. autoclass:: chanx.channels.views.AsyncAPISchemaView
   :members:

.. autoclass:: chanx.channels.views.AsyncAPIDocsView
   :members:

.. autofunction:: chanx.channels.views.generate_asyncapi_schema


.. _management-commands:

Management Commands
-------------------
.. module:: chanx.channels.management.commands.generate_asyncapi_schema

Generate AsyncAPI schema files without requiring an HTTP server.

**Command:**

.. code-block:: bash

    python manage.py generate_asyncapi_schema [options]

**Parameters:**

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Option
     - Default
     - Description
   * - ``--format {json,yaml}``
     - ``yaml``
     - Output format for the schema file
   * - ``--file FILE``
     - ``stdout``
     - Output file path. If not specified, outputs to stdout
   * - ``--base-url BASE_URL``
     - ``settings`` or ``ws://localhost:8000``
     - WebSocket base URL (e.g., ``ws://localhost:8000`` or ``wss://api.example.com``)
   * - ``--title TITLE``
     - ``settings.ASYNCAPI_TITLE``
     - API title for AsyncAPI documentation
   * - ``--api-version VERSION``
     - ``settings.ASYNCAPI_VERSION``
     - API version for AsyncAPI documentation
   * - ``--description DESCRIPTION``
     - ``settings.ASYNCAPI_DESCRIPTION``
     - API description for AsyncAPI documentation
   * - ``--discovery-class CLASS``
     - ``DjangoRouteDiscovery``
     - Python path to custom route discovery class

**Examples:**

.. code-block:: bash

    # Generate YAML to file
    python manage.py generate_asyncapi_schema --format yaml --file schema.yaml

    # Generate JSON to stdout
    python manage.py generate_asyncapi_schema --format json

    # With custom metadata
    python manage.py generate_asyncapi_schema \
        --title "Production API" \
        --api-version "2.0.0" \
        --base-url wss://api.example.com \
        --file api.yaml


Authenticator
-------------
.. module:: chanx.channels.authenticator

Django REST Framework integration for WebSocket authentication.

.. autoclass:: chanx.channels.authenticator.DjangoAuthenticator
   :members:
   :exclude-members: authenticate

   .. automethod:: authenticate(scope: dict[str, Any]) -> bool
      :async:

.. autoclass:: chanx.channels.authenticator.ChanxAuthView
   :members:


Testing
-------
.. module:: chanx.channels.testing

.. autoclass:: chanx.channels.testing.WebsocketCommunicator
   :members:

.. autoclass:: chanx.channels.testing.DjangoWebsocketCommunicator
   :members:

.. autoclass:: chanx.channels.testing.WebsocketTestCase
   :members:


Utils
-----
.. module:: chanx.channels.utils.asgi

.. autofunction:: chanx.channels.utils.asgi.get_websocket_application


Settings
--------
.. module:: chanx.channels.settings

The Django Channels integration provides configuration through Django's settings system.
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:

.. code-block:: python

    # settings.py
    CHANX = {
        'MESSAGE_ACTION_KEY': 'action',
        'SEND_COMPLETION': False,
        'SEND_MESSAGE_IMMEDIATELY': True,
        'SEND_AUTHENTICATION_MESSAGE': True,
        'CAMELIZE': False,
        'LOG_WEBSOCKET_MESSAGE': True,
        'LOG_IGNORED_ACTIONS': ['ping', 'pong'],
        'WEBSOCKET_BASE_URL': None,
        # AsyncAPI documentation settings
        'ASYNCAPI_TITLE': 'AsyncAPI Documentation',
        'ASYNCAPI_DESCRIPTION': '',
        'ASYNCAPI_VERSION': '1.0.0',
        'ASYNCAPI_SERVER_URL': None,
        'ASYNCAPI_SERVER_PROTOCOL': None,
    }

Settings Details
~~~~~~~~~~~~~~~~
.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - 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
   * - ``CAMELIZE``
     - ``False``
     - Whether to convert message keys to camelCase format using pyhumps. When enabled, requires either installing Chanx with the ``camel-case`` extra (``pip install chanx[camel-case]``) or manually installing the pyhumps package (``pip install pyhumps``).
   * - ``LOG_WEBSOCKET_MESSAGE``
     - ``True``
     - Whether to log WebSocket messages (both received and sent)
   * - ``LOG_IGNORED_ACTIONS``
     - ``[]``
     - List of message actions that should not be logged (e.g., frequent messages like heartbeats)
   * - ``WEBSOCKET_BASE_URL``
     - ``None``
     - WebSocket URL for overriding in development or testing
   * - ``ASYNCAPI_TITLE``
     - ``"AsyncAPI Documentation"``
     - Title for generated AsyncAPI documentation
   * - ``ASYNCAPI_DESCRIPTION``
     - ``""``
     - Description for generated AsyncAPI documentation
   * - ``ASYNCAPI_VERSION``
     - ``"1.0.0"``
     - Version for generated AsyncAPI documentation
   * - ``ASYNCAPI_SERVER_URL``
     - ``None``
     - Server URL for AsyncAPI documentation (auto-detected if not set)
   * - ``ASYNCAPI_SERVER_PROTOCOL``
     - ``None``
     - Server protocol for AsyncAPI documentation (auto-detected if not set)

Using Settings in Code
~~~~~~~~~~~~~~~~~~~~~~
Chanx's settings are accessible through the ``chanx_settings`` object:

.. code-block:: python

    from chanx.channels.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

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

.. code-block:: bash

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