datastructures¶

class litestar.datastructures.URL¶

Bases: object

Representation and modification utilities of a URL.

scheme: str¶: URL scheme.

netloc: str¶: Network location.

path: str¶: Hierarchical path.

fragment: str¶: Fragment component.

query: str¶: Query string.

username: str | None¶: Username if specified.

password: str | None¶: Password if specified.

port: int | None¶: Port if specified.

hostname: str | None¶: Hostname if specified.

static __new__(cls, url: str | SplitResult) → URL¶

Create a new instance.

Parameters:: url¶ – url string or split result to represent.

classmethod from_components(scheme: str = '', netloc: str = '', path: str = '', fragment: str = '', query: str = '') → Self¶

Create a new URL from components.

Parameters:

scheme¶ – URL scheme
netloc¶ – Network location
path¶ – Hierarchical path
query¶ – Query component
fragment¶ – Fragment identifier

Returns:

A new URL with the given components

classmethod from_scope(scope: Scope) → Self¶

Construct a URL from a Scope

Parameters:: scope¶ – A scope
Returns:: A URL

with_replacements(scheme: str = '', netloc: str = '', path: str = '', query: str | MultiDict | None | EmptyType = _EmptyEnum.EMPTY, fragment: str = '') → Self¶

Create a new URL, replacing the given components.

Parameters:

scheme¶ – URL scheme
netloc¶ – Network location
path¶ – Hierarchical path
query¶ – Raw query string
fragment¶ – Fragment identifier

Returns:

A new URL with the given components replaced

property query_params: MultiDict¶

Query parameters of a URL as a MultiDict

Returns:: A MultiDict with query parameters

Notes

The returned MultiDict is mutable, URL itself is immutable,
therefore mutating the query parameters will not directly mutate the URL. If you want to modify query parameters, make modifications in the multidict and pass them back to with_replacements()

class litestar.datastructures.Accept¶

Bases: object

An Accept header.

__init__(accept_value: str) → None¶

best_match(provided_types: list[str], default: str | None = None) → str | None¶

Find the best matching media type for the request.

Parameters:

provided_types¶ – A list of media types that can be provided as a response. These types can contain a wildcard * character in the main- or subtype part.
default¶ – The media type that is returned if none of the provided types match.

Returns:

The best matching media type. If the matching provided type contains wildcard characters, they are replaced with the corresponding part of the accepted type. Otherwise the provided type is returned as-is.

accepts(media_type: str) → bool¶

Check if the request accepts the specified media type.

If multiple media types can be provided, it is better to use best_match().

Parameters:: media_type¶ – The media type to check for.
Returns:: True if the request accepts media_type.

class litestar.datastructures.Address¶

Bases: NamedTuple

Just a network address.

host: str¶: Address host.

port: int¶: Address port.

static __new__(_cls, host: str, port: int)¶: Create new instance of Address(host, port)

class litestar.datastructures.CacheControlHeader¶

Bases: Header

A cache-control header.

max_age: int | None = None¶: Accessor for the max-age directive.

s_maxage: int | None = None¶: Accessor for the s-maxage directive.

no_cache: bool | None = None¶: Accessor for the no-cache directive.

no_store: bool | None = None¶: Accessor for the no-store directive.

private: bool | None = None¶: Accessor for the private directive.

public: bool | None = None¶: Accessor for the public directive.

no_transform: bool | None = None¶: Accessor for the no-transform directive.

must_revalidate: bool | None = None¶: Accessor for the must-revalidate directive.

proxy_revalidate: bool | None = None¶: Accessor for the proxy-revalidate directive.

must_understand: bool | None = None¶: Accessor for the must-understand directive.

immutable: bool | None = None¶: Accessor for the immutable directive.

stale_while_revalidate: int | None = None¶: Accessor for the stale-while-revalidate directive.

classmethod from_header(header_value: str) → CacheControlHeader¶

Create a CacheControlHeader instance from the header value.

Parameters:: header_value¶ – the header value as string
Returns:: An instance of CacheControlHeader

classmethod prevent_storing() → CacheControlHeader¶: Create a cache-control header with the no-store directive which indicates that any caches of any kind (private or shared) should not store this response.

__init__(documentation_only: bool = False, max_age: int | None = None, s_maxage: int | None = None, no_cache: bool | None = None, no_store: bool | None = None, private: bool | None = None, public: bool | None = None, no_transform: bool | None = None, must_revalidate: bool | None = None, proxy_revalidate: bool | None = None, must_understand: bool | None = None, immutable: bool | None = None, stale_while_revalidate: int | None = None) → None¶

class litestar.datastructures.Cookie¶

Bases: object

Container class for defining a cookie using the Set-Cookie header.

See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie for more details regarding this header.

key: str¶: Key for the cookie.

path: str = '/'¶

Path fragment that must exist in the request url for the cookie to be valid.

Defaults to /.

value: str | None = None¶: Value for the cookie, if none given defaults to empty string.

max_age: int | None = None¶: Maximal age of the cookie before its invalidated.

expires: int | None = None¶: Seconds from now until the cookie expires.

domain: str | None = None¶: Domain for which the cookie is valid.

secure: bool | None = None¶: Https is required for the cookie.

httponly: bool | None = None¶: Forbids javascript to access the cookie via document.cookie.

__init__(key: str, path: str = '/', value: str | None = None, max_age: int | None = None, expires: int | None = None, domain: str | None = None, secure: bool | None = None, httponly: bool | None = None, samesite: Literal['lax', 'strict', 'none'] = 'lax', description: str | None = None, documentation_only: bool = False) → None¶

samesite: Literal['lax', 'strict', 'none'] = 'lax'¶

Controls whether or not a cookie is sent with cross-site requests.

Defaults to ‘lax’.

description: str | None = None¶: Description of the response cookie header for OpenAPI documentation.

documentation_only: bool = False¶: Defines the Cookie instance as for OpenAPI documentation purpose only.

property simple_cookie: SimpleCookie¶

Get a simple cookie object from the values.

Returns:: A SimpleCookie

to_header(**kwargs: Any) → str¶

Return a string representation suitable to be sent as HTTP headers.

Parameters:: **kwargs¶ – Any kwargs to pass to the simple cookie output method.

to_encoded_header() → tuple[bytes, bytes]¶

Create encoded header for ASGI send.

Returns:: A two tuple of bytes.

property dict: dict[str, Any]¶

Get the cookie as a dict.

Returns:: A dict of values

__eq__(other: Any) → bool¶

Determine whether two cookie instances are equal according to the cookie spec, i.e. hey have a similar path, domain and key.

Parameters:: other¶ – An arbitrary value
Returns:: A boolean

class litestar.datastructures.ETag¶

Bases: Header

An etag header.

classmethod from_header(header_value: str) → ETag¶

Construct an etag header from its string representation.

Note that this will unquote etag-values

__init__(documentation_only: bool = False, weak: bool = False, value: str | None = None) → None¶

class litestar.datastructures.FormMultiDict¶

Bases: ImmutableMultiDict[Any]

MultiDict for form data.

classmethod from_form_data(form_data: dict[str, list[str] | str | litestar.datastructures.upload_file.UploadFile]) → FormMultiDict¶

Create a FormMultiDict from form data.

Parameters:: form_data¶ – Form data to create the FormMultiDict from.
Returns:: A FormMultiDict instance

async close() → None¶

Close all files in the multi-dict.

Returns:: None

class litestar.datastructures.Header¶

Bases: ABC

An abstract type for HTTP headers.

documentation_only: bool = False¶: Defines the header instance as for OpenAPI documentation purpose only.

abstract classmethod from_header(header_value: str) → Header¶: Construct a header from its string representation.

to_header(include_header_name: bool = False) → str¶

Get the header as string.

Parameters:: include_header_name¶ – should include the header name in the return value. If set to false the return value will only include the header value. if set to true the return value will be: <header name>: <header value>. Defaults to false.

__init__(documentation_only: bool = False) → None¶

class litestar.datastructures.Headers¶

Bases: CIMultiDictProxy[str], MultiMixin[str]

An immutable, case-insensitive multi dict for HTTP headers.

__init__(headers: Mapping[str, str] | RawHeaders | MultiMapping | None = None) → None¶

Initialize Headers.

Parameters:: headers¶ – Initial value.

classmethod from_scope(scope: Scope) → Headers¶

Create headers from a send-message.

Parameters:: scope¶ – The ASGI connection scope.
Returns:: Headers
Raises:: ValueError – If the message does not have a headers key

to_header_list() → RawHeadersList¶

Raw header value.

Returns:: A list of tuples contain the header and header-value as bytes

class litestar.datastructures.ImmutableMultiDict¶

Bases: MultiDictProxy[T], MultiMixin[T], Generic[T]

Immutable MultiDict, using class:MultiDictProxy <multidict.MultiDictProxy>.

__init__(args: MultiMapping | Mapping[str, Any] | Iterable[tuple[str, Any]] | None = None) → None¶

Initialize ImmutableMultiDict from a MultiMapping`, Mapping or an iterable of tuples.

Parameters:: args¶ – Mapping-like structure to create the ImmutableMultiDict from

mutable_copy() → MultiDict[T]¶

Create a mutable copy as a MultiDict

Returns:: A mutable multi dict

copy() → Self¶: Return a shallow copy

class litestar.datastructures.ImmutableState¶

Bases: Mapping[str, Any]

An object meant to store arbitrary state.

It can be accessed using dot notation while exposing dict like functionalities.

__init__(state: ImmutableState | Mapping[str, Any] | Iterable[tuple[str, Any]], deep_copy: bool = True) → None¶

Initialize an ImmutableState instance.

Parameters:

state¶ – An object to initialize the state from. Can be a dict, an instance of ImmutableState, or a tuple of key value paris.
deep_copy¶ – Whether to ‘deepcopy’ the passed in state.

Examples

from litestar.datastructures import ImmutableState

state_dict = {"first": 1, "second": 2, "third": 3, "fourth": 4}
state = ImmutableState(state_dict)

# state implements the Mapping type:
assert len(state) == 3
assert "first" in state
assert not "fourth" in state
assert state["first"] == 1
assert [(k, v) for k, v in state.items()] == [("first", 1), ("second", 2), ("third", 3)]

# state implements __bool__
assert state  # state is true when it has values.
assert not State()  # state is empty when it has no values.

# it has a 'dict' method to retrieve a shallow copy of the underlying dict
inner_dict = state.dict()
assert inner_dict == state_dict

# you can also retrieve a mutable State by calling 'mutable_copy'
mutable_state = state.mutable_copy()
del state["first"]
assert "first" not in state

__bool__() → bool¶: Return a boolean indicating whether the wrapped dict instance has values.

__getitem__(key: str) → Any¶

Get the value for the corresponding key from the wrapped state object using subscription notation.

Parameters:: key¶ – Key to access.
Raises:: KeyError –
Returns:: A value from the wrapped state instance.

__iter__() → Iterator[str]¶

Return an iterator iterating the wrapped state dict.

Returns:: An iterator of strings

__len__() → int¶

Return length of the wrapped state dict.

Returns:: An integer

__getattr__(key: str) → Any¶

Get the value for the corresponding key from the wrapped state object using attribute notation.

Parameters:: key¶ – Key to retrieve
Raises:: AttributeError – if the given attribute is not set.
Returns:: The retrieved value

__copy__() → Self¶

Return a shallow copy of the given state object.

Customizes how the builtin “copy” function will work.

mutable_copy() → State¶

Return a mutable copy of the state object.

Returns:: A State

dict() → dict[str, Any]¶

Return a shallow copy of the wrapped dict.

Returns:: A dict

classmethod __get_validators__() → Generator[Callable[[ImmutableState | dict[str, Any] | Iterable[tuple[str, Any]]], ImmutableState], None, None]¶: Pydantic compatible method to allow custom parsing of state instances in a SignatureModel.

classmethod validate(value: ImmutableState | dict[str, Any] | Iterable[tuple[str, Any]]) → Self¶

Parse a value and instantiate state inside a SignatureModel. This allows us to use custom subclasses of state, as well as allows users to decide whether state is mutable or immutable.

Parameters:: value¶ – The value from which to initialize the state instance.
Returns:: An ImmutableState instance

class litestar.datastructures.MultiDict¶

Bases: MultiDict[T], MultiMixin[T], Generic[T]

MultiDict, using MultiDict.

__init__(args: MultiMapping | Mapping[str, T] | Iterable[tuple[str, T]] | None = None) → None¶

Initialize MultiDict from a`MultiMapping``, Mapping or an iterable of tuples.

Parameters:: args¶ – Mapping-like structure to create the MultiDict from

immutable() → ImmutableMultiDict[T]¶

Create an.

ImmutableMultiDict view.

Returns:: An immutable multi dict

copy() → Self¶: Return a shallow copy

class litestar.datastructures.MultiMixin¶

Bases: Generic[T], MultiMapping[T], ABC

Mixin providing common methods for multi dicts, used by ImmutableMultiDict and MultiDict

dict() → dict[str, list[Any]]¶

Return the multi-dict as a dict of lists.

Returns:: A dict of lists

multi_items() → Generator[tuple[str, T], None, None]¶

Get all keys and values, including duplicates.

Returns:: A list of tuples containing key-value pairs

class litestar.datastructures.MutableScopeHeaders¶

Bases: MutableMapping

A case-insensitive, multidict-like structure that can be used to mutate headers within a Scope

__init__(scope: HeaderScope | None = None) → None¶

Initialize MutableScopeHeaders from a HeaderScope.

Parameters:: scope¶ – The ASGI connection scope.

classmethod from_message(message: Message) → MutableScopeHeaders¶

Construct a header from a message object.

Parameters:: message¶ – Message.
Returns:: MutableScopeHeaders.
Raises:: ValueError – If the message does not have a headers key.

add(key: str, value: str) → None¶

Add a header to the scope.

Notes

This method keeps duplicates.

Parameters:

key¶ – Header key.
value¶ – Header value.

Returns:

None.

getall(key: str, default: list[str] | None = None) → list[str]¶

Get all values of a header.

Parameters:

key¶ – Header key.
default¶ – Default value to return if name is not found.

Returns:

A list of strings.

Raises:

KeyError – if no header for name was found and default is not given.

extend_header_value(key: str, value: str) → None¶

Extend a multivalued header.

Notes

A multivalues header is a header that can take a comma separated list.
If the header previously did not exist, it will be added.

Parameters:

key¶ – Header key.
value¶ – Header value to add,

Returns:

None

__getitem__(key: str) → str¶: Get the first header matching name

__setitem__(key: str, value: str) → None¶: Set a header in the scope, overwriting duplicates.

__delitem__(key: str) → None¶: Delete all headers matching name

__len__() → int¶: Return the length of the internally stored headers, including duplicates.

__iter__() → Iterator[str]¶: Create an iterator of header names including duplicates.

class litestar.datastructures.ResponseHeader¶

Bases: object

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 = None¶

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.

__init__(name: str, documentation_only: bool = False, value: str | None = None, description: str | None = None, required: bool = False, deprecated: bool = False, allow_empty_value: bool = None, style: str | None = None, explode: bool | None = None, allow_reserved: bool = None, example: Any | None = None, examples: dict[str, Example] | None = None) → None¶

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¶

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.

__post_init__() → None¶: Ensure that either value is set or the instance is for documentation_only.

class litestar.datastructures.SecretBytes¶

Bases: SecretValue[bytes]

Represents a secret bytes value.

get_obscured() → bytes¶

Overrides the base class method to return the hidden bytes value.

Returns:: The hidden bytes representation of the secret value.
Return type:: bytes

class litestar.datastructures.SecretString¶

Bases: SecretValue[str]

Represents a secret string value.

get_obscured() → str¶

Overrides the base class method to return the hidden string value.

Returns:: The hidden string representation of the secret value.
Return type:: str

class litestar.datastructures.State¶

Bases: ImmutableState, MutableMapping[str, Any]

An object meant to store arbitrary state.

It can be accessed using dot notation while exposing dict like functionalities.

__init__(state: ImmutableState | Mapping[str, Any] | Iterable[tuple[str, Any]] | None = None, deep_copy: bool = False) → None¶

Initialize a State instance with an optional value.

Parameters:

state¶ – An object to initialize the state from. Can be a dict, an instance of ‘ImmutableState’, or a tuple of key value paris.
deep_copy¶ – Whether to ‘deepcopy’ the passed in state.

Examples¶

from litestar.datastructures import State

state_dict = {"first": 1, "second": 2, "third": 3, "fourth": 4}
state = State(state_dict)

# state can be accessed using '.' notation
assert state.fourth == 4
del state.fourth

# state implements the Mapping type:
assert len(state) == 3
assert "first" in state
assert not "fourth" in state
assert state["first"] == 1
assert [(k, v) for k, v in state.items()] == [("first", 1), ("second", 2), ("third", 3)]

state["fourth"] = 4
assert "fourth" in state
del state["fourth"]

# state implements __bool__
assert state  # state is true when it has values.
assert not State()  # state is empty when it has no values.

# it has shallow copy
copied_state = state.copy()
del copied_state.first
assert state.first

# it has a 'dict' method to retrieve a shallow copy of the underlying dict
inner_dict = state.dict()
assert inner_dict == state_dict

# you can get an immutable copy of the state by calling 'immutable_immutable_copy'
immutable_copy = state.immutable_copy()
del immutable_copy.first  #  raises AttributeError

__delitem__(key: str) → None¶

Delete the value from the key from the wrapped state object using subscription notation.

Parameters:: key¶ – Key to delete
Raises:: KeyError – if the given attribute is not set.
Returns:: None

__setitem__(key: str, value: Any) → None¶

Set an item in the state using subscription notation.

Parameters:

key¶ – Key to set.
value¶ – Value to set.

Returns:

None

__setattr__(key: str, value: Any) → None¶

Set an item in the state using attribute notation.

Parameters:

key¶ – Key to set.
value¶ – Value to set.

Returns:

None

__delattr__(key: str) → None¶

Delete the value from the key from the wrapped state object using attribute notation.

Parameters:: key¶ – Key to delete
Raises:: AttributeError – if the given attribute is not set.
Returns:: None

copy() → Self¶

Return a shallow copy of the state object.

Returns:: A State

immutable_copy() → ImmutableState¶

Return a shallow copy of the state object, setting it to be frozen.

Returns:: A State

class litestar.datastructures.UploadFile¶

Bases: object

Representation of a file upload

__init__(content_type: str, filename: str, file_data: bytes | None = None, headers: dict[str, str] | None = None, max_spool_size: int = 1048576) → None¶

Upload file in-memory container.

Parameters:

content_type¶ – Content type for the file.
filename¶ – The filename.
file_data¶ – File data.
headers¶ – Any attached headers.
max_spool_size¶ – The size above which the temporary file will be rolled to disk.

property rolled_to_disk: bool¶

Determine whether the spooled file exceeded the rolled-to-disk threshold and is no longer in memory.

Returns:: A boolean flag

async write(data: bytes | bytearray) → int¶

Proxy for data writing.

Parameters:: data¶ – Byte string to write.
Returns:: None

async read(size: int = -1) → bytes¶

Proxy for data reading.

Parameters:: size¶ – position from which to read.
Returns:: Byte string.

async seek(offset: int) → int¶

Async proxy for file seek.

Parameters:: offset¶ – start position..
Returns:: None.

async close() → None¶

Async proxy for file close.

Returns:: None.

secret_values