Table of Contents
AcceptListsanic.headersMatchedsanic.headersMediaTypesanic.headersformat_http1_responsesanic.headersfwd_normalizesanic.headersfwd_normalize_addresssanic.headersparse_acceptsanic.headersparse_content_headersanic.headersparse_credentialssanic.headersparse_forwardedsanic.headersparse_hostsanic.headersparse_xforwardedsanic.headerssanic.headers.AcceptList#
A list of media types, as used in the Accept header.
class AcceptList(iterable = ())
The Accept header entries are listed in order of preference, starting
with the most preferred. This class is a list of MediaType
objects,
that encapsulate also the q value or any other parameters.
Two separate methods are provided for searching the list:
- 'match' for finding the most preferred match (wildcards supported)
- operator 'in' for checking explicit matches (wildcards as literals)
Parameters
- *args
MediaType Any number of MediaType objects.
match#
Find a media type accepted by the client.
def match(self, mimes: str, accept_wildcards = True): -> Matched
This method can be used to find which of the media types requested by the client is most preferred against the ones given as arguments.
The ordering of preference is set by:
- The order set by RFC 7231, s. 5.3.2, giving a higher priority to q values and more specific type definitions,
- The order of the arguments (first is most preferred), and
- The first matching entry on the Accept header.
Wildcards are matched both ways. A match is usually found, as the
Accept headers typically include */*
, in particular if the header
is missing, is not manually set, or if the client is a browser.
Note: the returned object behaves as a string of the mime argument
that matched, and is empty/falsy if no match was found. The matched
header entry MediaType
or None
is available as the m
attribute.
Parameters
- mimes
List[str] Any MIME types to search for in order of preference.
- accept_wildcards
bool Match Accept entries with wildcards in them.
Return
- Match
A match object with the mime string and the MediaType object.
sanic.headers.Matched#
A matching result of a MIME string against a header.
class Matched(mime: str, header: Optional[MediaType])
This class is a representation of a matching result of a MIME string against a header. It encapsulates the MIME string, the header, and provides methods for matching against other MIME strings.
Parameters
- mime
str The MIME string to match.
- header
MediaType The header to match against, if any.
match#
Match this MIME string against another MIME string.
def match(self, other: Union[str, Matched]): -> Optional[Matched]
Check if this MIME string matches the given MIME string. Wildcards are supported both ways on both type and subtype.
Parameters
- other
str A MIME string to match.
Return
- Matched
Returns
self
if the MIME strings are compatible. None: ReturnsNone
if the MIME strings are not compatible.
parse#
@classmethod
def parse(raw: str): -> Matched
sanic.headers.MediaType#
A media type, as used in the Accept header.
class MediaType(type_: str, subtype: str, params: str)
This class is a representation of a media type, as used in the Accept header. It encapsulates the type, subtype and any parameters, and provides methods for matching against other media types.
Two separate methods are provided for searching the list:
- 'match' for finding the most preferred match (wildcards supported)
- operator 'in' for checking explicit matches (wildcards as literals)
Parameters
- type_
str The type of the media type.
- subtype
str The subtype of the media type.
- **params
str Any parameters for the media type.
has_wildcard#
Return True if this media type has a wildcard in it.
@property
def has_wildcard(self): -> bool
Return
- bool
True if this media type has a wildcard in it.
match#
Match this media type against another media type.
def match(self, mime_with_params: Union[str, MediaType]): -> Optional[MediaType]
Check if this media type matches the given mime type/subtype. Wildcards are supported both ways on both type and subtype. If mime contains a semicolon, optionally followed by parameters, the parameters of the two media types must match exactly.
Note
Use the ==
operator instead to check for literal matches
without expanding wildcards.
Parameters
- media_type
str A type/subtype string to match.
Return
- MediaType
Returns
self
if the media types are compatible. None: ReturnsNone
if the media types are not compatible.
sanic.headers.format_http1_response#
Format a HTTP/1.1 response header.
def format_http1_response(status: int, headers: HeaderBytesIterable): -> bytes
Parameters
- status
int The HTTP status code.
- headers
HeaderBytesIterable An iterable of header tuples.
Return
- bytes
The formatted response header.
sanic.headers.fwd_normalize#
Normalize and convert values extracted from forwarded headers.
def fwd_normalize(fwd: OptionsIterable): -> Options
Parameters
- fwd
OptionsIterable An iterable of key-value pairs.
Return
- Options
A dict of normalized key-value pairs.
sanic.headers.fwd_normalize_address#
Normalize address fields of proxy headers.
def fwd_normalize_address(addr: str): -> str
Parameters
- addr
str An address string.
Return
- str
A normalized address string.
sanic.headers.parse_accept#
Parse an Accept header and order the acceptable media types according to RFC 7231, s. 5.3.2
def parse_accept(accept: Optional[str]): -> AcceptList
https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.2
Parameters
- accept
str The Accept header value to parse.
Return
- AcceptList
A list of MediaType objects, ordered by preference.
Raises
- InvalidHeader
If the header value is invalid.
sanic.headers.parse_content_header#
Parse content-type and content-disposition header values.
def parse_content_header(value: str): -> Tuple[str, Options]
E.g. form-data; name=upload; filename="file.txt"
to
('form-data', {'name': 'upload', 'filename': 'file.txt'})
Mostly identical to cgi.parse_header and werkzeug.parse_options_header
but runs faster and handles special characters better.
Unescapes %22 to `"` and %0D%0A to `
` in field values.
Args:
value (str): The header value to parse.
Returns:
Tuple[str, Options]: The header value and a dict of options.
sanic.headers.parse_credentials#
Parses any header with the aim to retrieve any credentials from it.
def parse_credentials(header: Optional[str], prefixes: Optional[Union[List, Tuple, Set]] = None): -> Tuple[Optional[str], Optional[str]]
Parameters
- header
Optional[str] The header to parse.
- prefixes
Optional[Union[List, Tuple, Set]] The prefixes to look for. Defaults to None.
Return
- Tuple[Optional[str], Optional[str]]
The prefix and the credentials.
sanic.headers.parse_forwarded#
Parse RFC 7239 Forwarded headers.
def parse_forwarded(headers, config): -> Optional[Options]
The value of by
or secret
must match config.FORWARDED_SECRET
sanic.headers.parse_host#
Split host:port into hostname and port.
def parse_host(host: str): -> Tuple[Optional[str], Optional[int]]
Parameters
- host
str A host string.
Return
- Tuple[Optional[str], Optional[int]]
A tuple of hostname and port.
sanic.headers.parse_xforwarded#
Parse traditional proxy headers.
def parse_xforwarded(headers, config): -> Optional[Options]