Add comprehensive docstrings for public API attributes

oberstet · oberstet · commit 4b2a338ae37a · 2025-10-22T09:50:19.000+02:00
Added detailed Sphinx-compatible docstrings for the following public API attributes to improve documentation and developer experience: 1. autobahn.websocket.HAS_NVX - Explains build-time NVX availability check - Documents what NVX provides (UTF-8 validation, XOR masking) - Clarifies independence from AUTOBAHN_USE_NVX runtime setting - Includes usage example and cross-reference to USES_NVX 2. autobahn.websocket.USES_NVX - Explains runtime NVX usage decision - Documents interaction between build-time availability and runtime config - Provides complete AUTOBAHN_USE_NVX environment variable reference - Includes scenario examples and cross-reference to HAS_NVX 3. autobahn.twisted.__ident__ - Enhanced existing brief docstring with comprehensive documentation - Documents format variations (with/without NVX acceleration) - Explains usage in protocol handshakes (WebSocket Upgrade, WAMP HELLO) - Provides example values for different configurations - Cross-references asyncio.__ident__ and USES_NVX 4. autobahn.asyncio.__ident__ - Enhanced existing brief docstring with comprehensive documentation - Documents format variations (with/without NVX acceleration) - Explains usage in protocol handshakes (WebSocket Upgrade, WAMP HELLO) - Notes difference from Twisted variant (no asyncio version number) - Provides example values for different configurations - Cross-references twisted.__ident__ and USES_NVX All docstrings follow reStructuredText format for proper Sphinx rendering in Read the Docs documentation. This is a documentation-only change with no functional modifications. Related: This is a safe change to trigger final workflow testing before merging rel_v25.10.2 to master (addresses issues #1735, #1714).
diff --git a/autobahn/asyncio/__init__.py b/autobahn/asyncio/__init__.py
@@ -61,6 +61,41 @@
     __ident__ = "Autobahn/{}-asyncio-{}/{}".format(
         autobahn.__version__, platform.python_implementation(), platform.python_version()
     )
+
 """
-AutobahnPython library implementation (eg. "Autobahn/0.13.0-asyncio-CPython/3.5.1")
+Identification string for the Autobahn|Python asyncio backend.
+
+This string identifies the library version, networking framework, and runtime
+environment. It's commonly used in protocol handshakes (e.g., WebSocket Upgrade
+headers, WAMP HELLO metadata) to identify the client/server implementation.
+
+Format with NVX acceleration enabled::
+
+    "Autobahn/{version}-NVXCFFI/{cffi_version}-asyncio-{python_impl}/{python_version}"
+
+Format without NVX acceleration::
+
+    "Autobahn/{version}-asyncio-{python_impl}/{python_version}"
+
+The presence of ``NVXCFFI`` in the identification string indicates that NVX
+(Native Vector Extensions) native acceleration is enabled, providing high-performance
+UTF-8 validation and XOR masking using SIMD instructions.
+
+Note that asyncio is built into Python's standard library (since Python 3.4),
+so no separate asyncio version is included in the identification string (unlike
+the Twisted backend which includes the Twisted version).
+
+:type: str
+
+Example values::
+
+    # With NVX acceleration on CPython
+    "Autobahn/25.10.2-NVXCFFI/1.15.1-asyncio-CPython/3.11.9"
+
+    # Without NVX acceleration on PyPy
+    "Autobahn/25.10.2-asyncio-PyPy/7.3.16"
+
+See Also:
+    :data:`autobahn.twisted.__ident__` - Identification string for Twisted backend
+    :data:`autobahn.websocket.USES_NVX` - Whether NVX acceleration is enabled
 """
diff --git a/autobahn/twisted/__init__.py b/autobahn/twisted/__init__.py
@@ -80,6 +80,37 @@
         platform.python_implementation(),
         platform.python_version(),
     )
+
 """
-AutobahnPython library implementation (eg. "Autobahn/0.13.0-Twisted/15.5.0-CPython/3.5.1")
+Identification string for the Autobahn|Python Twisted backend.
+
+This string identifies the library version, networking framework, and runtime
+environment. It's commonly used in protocol handshakes (e.g., WebSocket Upgrade
+headers, WAMP HELLO metadata) to identify the client/server implementation.
+
+Format with NVX acceleration enabled::
+
+    "Autobahn/{version}-NVXCFFI/{cffi_version}-Twisted/{twisted_version}-{python_impl}/{python_version}"
+
+Format without NVX acceleration::
+
+    "Autobahn/{version}-Twisted/{twisted_version}-{python_impl}/{python_version}"
+
+The presence of ``NVXCFFI`` in the identification string indicates that NVX
+(Native Vector Extensions) native acceleration is enabled, providing high-performance
+UTF-8 validation and XOR masking using SIMD instructions.
+
+:type: str
+
+Example values::
+
+    # With NVX acceleration on CPython
+    "Autobahn/25.10.2-NVXCFFI/1.15.1-Twisted/24.7.0-CPython/3.11.9"
+
+    # Without NVX acceleration on PyPy
+    "Autobahn/25.10.2-Twisted/24.7.0-PyPy/7.3.16"
+
+See Also:
+    :data:`autobahn.asyncio.__ident__` - Identification string for asyncio backend
+    :data:`autobahn.websocket.USES_NVX` - Whether NVX acceleration is enabled
 """
diff --git a/autobahn/websocket/__init__.py b/autobahn/websocket/__init__.py
@@ -48,7 +48,37 @@
 except ImportError:
     # NVX not available (not built or CFFI compilation failed)
     pass
+
 HAS_NVX = _has_nvx
+"""
+Boolean flag indicating whether NVX (Native Vector Extensions) native acceleration
+modules are available in this installation.
+
+This is a build-time capability check - it's ``True`` if the NVX native extensions
+were successfully compiled and can be imported, ``False`` otherwise.
+
+NVX provides native implementations for performance-critical WebSocket operations:
+
+* UTF-8 validation using SIMD instructions
+* XOR masking using vectorized operations
+
+The value of ``HAS_NVX`` is independent of the runtime setting ``AUTOBAHN_USE_NVX``.
+To check if NVX is actually being used at runtime, see :data:`USES_NVX`.
+
+:type: bool
+
+Example::
+
+    from autobahn.websocket import HAS_NVX
+
+    if HAS_NVX:
+        print("NVX native acceleration is available")
+    else:
+        print("NVX not built - using pure Python implementations")
+
+See Also:
+    :data:`USES_NVX` - Whether NVX is actually enabled at runtime
+"""
 
 # Step 2: Parse AUTOBAHN_USE_NVX environment variable
 env_val = os.environ.get("AUTOBAHN_USE_NVX", "").strip().lower()
@@ -88,6 +118,43 @@
     # Case 5: Default behavior - use NVX if available
     USES_NVX = HAS_NVX
 
+"""
+Boolean flag indicating whether NVX (Native Vector Extensions) native acceleration
+is actually being used at runtime.
+
+This reflects the runtime configuration after considering both:
+
+* **Build-time availability** (:data:`HAS_NVX`) - Were NVX modules compiled?
+* **Runtime configuration** (``AUTOBAHN_USE_NVX`` environment variable) - Is NVX enabled?
+
+Possible scenarios:
+
+* ``USES_NVX = True``: NVX is built AND enabled (default when available)
+* ``USES_NVX = False``: Either NVX not built OR explicitly disabled via ``AUTOBAHN_USE_NVX=0``
+
+Control NVX at runtime using the ``AUTOBAHN_USE_NVX`` environment variable:
+
+* ``AUTOBAHN_USE_NVX=1`` - Force enable (raises error if not built)
+* ``AUTOBAHN_USE_NVX=0`` - Force disable (falls back to pure Python)
+* Unset or empty - Auto-enable if available (default)
+
+:type: bool
+
+Example::
+
+    from autobahn.websocket import USES_NVX, HAS_NVX
+
+    if USES_NVX:
+        print("Using NVX native acceleration for WebSocket operations")
+    elif HAS_NVX:
+        print("NVX available but disabled (AUTOBAHN_USE_NVX=0)")
+    else:
+        print("NVX not built - using pure Python implementations")
+
+See Also:
+    :data:`HAS_NVX` - Whether NVX was built and is available
+"""
+
 # ============================================================================
 # End of NVX Runtime Configuration
 # ============================================================================
