twisted.web.http

module documentation
(source)

HyperText Transfer Protocol implementation.

This is the basic server-side protocol implementation used by the Twisted Web server. It can parse HTTP 1.0 requests and supports many HTTP 1.1 features as well. Additionally, some functionality implemented here is also useful for HTTP clients (such as the chunked encoding parser).

Class HTTPChannel A receiver for HTTP requests.
Class HTTPClient A client for HTTP 1.0.
Class HTTPFactory Factory for HTTP server.
Class Request A HTTP request.
Class StringTransport I am a BytesIO wrapper that conforms for the transport API. I support the `writeSequence' method.
Exception PotentialDataLoss PotentialDataLoss may be raised by a transfer encoding decoder's noMoreData method to indicate that it cannot be determined if the entire response body has been delivered. This only occurs when making requests to HTTP servers which do not set ...
Function combinedLogFormatter No summary
Function datetimeToLogString Convert seconds since epoch to log datetime string.
Function datetimeToString Convert seconds since epoch to HTTP datetime string.
Function fromChunk Convert chunk to string.
Function parse_qs Like cgi.parse_qs, but with support for parsing byte strings on Python 3.
Function parseContentRange Parse a content-range header into (start, end, realLength).
Function proxiedLogFormatter No summary
Function stringToDatetime Convert an HTTP date string (one of three formats) to seconds since epoch.
Function timegm Convert time tuple in GMT to seconds since epoch, GMT
Function toChunk Convert string to a chunk.
Function urlparse Parse an URL into six components.
Constant ACCEPTED Undocumented
Constant BAD_GATEWAY Undocumented
Constant BAD_REQUEST Undocumented
Constant CACHED A marker value to be returned from cache-related request methods to indicate to the caller that a cached response will be usable and no response body should be generated.
Constant CONFLICT Undocumented
Constant CREATED Undocumented
Constant EXPECTATION_FAILED Undocumented
Constant FORBIDDEN Undocumented
Constant FOUND Undocumented
Constant GATEWAY_TIMEOUT Undocumented
Constant GONE Undocumented
Constant HTTP_VERSION_NOT_SUPPORTED Undocumented
Constant IM_A_TEAPOT Undocumented
Constant INSUFFICIENT_STORAGE_SPACE Undocumented
Constant INTERNAL_SERVER_ERROR Undocumented
Constant LENGTH_REQUIRED Undocumented
Constant MOVED_PERMANENTLY Undocumented
Constant MULTI_STATUS Undocumented
Constant MULTIPLE_CHOICE Undocumented
Constant NO_BODY_CODES Undocumented
Constant NO_CONTENT Undocumented
Constant NON_AUTHORITATIVE_INFORMATION Undocumented
Constant NOT_ACCEPTABLE Undocumented
Constant NOT_ALLOWED Undocumented
Constant NOT_EXTENDED Undocumented
Constant NOT_FOUND Undocumented
Constant NOT_IMPLEMENTED Undocumented
Constant NOT_MODIFIED Undocumented
Constant OK Undocumented
Constant PARTIAL_CONTENT Undocumented
Constant PAYMENT_REQUIRED Undocumented
Constant PERMANENT_REDIRECT Undocumented
Constant PRECONDITION_FAILED Undocumented
Constant PROXY_AUTH_REQUIRED Undocumented
Constant REQUEST_ENTITY_TOO_LARGE Undocumented
Constant REQUEST_TIMEOUT Undocumented
Constant REQUEST_URI_TOO_LONG Undocumented
Constant REQUESTED_RANGE_NOT_SATISFIABLE Undocumented
Constant RESET_CONTENT Undocumented
Constant RESPONSES Undocumented
Constant SEE_OTHER Undocumented
Constant SERVICE_UNAVAILABLE Undocumented
Constant SWITCHING Undocumented
Constant TEMPORARY_REDIRECT Undocumented
Constant UNAUTHORIZED Undocumented
Constant UNSUPPORTED_MEDIA_TYPE Undocumented
Constant USE_PROXY Undocumented
Variable H2_ENABLED Undocumented
Variable maxChunkSizeLineLength Maximum allowable length of the CRLF-terminated line that indicates the size of a chunk and the extensions associated with it, as in the HTTP 1.1 chunked Transfer-Encoding (RFC 7230 section 4.1). This limits how much data may be buffered when decoding the line.
Variable monthname Undocumented
Variable monthname_lower Undocumented
Variable protocol_version Undocumented
Variable weekdayname Undocumented
Variable weekdayname_lower Undocumented
Interface _IDeprecatedHTTPChannelToRequestInterface The interface HTTPChannel expects of Request.
Class _ChunkedTransferDecoder Protocol for decoding chunked Transfer-Encoding, as defined by RFC 7230, section 4.1. This protocol can interpret the contents of a request or response body which uses the chunked Transfer-Encoding. ...
Class _GenericHTTPChannelProtocol A proxy object that wraps one of the HTTP protocol objects, and switches between them depending on TLS negotiated protocol.
Class _IdentityTransferDecoder Protocol for accumulating bytes up to a specified length. This handles the case where no Transfer-Encoding is specified.
Class _MinimalLogFile No class docstring; 2/2 methods documented
Class _NoPushProducer A no-op version of interfaces.IPushProducer, used to abstract over the possibility that a HTTPChannel transport does not provide IPushProducer.
Class _XForwardedForAddress IAddress which represents the client IP to log for a request, as gleaned from an X-Forwarded-For header.
Class _XForwardedForRequest Add a layer on top of another request that only uses the value of an X-Forwarded-For header as the result of getClientAddress.
Exception _DataLoss _DataLoss indicates that not all of a message body was received. This is only one of several possible exceptions which may indicate that data was lost. Because of this, it should not be checked for by specifically; any unexpected exception should be treated as having caused data loss.
Exception _MalformedChunkedDataError _ChunkedTransferDecoder raises _MalformedChunkedDataError from its dataReceived method when it encounters malformed data. This exception indicates a client-side error. If this exception is raised, the connection should be dropped with a 400 error.
Exception _MultiPartParseException Failed to parse the multipart/form-data payload.
Function _escape Return a string like python repr, but always escaped as if surrounding quotes were double quotes.
Function _genericHTTPChannelProtocolFactory Returns an appropriately initialized _GenericHTTPChannelProtocol.
Function _getContentFile Get a writeable file-like object to which request content can be written.
Function _getMultiPartArgs Parse the content of a multipart/form-data request.
Function _parseContentType Parse the Content-Type header.
Function _parseRequestLine Parse an HTTP request line, which looks like:
Constant _QUEUED_SENTINEL Undocumented
Constant _REQUEST_TIMEOUT Undocumented
Variable _chunkExtChars Characters that are valid in a chunk extension.
Variable _hostHeaderExpression Undocumented
Variable _monthnameBytes Undocumented
Variable _months Undocumented
Variable _weekdaynameBytes Undocumented
@provider(IAccessLogFormatter)
def combinedLogFormatter(timestamp, request): (source)
Returns
A combined log formatted log line for the given request.
See Also
IAccessLogFormatter
def datetimeToLogString(msSinceEpoch=None): (source)

Convert seconds since epoch to log datetime string.

Returns
strUndocumented
def datetimeToString(msSinceEpoch=None): (source)

Convert seconds since epoch to HTTP datetime string.

Returns
bytesUndocumented
def fromChunk(data: bytes) -> tuple[bytes, bytes]: (source)

Convert chunk to string.

Note that this function is not specification compliant: it doesn't handle chunk extensions.

Parameters
data:bytesUndocumented
Returns
tuple[bytes, bytes]tuple of (result, remaining) - both bytes.
Raises
ValueErrorIf the given data is not a correctly formatted chunked byte string.
def parse_qs(qs, keep_blank_values=0, strict_parsing=0): (source)

Like cgi.parse_qs, but with support for parsing byte strings on Python 3.

This was created to help with Python 2 to Python 3 migration. Consider using urllib.parse.parse_qs.

Parameters
qs:bytesUndocumented
keep_blank_valuesUndocumented
strict_parsingUndocumented
def parseContentRange(header): (source)

Parse a content-range header into (start, end, realLength).

realLength might be None if real length is not known ('*').

@provider(IAccessLogFormatter)
def proxiedLogFormatter(timestamp, request): (source)
Returns
A combined log formatted log line for the given request but use the value of the X-Forwarded-For header as the value for the client IP address.
See Also
IAccessLogFormatter
def stringToDatetime(dateString): (source)

Convert an HTTP date string (one of three formats) to seconds since epoch.

Parameters
dateString:bytesUndocumented
def timegm(year, month, day, hour, minute, second): (source)

Convert time tuple in GMT to seconds since epoch, GMT

def toChunk(data): (source)

Convert string to a chunk.

Parameters
data:bytesUndocumented
Returns
a tuple of bytes representing the chunked encoding of data
def urlparse(url): (source)

Parse an URL into six components.

This is similar to urlparse.urlparse, but rejects str input and always produces bytes output.

Parameters
url:bytesUndocumented
Returns
ParseResultBytesThe scheme, net location, path, params, query string, and fragment of the URL - all as bytes.
Raises
TypeErrorThe given url was a str string instead of a bytes.
ACCEPTED: int = (source)

Undocumented

Value
202
BAD_GATEWAY: int = (source)

Undocumented

Value
502
BAD_REQUEST: int = (source)

Undocumented

Value
400
CACHED: str = (source)

A marker value to be returned from cache-related request methods to indicate to the caller that a cached response will be usable and no response body should be generated.

Value
'''Magic constant returned by http.Request methods to set cache
validation headers when the request is conditional and the value fails
the condition.'''
CONFLICT: int = (source)

Undocumented

Value
409
CREATED: int = (source)

Undocumented

Value
201
EXPECTATION_FAILED: int = (source)

Undocumented

Value
417
FORBIDDEN: int = (source)

Undocumented

Value
403
FOUND: int = (source)

Undocumented

Value
302
GATEWAY_TIMEOUT: int = (source)

Undocumented

Value
504
GONE: int = (source)

Undocumented

Value
410
HTTP_VERSION_NOT_SUPPORTED: int = (source)

Undocumented

Value
505
IM_A_TEAPOT: int = (source)

Undocumented

Value
418
INSUFFICIENT_STORAGE_SPACE: int = (source)

Undocumented

Value
507
INTERNAL_SERVER_ERROR: int = (source)

Undocumented

Value
500
LENGTH_REQUIRED: int = (source)

Undocumented

Value
411
MOVED_PERMANENTLY: int = (source)

Undocumented

Value
301
MULTI_STATUS: int = (source)

Undocumented

Value
207
MULTIPLE_CHOICE: int = (source)

Undocumented

Value
300
NO_BODY_CODES: tuple[int, ...] = (source)

Undocumented

Value
(204, 304)
NO_CONTENT: int = (source)

Undocumented

Value
204
NON_AUTHORITATIVE_INFORMATION: int = (source)

Undocumented

Value
203
NOT_ACCEPTABLE: int = (source)

Undocumented

Value
406
NOT_ALLOWED: int = (source)

Undocumented

Value
405
NOT_EXTENDED: int = (source)

Undocumented

Value
510
NOT_FOUND: int = (source)

Undocumented

Value
404
NOT_IMPLEMENTED: int = (source)

Undocumented

Value
501
NOT_MODIFIED: int = (source)

Undocumented

Value
304
OK: int = (source)

Undocumented

Value
200
PARTIAL_CONTENT: int = (source)

Undocumented

Value
206
PAYMENT_REQUIRED: int = (source)

Undocumented

Value
402
PERMANENT_REDIRECT: int = (source)

Undocumented

Value
308
PRECONDITION_FAILED: int = (source)

Undocumented

Value
412
PROXY_AUTH_REQUIRED: int = (source)

Undocumented

Value
407
REQUEST_ENTITY_TOO_LARGE: int = (source)

Undocumented

Value
413
REQUEST_TIMEOUT: int = (source)

Undocumented

Value
408
REQUEST_URI_TOO_LONG: int = (source)

Undocumented

Value
414
REQUESTED_RANGE_NOT_SATISFIABLE: int = (source)

Undocumented

Value
416
RESET_CONTENT: int = (source)

Undocumented

Value
205
RESPONSES = (source)

Undocumented

Value
{_CONTINUE: b'Continue',
 SWITCHING: b'Switching Protocols',
 OK: b'OK',
 CREATED: b'Created',
 ACCEPTED: b'Accepted',
 NON_AUTHORITATIVE_INFORMATION: b'Non-Authoritative Information',
 NO_CONTENT: b'No Content',
...
SEE_OTHER: int = (source)

Undocumented

Value
303
SERVICE_UNAVAILABLE: int = (source)

Undocumented

Value
503
SWITCHING: int = (source)

Undocumented

Value
101
TEMPORARY_REDIRECT: int = (source)

Undocumented

Value
307
UNAUTHORIZED: int = (source)

Undocumented

Value
401
UNSUPPORTED_MEDIA_TYPE: int = (source)

Undocumented

Value
415
USE_PROXY: int = (source)

Undocumented

Value
305
H2_ENABLED: bool = (source)

Undocumented

maxChunkSizeLineLength: int = (source)

Maximum allowable length of the CRLF-terminated line that indicates the size of a chunk and the extensions associated with it, as in the HTTP 1.1 chunked Transfer-Encoding (RFC 7230 section 4.1). This limits how much data may be buffered when decoding the line.

monthname = (source)

Undocumented

monthname_lower = (source)

Undocumented

protocol_version: str = (source)

Undocumented

weekdayname: list[str] = (source)

Undocumented

weekdayname_lower = (source)

Undocumented

def _escape(s): (source)

Return a string like python repr, but always escaped as if surrounding quotes were double quotes.

Parameters
s:bytes or strThe string to escape.
Returns
strAn escaped string.
def _genericHTTPChannelProtocolFactory(self): (source)

Returns an appropriately initialized _GenericHTTPChannelProtocol.

def _getContentFile(length): (source)

Get a writeable file-like object to which request content can be written.

def _getMultiPartArgs(content: bytes, ctype: bytes) -> dict[bytes, list[bytes]]: (source)

Parse the content of a multipart/form-data request.

def _parseContentType(line: bytes) -> bytes: (source)

Parse the Content-Type header.

def _parseRequestLine(line: bytes) -> tuple[bytes, bytes, bytes]: (source)

Parse an HTTP request line, which looks like:

    GET /foo/bar HTTP/1.1

This function attempts to validate the well-formedness of the line. RFC 9112 section 3 provides this ABNF:

    request-line   = method SP request-target SP HTTP-version

We allow any method that is a valid token:

    method         = token
    token          = 1*tchar
    tchar          = "!" / "#" / "$" / "%" / "&" / "'" / "*"
                    / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
                    / DIGIT / ALPHA

We allow any non-empty request-target that contains only printable ASCII characters (no whitespace).

The RFC defines HTTP-version like this:

    HTTP-version  = HTTP-name "/" DIGIT "." DIGIT
    HTTP-name     = %s"HTTP"

However, this function is more strict than the RFC: we only allow HTTP versions of 1.0 and 1.1, as later versions of HTTP don't use a request line.

Returns
tuple[bytes, bytes, bytes](method, request, version) three-tuple
Raises
ValueErrorwhen malformed
_QUEUED_SENTINEL = (source)

Undocumented

Value
object()
_REQUEST_TIMEOUT = (source)

Undocumented

Value
1 * 60
_chunkExtChars: bytes = (source)

Characters that are valid in a chunk extension.

See RFC 7230 section 4.1.1:

     chunk-ext      = *( ";" chunk-ext-name [ "=" chunk-ext-val ] )

     chunk-ext-name = token
     chunk-ext-val  = token / quoted-string

And section 3.2.6:

     token          = 1*tchar

     tchar          = "!" / "#" / "$" / "%" / "&" / "'" / "*"
                    / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
                    / DIGIT / ALPHA
                    ; any VCHAR, except delimiters

     quoted-string  = DQUOTE *( qdtext / quoted-pair ) DQUOTE
     qdtext         = HTAB / SP /%x21 / %x23-5B / %x5D-7E / obs-text
     obs-text       = %x80-FF

We don't check if chunk extensions are well-formed beyond validating that they don't contain characters outside this range.

_hostHeaderExpression = (source)

Undocumented

_monthnameBytes = (source)

Undocumented

_months: list[str] = (source)

Undocumented

_weekdaynameBytes = (source)

Undocumented