django-bolt 0.1.0__cp310-abi3-win_amd64.whl

django_bolt/openapi/spec/base.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, fields, is_dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from dataclasses import Field
+
+__all__ = ("BaseSchemaObject",)
+
+
+def _normalize_key(key: str) -> str:
+    if key.endswith("_in"):
+        return "in"
+    if key.startswith("schema_"):
+        return key.split("_")[1]
+    if "_" in key:
+        components = key.split("_")
+        return components[0] + "".join(component.title() for component in components[1:])
+    return "$ref" if key == "ref" else key
+
+
+def _normalize_value(value: Any) -> Any:
+    if isinstance(value, BaseSchemaObject):
+        return value.to_schema()
+    if is_dataclass(value):
+        return {
+            _normalize_value(k): _normalize_value(v)
+            for k, v in asdict(value).items()  # type: ignore[call-overload]
+            if v is not None
+        }
+    if isinstance(value, dict):
+        return {_normalize_value(k): _normalize_value(v) for k, v in value.items() if v is not None}
+    if isinstance(value, list):
+        return [_normalize_value(v) for v in value]
+    return value.value if isinstance(value, Enum) else value
+
+
+@dataclass
+class BaseSchemaObject:
+    """Base class for schema spec objects"""
+
+    @property
+    def _exclude_fields(self) -> set[str]:
+        return set()
+
+    def _iter_fields(self) -> Iterator[Field[Any]]:
+        yield from fields(self)
+
+    def to_schema(self) -> dict[str, Any]:
+        """Transform the spec dataclass object into a string keyed dictionary. This method traverses all nested values
+        recursively.
+        """
+        result: dict[str, Any] = {}
+        exclude = self._exclude_fields
+
+        for field in self._iter_fields():
+            if field.name in exclude:
+                continue
+            value = _normalize_value(getattr(self, field.name, None))
+
+            if value is not None:
+                if "alias" in field.metadata:
+                    if not isinstance(field.metadata["alias"], str):
+                        raise TypeError('metadata["alias"] must be a str')
+                    key = field.metadata["alias"]
+                else:
+                    key = _normalize_key(field.name)
+
+                result[key] = value
+
+        return result

django_bolt/openapi/spec/callback.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Union
+
+if TYPE_CHECKING:
+    from .path_item import PathItem
+    from .reference import Reference
+
+
+Callback = dict[str, Union["PathItem", "Reference"]]
+"""A map of possible out-of band callbacks related to the parent operation. Each value in the map is a
+`Path Item Object <https://spec.openapis.org/oas/v3.1.0#pathItemObject>`_ that describes a set of requests that may be
+initiated by the API provider and the expected responses. The key value used to identify the path item object is an
+expression, evaluated at runtime, that identifies a URL to use for the callback operation.
+
+Patterned Fields
+
+{expression}: 'PathItem' = ...
+
+A Path Item Object used to define a callback request and expected responses.
+
+A `complete example <https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml>`_ is
+available.
+"""

django_bolt/openapi/spec/components.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .base import BaseSchemaObject
+
+__all__ = ("Components",)
+
+
+if TYPE_CHECKING:
+    from .callback import Callback
+    from .example import Example
+    from .header import OpenAPIHeader
+    from .link import Link
+    from .parameter import Parameter
+    from .path_item import PathItem
+    from .reference import Reference
+    from .request_body import RequestBody
+    from .response import OpenAPIResponse
+    from .schema import Schema
+    from .security_scheme import SecurityScheme
+
+
+@dataclass
+class Components(BaseSchemaObject):
+    """Holds a set of reusable objects for different aspects of the OAS.
+
+    All objects defined within the components object will have no effect
+    on the API unless they are explicitly referenced from properties
+    outside the components object.
+    """
+
+    schemas: dict[str, Schema] = field(default_factory=dict)
+    """An object to hold reusable
+    `Schema Objects <https://spec.openapis.org/oas/v3.1.0#schemaObject>`_"""
+
+    responses: dict[str, OpenAPIResponse | Reference] | None = None
+    """An object to hold reusable
+    `Response Objects <https://spec.openapis.org/oas/v3.1.0#responseObject>`_"""
+
+    parameters: dict[str, Parameter | Reference] | None = None
+    """An object to hold reusable
+    `Parameter Objects <https://spec.openapis.org/oas/v3.1.0#parameterObject>`_"""
+
+    examples: dict[str, Example | Reference] | None = None
+    """An object to hold reusable
+    `Example Objects <https://spec.openapis.org/oas/v3.1.0#exampleObject>`_"""
+
+    request_bodies: dict[str, RequestBody | Reference] | None = None
+    """An object to hold reusable
+    `Request Body Objects <https://spec.openapis.org/oas/v3.1.0#requestBodyObject>`_"""
+
+    headers: dict[str, OpenAPIHeader | Reference] | None = None
+    """An object to hold reusable
+    `Header  Objects <https://spec.openapis.org/oas/v3.1.0#headerObject>`_"""
+
+    security_schemes: dict[str, SecurityScheme | Reference] | None = None
+    """An object to hold reusable
+    `Security Scheme  Objects <https://spec.openapis.org/oas/v3.1.0#securitySchemeObject>`_"""
+
+    links: dict[str, Link | Reference] | None = None
+    """An object to hold reusable
+    `Link Objects <https://spec.openapis.org/oas/v3.1.0#linkObject>`_"""
+
+    callbacks: dict[str, Callback | Reference] | None = None
+    """An object to hold reusable
+    `Callback Objects <https://spec.openapis.org/oas/v3.1.0#callbackObject>`_"""
+
+    path_items: dict[str, PathItem | Reference] | None = None
+    """An object to hold reusable
+    `Path Item Object <https://spec.openapis.org/oas/v3.1.0#pathItemObject>`_"""

django_bolt/openapi/spec/contact.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base import BaseSchemaObject
+
+__all__ = ("Contact",)
+
+
+@dataclass
+class Contact(BaseSchemaObject):
+    """Contact information for the exposed API."""
+
+    name: str | None = None
+    """The identifying name of the contact person/organization."""
+
+    url: str | None = None
+    """The URL pointing to the contact information. MUST be in the form of a URL."""
+
+    email: str | None = None
+    """The email address of the contact person/organization. MUST be in the form of an email address."""

django_bolt/openapi/spec/discriminator.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base import BaseSchemaObject
+
+__all__ = ("Discriminator",)
+
+
+@dataclass(unsafe_hash=True)
+class Discriminator(BaseSchemaObject):
+    """When request bodies or response payloads may be one of a number of different schemas, a ``discriminator``
+    object can be used to aid in serialization, deserialization, and validation.
+
+    The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an
+    alternative schema based on the value associated with it.
+
+    When using the discriminator, _inline_ schemas will not be considered.
+    """
+
+    property_name: str
+    """**REQUIRED**. The name of the property in the payload that will hold the discriminator value."""
+
+    mapping: dict[str, str] | None = None
+    """An object to hold mappings between payload values and schema names or references."""

django_bolt/openapi/spec/encoding.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from .header import OpenAPIHeader
+    from .reference import Reference
+
+__all__ = ("Encoding",)
+
+
+@dataclass
+class Encoding(BaseSchemaObject):
+    """A single encoding definition applied to a single schema property."""
+
+    content_type: str | None = None
+    """The Content-Type for encoding a specific property. Default value depends n the property type:
+
+    - for ``object``: ``application/json``
+    - for ``array``: the default is defined based on the inner type
+    - for all other cases the default is ``application/octet-stream``.
+
+    The value can be a specific media type (e.g. ``application/json``), a wildcard media type (e.g. ``image/*``), or a
+    comma-separated list of the two types.
+    """
+
+    headers: dict[str, OpenAPIHeader | Reference] | None = None
+    """A map allowing additional information to be provided as headers, for example ``Content-Disposition``.
+
+    ``Content-Type`` is described separately and SHALL be ignored in this section. This property SHALL be ignored if the
+    request body media type is not a ``multipart``.
+    """
+
+    style: str | None = None
+    """Describes how a specific property value will be serialized depending on its type.
+
+    See `Parameter Object <https://spec.openapis.org/oas/v3.1.0#parameterObject>`_ for details on the
+    `style <https://spec.openapis.org/oas/v3.1.0#parameterStyle>`__ property. The behavior follows the same values as
+    ``query`` parameters, including default values. This property SHALL be ignored if the request body media type is not
+    ``application/x-www-form-urlencoded`` or ``multipart/form-data``. If a value is explicitly defined, then the value
+    of `contentType <https://spec.openapis.org/oas/v3.1.0#encodingContentType>`_ (implicit or explicit) SHALL be
+    ignored.
+    """
+
+    explode: bool = False
+    """When this is true, property values of type ``array`` or ``object`` generate separate parameters for each value of
+    the array, or key-value-pair of the map.
+
+    For other types of properties this property has no effect. When
+    `style <https://spec.openapis.org/oas/v3.1.0#encodingStyle>`_ is ``form``, the default value is ``True``. For all
+    other styles, the default value is ``False``. This property SHALL be ignored if the request body media type is not
+    ``application/x-www-form-urlencoded`` or ``multipart/form-data``. If a value is explicitly defined, then the value
+    of `contentType <https://spec.openapis.org/oas/v3.1.0#encodingContentType>`_ (implicit or explicit) SHALL be
+    ignored.
+    """
+
+    allow_reserved: bool = False
+    """Determines whether the parameter value SHOULD allow reserved characters, as defined by :rfc:`3986`
+    (``:/?#[]@!$&'()*+,;=``) to be included without percent-encoding.
+
+    This property SHALL be ignored if the request body media type s not ``application/x-www-form-urlencoded`` or
+    ``multipart/form-data``. If a value is explicitly defined, then the value of
+    `contentType <https://spec.openapis.org/oas/v3.1.0#encodingContentType>`_ (implicit or explicit) SHALL be ignored.
+    """

django_bolt/openapi/spec/enums.py

@@ -0,0 +1,41 @@
+from enum import Enum
+
+__all__ = ("OpenAPIFormat", "OpenAPIType")
+
+
+class OpenAPIFormat(str, Enum):
+    """Formats extracted from: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#page-13"""
+
+    DATE = "date"
+    DATE_TIME = "date-time"
+    TIME = "time"
+    DURATION = "duration"
+    URL = "url"
+    EMAIL = "email"
+    IDN_EMAIL = "idn-email"
+    HOST_NAME = "hostname"
+    IDN_HOST_NAME = "idn-hostname"
+    IPV4 = "ipv4"
+    IPV6 = "ipv6"
+    URI = "uri"
+    URI_REFERENCE = "uri-reference"
+    URI_TEMPLATE = "uri-template"
+    JSON_POINTER = "json-pointer"
+    RELATIVE_JSON_POINTER = "relative-json-pointer"
+    IRI = "iri-reference"
+    IRI_REFERENCE = "iri-reference"  # noqa: PIE796
+    UUID = "uuid"
+    REGEX = "regex"
+    BINARY = "binary"
+
+
+class OpenAPIType(str, Enum):
+    """An OopenAPI type."""
+
+    ARRAY = "array"
+    BOOLEAN = "boolean"
+    INTEGER = "integer"
+    NULL = "null"
+    NUMBER = "number"
+    OBJECT = "object"
+    STRING = "string"

django_bolt/openapi/spec/example.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .base import BaseSchemaObject
+
+
+@dataclass
+class Example(BaseSchemaObject):
+    id: str | None = None
+    """Optional ID for the example. When provided, this will be used as the key in the OpenAPI specification."""
+
+    summary: str | None = None
+    """Short description for the example."""
+
+    description: str | None = None
+    """Long description for the example.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
+    """
+
+    value: Any | None = None
+    """Embedded literal example.
+
+    The ``value`` field and ``externalValue`` field are mutually exclusive. To represent examples of media types that
+    cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.
+    """
+
+    external_value: str | None = None
+    """A URL that points to the literal example. This provides the capability to reference examples that cannot easily
+    be included in JSON or YAML documents.
+
+    The ``value`` field and ``externalValue`` field are mutually exclusive. See the rules for resolving
+    `Relative References <https://spec.openapis.org/oas/v3.1.0#relativeReferencesURI>`_.
+    """

django_bolt/openapi/spec/external_documentation.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base import BaseSchemaObject
+
+__all__ = ("ExternalDocumentation",)
+
+
+@dataclass
+class ExternalDocumentation(BaseSchemaObject):
+    """Allows referencing an external resource for extended documentation."""
+
+    url: str
+    """**REQUIRED**. The URL for the target documentation. Value MUST be in the form of a URL."""
+
+    description: str | None = None
+    """A short description of the target documentation.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
+    """

django_bolt/openapi/spec/header.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from .example import Example
+    from .media_type import OpenAPIMediaType
+    from .reference import Reference
+    from .schema import Schema
+
+__all__ = ("OpenAPIHeader",)
+
+
+@dataclass
+class OpenAPIHeader(BaseSchemaObject):
+    """The Header Object follows the structure of the [Parameter
+    Object](https://spec.openapis.org/oas/v3.1.0#parameterObject) with the
+    following changes:
+
+    1. ``name`` MUST NOT be specified, it is given in the corresponding ``headers`` map.
+    2. ``in`` MUST NOT be specified, it is implicitly in ``header``.
+    3. All traits that are affected by the location MUST be applicable to a location of ``header``
+       (for example, `style <https://spec.openapis.org/oas/v3.1.0#parameterStyle>`__).
+    """
+
+    schema: Schema | Reference | None = None
+    """The schema defining the type used for the parameter."""
+
+    name: Literal[""] = ""
+    """MUST NOT be specified, it is given in the corresponding ``headers`` map."""
+
+    param_in: Literal["header"] = "header"
+    """MUST NOT be specified, it is implicitly in ``header``."""
+
+    description: str | None = None
+    """A brief description of the parameter. This could contain examples of
+    use.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
+    """
+
+    required: bool = False
+    """Determines whether this parameter is mandatory.
+
+    If the `parameter location <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_ is ``"path"``, this property is
+    **REQUIRED** and its value MUST be ``True``. Otherwise, the property MAY be included and its default value is
+    ``False``.
+    """
+
+    deprecated: bool = False
+    """Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is ``False``."""
+
+    allow_empty_value: bool = None  # type: ignore[assignment]
+    """Sets the ability to pass empty-valued parameters. This is valid only for ``query`` parameters and allows sending
+    a parameter with an empty value. Default value is ``False``. If
+    `style <https://spec.openapis.org/oas/v3.1.0#parameterStyle>`__ is used, and if behavior is ``n/a`` (cannot be
+    serialized), the value of ``allowEmptyValue`` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is
+    likely to be removed in a later revision.
+
+    The rules for serialization of the parameter are specified in one of two ways.For simpler scenarios, a
+    `schema <https://spec.openapis.org/oas/v3.1.0#parameterSchema>`_ and
+    `style <https://spec.openapis.org/oas/v3.1.0#parameterStyle>`__ can describe the structure and syntax of the
+    parameter.
+    """
+
+    style: str | None = None
+    """Describes how the parameter value will be serialized depending on the
+    type of the parameter value. Default values (based on value of ``in``):
+
+    - for ``query`` - ``form``;
+    - for ``path`` - ``simple``;
+    - for ``header`` - ``simple``;
+    - for ``cookie`` - ``form``.
+    """
+
+    explode: bool | None = None
+    """When this is true, parameter values of type ``array`` or ``object`` generate separate parameters for each value
+    of the array or key-value pair of the map.
+
+    For other types of parameters this property has no effect.When
+    `style <https://spec.openapis.org/oas/v3.1.0#parameterStyle>`__ is ``form``, the default value is ``True``. For all
+    other styles, the default value is ``False``.
+    """
+
+    allow_reserved: bool = None  # type: ignore[assignment]
+    """Determines whether the parameter value SHOULD allow reserved characters, as defined by. :rfc:`3986`
+    (``:/?#[]@!$&'()*+,;=``) to be included without percent-encoding.
+
+    This property only applies to parameters with an ``in`` value of ``query``. The default value is ``False``.
+    """
+
+    example: Any | None = None
+    """Example of the parameter's potential value.
+
+    The example SHOULD match the specified schema and encoding properties if present. The ``example`` field is mutually
+    exclusive of the ``examples`` field. Furthermore, if referencing a ``schema`` that contains an example, the
+    ``example`` value SHALL _override_ the example provided by the schema. To represent examples of media types that
+    cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where
+    necessary.
+    """
+
+    examples: dict[str, Example | Reference] | None = None
+    """Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as
+    specified in the parameter encoding. The ``examples`` field is mutually exclusive of the ``example`` field.
+    Furthermore, if referencing a ``schema`` that contains an example, the ``examples`` value SHALL _override_ the
+    example provided by the schema.
+
+    For more complex scenarios, the `content <https://spec.openapis.org/oas/v3.1.0#parameterContent>`_ property can
+    define the media type and schema of the parameter. A parameter MUST contain either a ``schema`` property, or a
+    ``content`` property, but not both. When ``example`` or ``examples`` are provided in conjunction with the ``schema``
+    object, the example MUST follow the prescribed serialization strategy for the parameter.
+    """
+
+    content: dict[str, OpenAPIMediaType] | None = None
+    """A map containing the representations for the parameter.
+
+    The key is the media type and the value describes it. The map MUST only contain one entry.
+    """
+
+    @property
+    def _exclude_fields(self) -> set[str]:
+        return {"name", "param_in", "allow_reserved", "allow_empty_value"}
+
+    def __post_init__(self) -> None:
+        if self.allow_reserved is None:
+            self.allow_reserved = False  # type: ignore[unreachable]
+
+        if self.allow_empty_value is None:
+            self.allow_empty_value = False  # type: ignore[unreachable]

django_bolt/openapi/spec/info.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from .contact import Contact
+    from .license import License
+
+__all__ = ("Info",)
+
+
+@dataclass
+class Info(BaseSchemaObject):
+    """The object provides metadata about the API.
+
+    The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools
+    for convenience.
+    """
+
+    title: str
+    """
+    **REQUIRED**. The title of the API.
+    """
+
+    version: str
+    """
+    **REQUIRED**. The version of the OpenAPI document which is distinct from the
+    `OpenAPI Specification version <https://spec.openapis.org/oas/v3.1.0#oasVersion>`_ or the API implementation version
+    """
+
+    summary: str | None = None
+    """A short summary of the API."""
+
+    description: str | None = None
+    """A description of the API.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
+    """
+
+    terms_of_service: str | None = None
+    """A URL to the Terms of Service for the API. MUST be in the form of a URL."""
+
+    contact: Contact | None = None
+    """The contact information for the exposed API."""
+
+    license: License | None = None
+    """The license information for the exposed API."""

django_bolt/openapi/spec/license.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base import BaseSchemaObject
+
+__all__ = ("License",)
+
+
+@dataclass
+class License(BaseSchemaObject):
+    """License information for the exposed API."""
+
+    name: str
+    """**REQUIRED**. The license name used for the API."""
+
+    identifier: str | None = None
+    """An
+    `SPDX <https://spdx.github.io/spdx-spec/v2.3/SPDX-license-list/#a1-licenses-with-short-identifiers>`_ license expression for the API.
+
+    The ``identifier`` field is mutually exclusive of the ``url`` field.
+    """
+
+    url: str | None = None
+    """A URL to the license used for the API.
+
+    This MUST be in the form of a URL. The ``url`` field is mutually exclusive of the ``identifier`` field.
+    """

django_bolt/openapi/spec/link.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from .server import Server
+
+__all__ = ("Link",)
+
+
+@dataclass
+class Link(BaseSchemaObject):
+    """The ``Link object`` represents a possible design-time link for a response. The presence of a link does not
+    guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal
+    mechanism between responses and other operations.
+
+    Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require
+    link information in the runtime response.
+
+    For computing links, and providing instructions to execute them, a
+    `runtime expression <https://spec.openapis.org/oas/v3.1.0#runtimeExpression>`_ is used for accessing values in an
+    operation and using them as parameters while invoking the linked operation.
+    """
+
+    operation_ref: str | None = None
+    """A relative or absolute URI reference to an OAS operation.
+
+    This field is mutually exclusive of the ``operationId`` field, and MUST point to an
+    `Operation Object <https://spec.openapis.org/oas/v3.1.0#operationObject>`_. Relative ``operationRef`` values MAY be
+    used to locate an existing `Operation Object <https://spec.openapis.org/oas/v3.1.0#operationObject>`_ in the OpenAPI
+    definition. See the rules for resolving
+    `Relative References <https://spec.openapis.org/oas/v3.1.0#relativeReferencesURI>`_
+    """
+
+    operation_id: str | None = None
+    """The name of an _existing_, resolvable OAS operation, as defined with a unique ``operationId``.
+
+    This field is mutually exclusive of the ``operationRef`` field.
+    """
+
+    parameters: dict[str, Any] | None = None
+    """A map representing parameters to pass to an operation as specified with ``operationId`` or identified via
+    ``operationRef``. The key is the parameter name to be used, whereas the value can be a constant or an expression to
+    be evaluated and passed to the linked operation.
+
+    The parameter name can be qualified using the
+    `parameter location <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_ ``[{in}.]{name}`` for operations that use
+    the same parameter name in different locations (e.g. path.id).
+    """
+
+    request_body: Any | None = None
+    """A literal value or
+    `{expression} <https://spec.openapis.org/oas/v3.1.0#runtimeExpression>`_ to use as a request body when calling the
+    target operation."""
+
+    description: str | None = None
+    """A description of the link.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
+    """
+
+    server: Server | None = None
+    """A server object to be used by the target operation."""