MessageHeaders

class MessageHeaders(**kwargs)

The HTTP message headers associated with a request or response.

Constructors

class MessageHeaders

classmethod new(type: MessageHeadersType) → MessageHeaders

Creates a MessageHeaders.

(Message does this automatically for its own headers. You would only need to use this method if you are manually parsing or generating message headers.)

Parameters:: type – the type of headers

Methods

class MessageHeaders

append(name: str, value: str) → None

Appends a new header with name name and value value to hdrs.

(If there is an existing header with name name, then this creates a second one, which is only allowed for list-valued headers; see also replace.)

The caller is expected to make sure that name and value are syntactically correct.

Parameters:

name – the header name to add
value – the new value of name

clean_connection_headers() → None: Removes all the headers listed in the Connection header.

clear() → None: Clears hdrs.

foreach(func: Callable[[...], None], *user_data: Any) → None

Calls func once for each header value in hdrs.

Beware that unlike get_list, this processes the headers in exactly the way they were added, rather than concatenating multiple same-named headers into a single value. (This is intentional; it ensures that if you call append multiple times with the same name, then the I/O code will output multiple copies of the header when sending the message to the remote implementation, which may be required for interoperability in some cases.)

You may not modify the headers from func.

Parameters:

func – callback function to run for each header
user_data – data to pass to func

free_ranges(ranges: Range) → None

Frees the array of ranges returned from get_ranges.

Parameters:: ranges – an array of Range

get_content_disposition() → tuple[bool, str, dict[str, str]]

Looks up the “Content-Disposition” header in hdrs, parses it, and returns its value in *disposition and *params.

params can be None if you are only interested in the disposition-type.

In HTTP, the most common use of this header is to set a disposition-type of “attachment”, to suggest to the browser that a response should be saved to disk rather than displayed in the browser. If params contains a “filename” parameter, this is a suggestion of a filename to use. (If the parameter value in the header contains an absolute or relative path, libsoup will truncate it down to just the final path component, so you do not need to test this yourself.)

Content-Disposition is also used in “multipart/form-data”, however this is handled automatically by Multipart and the associated form methods.

get_content_length() → int

Gets the message body length that hdrs declare.

This will only be non-0 if get_encoding returns CONTENT_LENGTH.

get_content_range() → tuple[bool, int, int, int]: Parses hdrs’s Content-Range header and returns it in start, end, and total_length. If the total length field in the header was specified as “*”, then total_length will be set to -1.

get_content_type() → tuple[str | None, dict[str, str]]

Looks up the “Content-Type” header in hdrs, parses it, and returns its value in *content_type and *params.

params can be None if you are only interested in the content type itself.

get_encoding() → Encoding

Gets the message body encoding that hdrs declare.

This may not always correspond to the encoding used on the wire; eg, a HEAD response may declare a Content-Length or Transfer-Encoding, but it will never actually include a body.

get_expectations() → Expectation

Gets the expectations declared by hdrs’s “Expect” header.

Currently this will either be CONTINUE or UNRECOGNIZED.

get_headers_type() → MessageHeadersType: Gets the type of headers.

get_list(name: str) → str | None

Gets the value of header name in hdrs.

Use this for headers whose values are comma-delimited lists, and which are therefore allowed to appear multiple times in the headers. For non-list-valued headers, use get_one.

If name appears multiple times in hdrs, get_list will concatenate all of the values together, separated by commas. This is sometimes awkward to parse (eg, WWW-Authenticate, Set-Cookie), but you have to be able to deal with it anyway, because the HTTP spec explicitly states that this transformation is allowed, and so an upstream proxy could do the same thing.

Parameters:: name – header name

get_one(name: str) → str | None

Gets the value of header name in hdrs.

Use this for headers whose values are not comma-delimited lists, and which therefore can only appear at most once in the headers. For list-valued headers, use get_list.

If hdrs does erroneously contain multiple copies of the header, it is not defined which one will be returned. (Ideally, it will return whichever one makes libsoup most compatible with other HTTP implementations.)

Parameters:: name – header name

get_ranges(total_length: int) → tuple[bool, list[Range]]

Parses hdrs’s Range header and returns an array of the requested byte ranges.

The returned array must be freed with free_ranges.

If total_length is non-0, its value will be used to adjust the returned ranges to have explicit start and end values, and the returned ranges will be sorted and non-overlapping. If total_length is 0, then some ranges may have an end value of -1, as described under Range, and some of the ranges may be redundant.

Beware that even if given a total_length, this function does not check that the ranges are satisfiable.

Server has built-in handling for range requests. If your server handler returns a OK response containing the complete response body (rather than pausing the message and returning some of the response body later), and there is a Range header in the request, then libsoup will automatically convert the response to a PARTIAL_CONTENT response containing only the range(s) requested by the client.

The only time you need to process the Range header yourself is if either you need to stream the response body rather than returning it all at once, or you do not already have the complete response body available, and only want to generate the parts that were actually requested by the client.

Parameters:: total_length – the total_length of the response body

header_contains(name: str, token: str) → bool

Checks whether the list-valued header name is present in hdrs, and contains a case-insensitive match for token.

(If name is present in hdrs, then this is equivalent to calling header_contains on its value.)

Parameters:

name – header name
token – token to look for

Returns:

whether or not header contains token

header_equals(name: str, value: str) → bool

Checks whether the header name is present in hdrs and is (case-insensitively) equal to value.

Parameters:

name – header name
value – expected value

remove(name: str) → None

Removes name from hdrs.

If there are multiple values for name, they are all removed.

Parameters:: name – the header name to remove

replace(name: str, value: str) → None

Replaces the value of the header name in hdrs with value.