Soup.MessageHeaders¶

Fields¶

None

Methods¶

class	`new` (type)
	`append` (name, value)
	`clean_connection_headers` ()
	`clear` ()
	`foreach` (func, *user_data)
	`free` ()
	`free_ranges` (ranges)
	`get` (name)
	`get_content_disposition` ()
	`get_content_length` ()
	`get_content_range` ()
	`get_content_type` ()
	`get_encoding` ()
	`get_expectations` ()
	`get_headers_type` ()
	`get_list` (name)
	`get_one` (name)
	`get_ranges` (total_length)
	`header_contains` (name, token)
	`header_equals` (name, value)
	`remove` (name)
	`replace` (name, value)
	`set_content_disposition` (disposition, params)
	`set_content_length` (content_length)
	`set_content_range` (start, end, total_length)
	`set_content_type` (content_type, params)
	`set_encoding` (encoding)
	`set_expectations` (expectations)
	`set_range` (start, end)
	`set_ranges` (ranges, length)

Details¶

class Soup.MessageHeaders¶

The HTTP message headers associated with a request or response.

classmethod new(type)¶

Parameters:: type (Soup.MessageHeadersType) – the type of headers
Returns:: a new Soup.MessageHeaders
Return type:: Soup.MessageHeaders

Creates a Soup.MessageHeaders. (Soup.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.)

append(name, value)¶

Parameters:

name (str) – the header name to add
value (str) – the new value of name

Appends a new header with name name and value value to self. (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 Soup.MessageHeaders.replace().)

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

clean_connection_headers()¶: Removes all the headers listed in the Connection header.

New in version 2.36.

clear()¶: Clears self.

foreach(func, *user_data)¶

Parameters:

func (Soup.MessageHeadersForeachFunc) – callback function to run for each header
user_data (object or None) – data to pass to func

Calls func once for each header value in self.

Beware that unlike Soup.MessageHeaders.get(), 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 Soup.MessageHeaders.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.

free()¶: Frees self.

free_ranges(ranges)¶

Parameters:: ranges (Soup.Range) – an array of Soup.Range

Frees the array of ranges returned from Soup.MessageHeaders.get_ranges().

New in version 2.26.

get(name)¶

Parameters:: name (str) – header name
Returns:: as with Soup.MessageHeaders.get_list().
Return type:: str or None

Gets the value of header name in self.

This method was supposed to work correctly for both single-valued and list-valued headers, but because some HTTP clients/servers mistakenly send multiple copies of headers that are supposed to be single-valued, it sometimes returns incorrect results. To fix this, the methods Soup.MessageHeaders.get_one() and Soup.MessageHeaders.get_list() were introduced, so callers can explicitly state which behavior they are expecting.

Deprecated since version ???: Use Soup.MessageHeaders.get_one() or Soup.MessageHeaders.get_list() instead.

get_content_disposition()¶

Returns:

True if self contains a “Content-Disposition” header, False if not (in which case disposition and params will be unchanged).

disposition:: return location for the disposition-type, or None
params:: return location for the Content-Disposition parameters, or None

Return type:

(bool, disposition: str, params: {str: str})

Looks up the “Content-Disposition” header in self, 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 Soup.Multipart and the associated form methods.

New in version 2.26.

get_content_length()¶

Returns:: the message body length declared by self.
Return type:: int

Gets the message body length that self declare. This will only be non-0 if Soup.MessageHeaders.get_encoding() returns Soup.Encoding.CONTENT_LENGTH.

get_content_range()¶

Returns:

True if self contained a “Content-Range” header containing a byte range which could be parsed, False otherwise.

start:: return value for the start of the range
end:: return value for the end of the range
total_length:: return value for the total length of the resource, or None if you don’t care.

Return type:

(bool, start: int, end: int, total_length: int)

Parses self'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.

New in version 2.26.

get_content_type()¶

Returns:

a string with the value of the “Content-Type” header or None if self does not contain that header or it cannot be parsed (in which case params will be unchanged).

params:: return location for the Content-Type parameters (eg, “charset”), or None

Return type:

(str or None, params: {str: str})

Looks up the “Content-Type” header in self, 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.

New in version 2.26.

get_encoding()¶

Returns:: the encoding declared by self.
Return type:: Soup.Encoding

Gets the message body encoding that self 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()¶

Returns:: the contents of self's “Expect” header
Return type:: Soup.Expectation

Gets the expectations declared by self's “Expect” header. Currently this will either be Soup.Expectation.CONTINUE or Soup.Expectation.UNRECOGNIZED.

get_headers_type()¶

Returns:: the header’s type.
Return type:: Soup.MessageHeadersType

Gets the type of headers.

New in version 2.50.

get_list(name)¶

Parameters:: name (str) – header name
Returns:: the header’s value or None if not found.
Return type:: str or None

Gets the value of header name in self. 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 Soup.MessageHeaders.get_one().

If name appears multiple times in self, Soup.MessageHeaders.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.

New in version 2.28.

get_one(name)¶

Parameters:: name (str) – header name
Returns:: the header’s value or None if not found.
Return type:: str or None

Gets the value of header name in self. 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 Soup.MessageHeaders.get_list().

If self 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.)

New in version 2.28.

get_ranges(total_length)¶

Parameters:

total_length (int) – the total_length of the response body

Returns:

True if self contained a syntactically-valid “Range” header, False otherwise (in which case range and length will not be set).

ranges:: return location for an array of Soup.Range

Return type:

(bool, ranges: [Soup.Range])

Parses self's Range header and returns an array of the requested byte ranges. The returned array must be freed with Soup.MessageHeaders.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 Soup.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.

Soup.Server has built-in handling for range requests. If your server handler returns a Soup.Status.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 Soup.Status.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.

New in version 2.26.

header_contains(name, token)¶

Parameters:

name (str) – header name
token (str) – token to look for

Returns:

True if the header is present and contains token, False otherwise.

Return type:

bool

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

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

New in version 2.50.

header_equals(name, value)¶

Parameters:

name (str) – header name
value (str) – expected value

Returns:

True if the header is present and its value is value, False otherwise.

Return type:

bool

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

New in version 2.50.

remove(name)¶

Parameters:: name (str) – the header name to remove

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

replace(name, value)¶

Parameters:

name (str) – the header name to replace
value (str) – the new value of name

Replaces the value of the header name in self with value. (See also Soup.MessageHeaders.append().)

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

set_content_disposition(disposition, params)¶

Parameters:

disposition (str) – the disposition-type
params ({str: str} or None) – additional parameters, or None

Sets the “Content-Disposition” header in self to disposition, optionally with additional parameters specified in params.

See Soup.MessageHeaders.get_content_disposition() for a discussion of how Content-Disposition is used in HTTP.

New in version 2.26.

set_content_length(content_length)¶

Parameters:: content_length (int) – the message body length

Sets the message body length that self will declare, and sets self's encoding to Soup.Encoding.CONTENT_LENGTH.

You do not normally need to call this; if self is set to use Content-Length encoding, libsoup will automatically set its Content-Length header for you immediately before sending the headers. One situation in which this method is useful is when generating the response to a HEAD request; Calling Soup.MessageHeaders.set_content_length() allows you to put the correct content length into the response without needing to waste memory by filling in a response body which won’t actually be sent.

set_content_range(start, end, total_length)¶

Parameters:

start (int) – the start of the range
end (int) – the end of the range
total_length (int) – the total length of the resource, or -1 if unknown

Sets self's Content-Range header according to the given values. (Note that total_length is the total length of the entire resource that this is a range of, not simply end - start + 1.)

Soup.Server has built-in handling for range requests, and you do not normally need to call this function youself. See Soup.MessageHeaders.get_ranges() for more details.

New in version 2.26.

set_content_type(content_type, params)¶

Parameters:

content_type (str) – the MIME type
params ({str: str} or None) – additional parameters, or None

Sets the “Content-Type” header in self to content_type, optionally with additional parameters specified in params.

New in version 2.26.

set_encoding(encoding)¶

Parameters:: encoding (Soup.Encoding) – a Soup.Encoding

Sets the message body encoding that self will declare. In particular, you should use this if you are going to send a request or response in chunked encoding.

set_expectations(expectations)¶

Parameters:: expectations (Soup.Expectation) – the expectations to set

Sets self's “Expect” header according to expectations.

Currently Soup.Expectation.CONTINUE is the only known expectation value. You should set this value on a request if you are sending a large message body (eg, via POST or PUT), and want to give the server a chance to reject the request after seeing just the headers (eg, because it will require authentication before allowing you to post, or because you’re POSTing to a URL that doesn’t exist). This saves you from having to transmit the large request body when the server is just going to ignore it anyway.

set_range(start, end)¶

Parameters:

start (int) – the start of the range to request
end (int) – the end of the range to request

Sets self's Range header to request the indicated range. start and end are interpreted as in a Soup.Range.

If you need to request multiple ranges, use Soup.MessageHeaders.set_ranges().

New in version 2.26.

set_ranges(ranges, length)¶

Parameters:

ranges (Soup.Range) – an array of Soup.Range
length (int) – the length of range

Sets self's Range header to request the indicated ranges. (If you only want to request a single range, you can use Soup.MessageHeaders.set_range().)

New in version 2.26.