:right-sidebar: True MessageHeaders =================================================================== .. currentmodule:: gi.repository.Soup .. class:: MessageHeaders(**kwargs) :no-contents-entry: The HTTP message headers associated with a request or response. Constructors ------------ .. rst-class:: interim-class .. class:: MessageHeaders :no-index: .. classmethod:: new(type: ~gi.repository.Soup.MessageHeadersType) -> ~gi.repository.Soup.MessageHeaders Creates a :obj:`~gi.repository.Soup.MessageHeaders`\. (:obj:`~gi.repository.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.) :param type: the type of headers Methods ------- .. rst-class:: interim-class .. class:: MessageHeaders :no-index: .. method:: 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 :obj:`~gi.repository.MessageHeaders.replace`\.) The caller is expected to make sure that ``name`` and ``value`` are syntactically correct. :param name: the header name to add :param value: the new value of ``name`` .. method:: clean_connection_headers() -> None Removes all the headers listed in the Connection header. .. method:: clear() -> None Clears ``hdrs``\. .. method:: foreach(func: ~typing.Callable[[str, str, ~typing.Any], None], user_data: ~typing.Any = None) -> None Calls ``func`` once for each header value in ``hdrs``\. Beware that unlike :obj:`~gi.repository.MessageHeaders.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 :obj:`~gi.repository.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``\. :param func: callback function to run for each header :param user_data: data to pass to ``func`` .. method:: free_ranges(ranges: ~gi.repository.Soup.Range) -> None Frees the array of ranges returned from :obj:`~gi.repository.MessageHeaders.get_ranges`\. :param ranges: an array of :obj:`~gi.repository.Soup.Range` .. method:: get_content_disposition() -> ~typing.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 :const:`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 :obj:`~gi.repository.Soup.Multipart` and the associated form methods. .. method:: get_content_length() -> int Gets the message body length that ``hdrs`` declare. This will only be non-0 if :obj:`~gi.repository.MessageHeaders.get_encoding` returns :const:`~gi.repository.Soup.Encoding.CONTENT_LENGTH`. .. method:: get_content_range() -> ~typing.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. .. method:: get_content_type() -> ~typing.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 :const:`None` if you are only interested in the content type itself. .. method:: get_encoding() -> ~gi.repository.Soup.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. .. method:: get_expectations() -> ~gi.repository.Soup.Expectation Gets the expectations declared by ``hdrs``\'s "Expect" header. Currently this will either be :const:`~gi.repository.Soup.Expectation.CONTINUE` or :const:`~gi.repository.Soup.Expectation.UNRECOGNIZED`. .. method:: get_headers_type() -> ~gi.repository.Soup.MessageHeadersType Gets the type of headers. .. method:: 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 :obj:`~gi.repository.MessageHeaders.get_one`\. If ``name`` appears multiple times in ``hdrs``\, :obj:`~gi.repository.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. :param name: header name .. method:: 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 :obj:`~gi.repository.MessageHeaders.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.) :param name: header name .. method:: get_ranges(total_length: int) -> ~typing.Tuple[bool, list[~gi.repository.Soup.Range]] Parses ``hdrs``\'s Range header and returns an array of the requested byte ranges. The returned array must be freed with :obj:`~gi.repository.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 :obj:`~gi.repository.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. :obj:`~gi.repository.Soup.Server` has built-in handling for range requests. If your server handler returns a :const:`~gi.repository.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 :const:`~gi.repository.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. :param total_length: the total_length of the response body .. method:: 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 :obj:`~gi.repository.Soup.header_contains` on its value.) :param name: header name :param token: token to look for :return: whether or not ``header`` contains ``token`` .. method:: header_equals(name: str, value: str) -> bool Checks whether the header ``name`` is present in ``hdrs`` and is (case-insensitively) equal to ``value``\. :param name: header name :param value: expected value .. method:: remove(name: str) -> None Removes ``name`` from ``hdrs``\. If there are multiple values for ``name``\, they are all removed. :param name: the header name to remove .. method:: replace(name: str, value: str) -> None Replaces the value of the header ``name`` in ``hdrs`` with ``value``\. See also :obj:`~gi.repository.MessageHeaders.append`\. The caller is expected to make sure that ``name`` and ``value`` are syntactically correct. :param name: the header name to replace :param value: the new value of ``name`` .. method:: set_content_disposition(disposition: str, params: dict[str, str] | None = None) -> None Sets the "Content-Disposition" header in ``hdrs`` to ``disposition``\, optionally with additional parameters specified in ``params``\. See :obj:`~gi.repository.MessageHeaders.get_content_disposition` for a discussion of how Content-Disposition is used in HTTP. :param disposition: the disposition-type :param params: additional parameters .. method:: set_content_length(content_length: int) -> None Sets the message body length that ``hdrs`` will declare, and sets ``hdrs``\'s encoding to :const:`~gi.repository.Soup.Encoding.CONTENT_LENGTH`. You do not normally need to call this; if ``hdrs`` 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 :obj:`~gi.repository.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. :param content_length: the message body length .. method:: set_content_range(start: int, end: int, total_length: int) -> None Sets ``hdrs``\'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.) :obj:`~gi.repository.Soup.Server` has built-in handling for range requests, and you do not normally need to call this function youself. See :obj:`~gi.repository.MessageHeaders.get_ranges` for more details. :param start: the start of the range :param end: the end of the range :param total_length: the total length of the resource, or -1 if unknown .. method:: set_content_type(content_type: str, params: dict[str, str] | None = None) -> None Sets the "Content-Type" header in ``hdrs`` to ``content_type``\. Accepts additional parameters specified in ``params``\. :param content_type: the MIME type :param params: additional parameters .. method:: set_encoding(encoding: ~gi.repository.Soup.Encoding) -> None Sets the message body encoding that ``hdrs`` will declare. In particular, you should use this if you are going to send a request or response in chunked encoding. :param encoding: a :obj:`~gi.repository.Soup.Encoding` .. method:: set_expectations(expectations: ~gi.repository.Soup.Expectation) -> None Sets ``hdrs``\'s "Expect" header according to ``expectations``\. Currently :const:`~gi.repository.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. :param expectations: the expectations to set .. method:: set_range(start: int, end: int) -> None Sets ``hdrs``\'s Range header to request the indicated range. ``start`` and ``end`` are interpreted as in a :obj:`~gi.repository.Soup.Range`\. If you need to request multiple ranges, use :obj:`~gi.repository.MessageHeaders.set_ranges`\. :param start: the start of the range to request :param end: the end of the range to request .. method:: set_ranges(ranges: ~gi.repository.Soup.Range, length: int) -> None Sets ``hdrs``\'s Range header to request the indicated ranges. If you only want to request a single range, you can use :obj:`~gi.repository.MessageHeaders.set_range`\. :param ranges: an array of :obj:`~gi.repository.Soup.Range` :param length: the length of ``range``