PyOpenXR Docstring Style Guide

This page establishes the docstring conventions for the pyopenxr codebase.

General Guidelines

• All public-facing Python objects must include docstrings.
• Use Sphinx-compatible reStructuredText syntax.
• Favor clarity over verbosity.
• Include :param:, :return:, and :raises: where appropriate.
• Use :class: and :func: for rich linking.

Docstring Examples

Function

def get_instance_proc_addr(instance: xr.Instance, name: str) -> xr.PFN_xrVoidFunction:
    """
    Retrieve a function pointer for an OpenXR core or extension function.

    This function wraps the native `xrGetInstanceProcAddr` call, allowing dynamic access
    to OpenXR API functions. It returns a raw function pointer that must be cast to the
    appropriate callable type before use.

    If `instance` is `None`, only a limited set of functions may be queried:
    - `xrEnumerateInstanceExtensionProperties`
    - `xrEnumerateApiLayerProperties`
    - `xrCreateInstance`

    For extension functions, the corresponding extension must have been enabled during
    instance creation via `enabled_extension_names`.

    :param instance: The OpenXR instance handle, or `None` for pre-instance functions.
    :type instance: xr.Instance
    :param name: The name of the function to query (e.g. `"xrCreateSession"`).
    :type name: str
    :return: A raw function pointer (`PFN_xrVoidFunction`) to the requested API function.
    :rtype: xr.PFN_xrVoidFunction
    :raises xr.FunctionUnsupportedError: If the function name is not recognized or not supported.
    :raises xr.HandleInvalidError: If the provided instance handle is invalid.
    :raises xr.InstanceLossPendingError: If the instance is in a loss-pending state.
    :raises xr.InitializationFailedError: If the runtime failed to initialize the query.
    :raises xr.RuntimeFailureError: For general runtime failure not covered by other error codes.
    :seealso: :class:`xr.PFN_xrVoidFunction`
    """

Class

class Instance:
    """
    Opaque handle to an OpenXR instance object.

    An `xr.Instance` represents a connection between an OpenXR application and the
    OpenXR runtime. It encapsulates all runtime-managed state and serves as the root
    object for most OpenXR operations, including system queries, session creation,
    and extension dispatch.

    This object may be instantiated directly with an optional :class:`xr.InstanceCreateInfo`
    descriptor. If none is provided, a default descriptor will be used. Initialization
    wraps the native :func:`xrCreateInstance` call and is performed lazily, with runtime
    bindings imported just-in-time to avoid circular dependencies and import-time overhead.

    `Instance` supports context management protocols and may be used in a `with` block
    for automatic teardown via :func:`xr.destroy_instance`:

    .. code-block:: python

        with xr.Instance(...) as instance:
            ...

    Internally, this object wraps a pointer to the OpenXR instance and delegates all
    interactions to the runtime via raw API functions. It is opaque and cannot be
    directly inspected or modified.

    :param create_info: Optional descriptor specifying application info, enabled extensions,
                        and platform-specific parameters.
    :type create_info: xr.InstanceCreateInfo or None

    :raises xr.ValidationFailureError: If validation layers reject the configuration.
    :raises xr.RuntimeFailureError: If the runtime fails to initialize.
    :raises xr.OutOfMemoryError: If memory allocation fails.
    :raises xr.LimitReachedError: If the runtime cannot support additional instances.
    :raises xr.RuntimeUnavailableError: If no runtime is available.
    :raises xr.NameInvalidError: If the application name is empty.
    :raises xr.InitializationFailedError: If platform-specific initialization fails.
    :raises xr.ExtensionNotPresentError: If a requested extension is missing.
    :raises xr.ExtensionDependencyNotEnabledError: If an extension dependency is missing.
    :raises xr.ApiVersionUnsupportedError: If the requested API version is not supported.
    :raises xr.ApiLayerNotPresentError: If a requested API layer is missing.

    :seealso: :func:`xr.create_instance`, :func:`xr.destroy_instance`, :class:`xr.InstanceCreateInfo`
    :see: https://registry.khronos.org/OpenXR/specs/1.1/man/html/XrInstance.html
    """

Module

"""
`xr` is the root module of pyopenxr, an unofficial Python binding for the OpenXR SDK.

It provides low-level access to the core OpenXR API for interacting with VR and AR runtimes,
including system queries, session management, and extension dispatch. This module wraps the
standard C interface in a Pythonic structure while preserving fidelity to the original spec.

For high-level utilities and ergonomic abstractions, see submodules and helper packages.
"""

"""
Module xr.ext.KHR.opengl_enable — Python bindings for the XR_KHR_opengl_enable extension.

This module provides access to OpenGL-specific graphics requirements via OpenXR.
It exposes a Pythonic wrapper around `xrGetOpenGLGraphicsRequirementsKHR`, allowing
applications to query the minimum and maximum supported OpenGL versions for a given system.

To use this extension, ensure `"XR_KHR_opengl_enable"` is included in the list of
enabled extensions during instance creation.

:see: https://registry.khronos.org/OpenXR/specs/1.1/man/html/XR_KHR_opengl_enable.html
"""

Constant or Variable

NAME = "XR_KHR_opengl_enable"
"""The extension name string used during instance creation."""

Notes

• Use .. code-block:: python only when embedding examples inside docstrings.
• Prefer linking over repetition.
• Internal/private symbols don’t require full docstrings unless exposed during debugging.