diff options
Diffstat (limited to 'venv/lib/python3.11/site-packages/litestar/datastructures/response_header.py')
-rw-r--r-- | venv/lib/python3.11/site-packages/litestar/datastructures/response_header.py | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/venv/lib/python3.11/site-packages/litestar/datastructures/response_header.py b/venv/lib/python3.11/site-packages/litestar/datastructures/response_header.py new file mode 100644 index 0000000..f781d0c --- /dev/null +++ b/venv/lib/python3.11/site-packages/litestar/datastructures/response_header.py @@ -0,0 +1,125 @@ +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +from litestar.exceptions import ImproperlyConfiguredException + +if TYPE_CHECKING: + from litestar.openapi.spec import Example + +__all__ = ("ResponseHeader",) + + +@dataclass +class ResponseHeader: + """Container type for a response header.""" + + name: str + """Header name""" + + documentation_only: bool = False + """Defines the ResponseHeader instance as for OpenAPI documentation purpose only.""" + + value: str | None = None + """Value to set for the response 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 = False + """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 = False + """Determines whether the parameter value SHOULD allow reserved characters, + as defined by. + + [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` 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] | 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. + """ + + def __post_init__(self) -> None: + """Ensure that either value is set or the instance is for documentation_only.""" + if not self.documentation_only and self.value is None: + raise ImproperlyConfiguredException("value must be set if documentation_only is false") + + def __hash__(self) -> int: + return hash(self.name) |