An HTTPConnection instance represents one transaction with an HTTP server. It should be instantiated passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has the form host:port, else the default HTTP port (80) is used. If the optional timeout parameter is given, blocking operations (like connection attempts) will timeout after that many seconds (if it is not given, the global default timeout setting is used). The optional source_address parameter may be a tuple of a (host, port) to use as the source address the HTTP connection is made from. The optional blocksize parameter sets the buffer size in bytes for sending a file-like message body.
For example, the following calls all create instances that connect to the server at the same host and port:
Changed in version 3.2: source_address was added.
Changed in version 3.4: The strict parameter was removed. HTTP 0.9-style “Simple Responses” are not longer supported.
Changed in version 3.7: blocksize parameter was added.


Buffer size in bytes for sending a file-like message body.
New in version 3.7.


Connect to the server specified when the object was created. By default, this is called automatically when making a request if the client does not already have a connection.


Send a blank line to the server, signalling the end of the headers. The optional message_body argument can be used to pass a message body associated with the request.
If encode_chunked is True, the result of each iteration of message_body will be chunk-encoded as specified in RFC 7230, Section 3.3.1. How the data is encoded is dependent on the type of message_body. If message_body implements the buffer interface the encoding will result in a single chunk. If message_body is a collections.abc.Iterable, each iteration of message_body will result in a chunk. If message_body is a file object, each call to .read() will result in a chunk. The method automatically signals the end of the chunk-encoded data immediately after message_body.
Note
Due to the chunked encoding specification, empty chunks yielded by an iterator body will be ignored by the chunk-encoder. This is to avoid premature termination of the read of the request by the target server due to malformed encoding.
New in version 3.6: Chunked encoding support. The encode_chunked parameter was added.


Should be called after a request is sent to get the response from the server. Returns an HTTPResponse instance.
Note
Note that you must have read the whole response before you can send a new request to the server.
Changed in version 3.5: If a ConnectionError or subclass is raised, the HTTPConnection object will be ready to reconnect when a new request is sent.


Send an RFC 822-style header to the server. It sends a line to the server consisting of the header, a colon and a space, and the first argument. If more arguments are given, continuation lines are sent, each consisting of a tab and an argument.


This should be the first call after the connection to the server has been made. It sends a line to the server consisting of the method string, the url string, and the HTTP version (HTTP/1.1). To disable automatic sending of Host: or Accept-Encoding: headers (for example to accept additional content encodings), specify skip_host or skip_accept_encoding with non-False values.


This will send a request to the server using the HTTP request method method and the selector url.
If body is specified, the specified data is sent after the headers are finished. It may be a str, a bytes-like object, an open file object, or an iterable of bytes. If body is a string, it is encoded as ISO-8859-1, the default for HTTP. If it is a bytes-like object, the bytes are sent as is. If it is a file object, the contents of the file is sent; this file object should support at least the read() method. If the file object is an instance of io.TextIOBase, the data returned by the read() method will be encoded as ISO-8859-1, otherwise the data returned by read() is sent as is. If body is an iterable, the elements of the iterable are sent as is until the iterable is exhausted.
The headers argument should be a mapping of extra HTTP headers to send with the request.
If headers contains neither Content-Length nor Transfer-Encoding, but there is a request body, one of those header fields will be added automatically. If body is None, the Content-Length header is set to 0 for methods that expect a body (PUT, POST, and PATCH). If body is a string or a bytes-like object that is not also a file, the Content-Length header is set to its length. Any other type of body (files and iterables in general) will be chunk-encoded, and the Transfer-Encoding header will automatically be set instead of Content-Length.
The encode_chunked argument is only relevant if Transfer-Encoding is specified in headers. If encode_chunked is False, the HTTPConnection object assumes that all encoding is handled by the calling code. If it is True, the body will be chunk-encoded.
Note
Chunked transfer encoding has been added to the HTTP protocol version 1.1. Unless the HTTP server is known to handle HTTP 1.1, the caller must either specify the Content-Length, or must pass a str or bytes-like object that is not also a file as the body representation.
New in version 3.2: body can now be an iterable.
Changed in version 3.6: If neither Content-Length nor Transfer-Encoding are set in headers, file and iterable body objects are now chunk-encoded. The encode_chunked argument was added. No attempt is made to determine the Content-Length for file objects.


Send data to the server. This should be used directly only after the endheaders() method has been called and before getresponse() is called.


Set the debugging level. The default debug level is 0, meaning no debugging output is printed. Any value greater than 0 will cause all currently defined debug output to be printed to stdout. The debuglevel is passed to any new HTTPResponse objects that are created.
New in version 3.1.


Set the host and the port for HTTP Connect Tunnelling. This allows running the connection through a proxy server.
The host and port arguments specify the endpoint of the tunneled connection (i.e. the address included in the CONNECT request, not the address of the proxy server).
The headers argument should be a mapping of extra HTTP headers to send with the CONNECT request.
For example, to tunnel through a HTTPS proxy server running locally on port 8080, we would pass the address of the proxy to the HTTPSConnection constructor, and the address of the host that we eventually want to reach to the set_tunnel() method:
New in version 3.2.


The base class of the other exceptions in this module. It is a subclass of Exception.


Class whose instances are returned upon successful connection. Not instantiated directly by user.
Changed in version 3.4: The strict parameter was removed. HTTP 0.9 style “Simple Responses” are no longer supported.


A debugging hook. If debuglevel is greater than zero, messages will be printed to stdout as the response is read and parsed.


Return the fileno of the underlying socket.


Return the value of the header name, or default if there is no header matching name. If there is more than one header with the name name, return all of the values joined by ‘, ‘. If ‘default’ is any iterable other than a single string, its elements are similarly returned joined by commas.


Return a list of (header, value) tuples.


Deprecated since version 3.9: Deprecated in favor of status.


Deprecated since version 3.9: Deprecated in favor of url.


Headers of the response in the form of an email.message.EmailMessage instance.


Deprecated since version 3.9: Deprecated in favor of headers.


A http.client.HTTPMessage instance containing the response headers. http.client.HTTPMessage is a subclass of email.message.Message.


Reads and returns the response body, or up to the next amt bytes.


Reads up to the next len(b) bytes of the response body into the buffer b. Returns the number of bytes read.
New in version 3.3.


URL of the resource retrieved, commonly used to determine if a redirect was followed.


HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.


A subclass of HTTPConnection that uses SSL for communication with secure servers. Default port is 443. If context is specified, it must be a ssl.SSLContext instance describing the various SSL options.
Please read Security considerations for more information on best practices.
Changed in version 3.2: source_address, context and check_hostname were added.
Changed in version 3.2: This class now supports HTTPS virtual hosts if possible (that is, if ssl.HAS_SNI is true).
Changed in version 3.4: The strict parameter was removed. HTTP 0.9-style “Simple Responses” are no longer supported.
Changed in version 3.4.3: This class now performs all the necessary certificate and hostname checks by default. To revert to the previous, unverified, behavior ssl._create_unverified_context() can be passed to the context parameter.
Changed in version 3.8: This class now enables TLS 1.3 ssl.SSLContext.post_handshake_auth for the default context or when cert_file is passed with a custom context.
Deprecated since version 3.6: key_file and cert_file are deprecated in favor of context. Please use ssl.SSLContext.load_cert_chain() instead, or let ssl.create_default_context() select the system’s trusted CA certificates for you.
The check_hostname parameter is also deprecated; the ssl.SSLContext.check_hostname attribute of context should be used instead.


The default port for the HTTPS protocol (always 443).


The default port for the HTTP protocol (always 80).


A subclass of HTTPException, raised if a port is given and is either non-numeric or empty.


A subclass of HTTPException. Raised if an excessively long line is received in the HTTP protocol from the server.


Parse the headers from a file pointer fp representing a HTTP request/response. The file has to be a BufferedIOBase reader (i.e. not text) and must provide a valid RFC 2822 style header.
This function returns an instance of http.client.HTTPMessage that holds the header fields, but no payload (the same as HTTPResponse.msg and http.server.BaseHTTPRequestHandler.headers). After returning, the file pointer fp is ready to read the HTTP body.
Note
parse_headers() does not parse the start-line of a HTTP message; it only parses the Name: value lines. The file has to be ready to read these field lines, so the first line should already be consumed before calling the function.


A subclass of ConnectionResetError and BadStatusLine. Raised by HTTPConnection.getresponse() when the attempt to read the response results in no data read from the connection, indicating that the remote end has closed the connection.
New in version 3.5: Previously, BadStatusLine('') was raised.


This dictionary maps the HTTP 1.1 status codes to the W3C names.
Example: http.client.responses[http.client.NOT_FOUND] is 'Not Found'.


Source code: Lib/http/cookiejar.py
The http.cookiejar module defines classes for automatic handling of HTTP cookies. It is useful for accessing web sites that require small pieces of data – cookies – to be set on the client machine by an HTTP response from a web server, and then returned to the server in later HTTP requests.
Both the regular Netscape cookie protocol and the protocol defined by RFC 2965 are handled. RFC 2965 handling is switched off by default. RFC 2109 cookies are parsed as Netscape cookies and subsequently treated either as Netscape or RFC 2965 cookies according to the ‘policy’ in effect. Note that the great majority of cookies on the Internet are Netscape cookies. http.cookiejar attempts to follow the de-facto Netscape cookie protocol (which differs substantially from that set out in the original Netscape specification), including taking note of the max-age and port cookie-attributes introduced with RFC 2965.
Note
The various named parameters found in Set-Cookie and Set-Cookie2 headers (eg. domain and expires) are conventionally referred to as attributes. To distinguish them from Python attributes, the documentation for this module uses the term cookie-attribute instead.
The module defines the following exception:
Instances of FileCookieJar raise this exception on failure to load cookies from a file. LoadError is a subclass of OSError.
Changed in version 3.3: LoadError was made a subclass of OSError instead of IOError.
The following classes are provided:
policy is an object implementing the CookiePolicy interface.
The CookieJar class stores HTTP cookies. It extracts cookies from HTTP requests, and returns them in HTTP responses. CookieJar instances automatically expire contained cookies when necessary. Subclasses are also responsible for storing and retrieving cookies from a file or database.
policy is an object implementing the CookiePolicy interface. For the other arguments, see the documentation for the corresponding attributes.
A CookieJar which can load cookies from, and perhaps save cookies to, a file on disk. Cookies are NOT loaded from the named file until either the load() or revert() method is called. Subclasses of this class are documented in section FileCookieJar subclasses and co-operation with web browsers.
Changed in version 3.8: The filename parameter supports a path-like object.
This class is responsible for deciding whether each cookie should be accepted from / returned to the server.
Constructor arguments should be passed as keyword arguments only. blocked_domains is a sequence of domain names that we never accept cookies from, nor return cookies to. allowed_domains if not None, this is a sequence of the only domains for which we accept and return cookies. secure_protocols is a sequence of protocols for which secure cookies can be added to. By default https and wss (secure websocket) are considered secure protocols. For all other arguments, see the documentation for CookiePolicy and DefaultCookiePolicy objects.
DefaultCookiePolicy implements the standard accept / reject rules for Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (ie. cookies received in a Set-Cookie header with a version cookie-attribute of 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling is turned off or rfc2109_as_netscape is True, RFC 2109 cookies are ‘downgraded’ by the CookieJar instance to Netscape cookies, by setting the version attribute of the Cookie instance to 0. DefaultCookiePolicy also provides some parameters to allow some fine-tuning of policy.
This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not expected that users of http.cookiejar construct their own Cookie instances. Instead, if necessary, call make_cookies() on a CookieJar instance.
See also
URL opening with automatic cookie handling.
HTTP cookie classes, principally useful for server-side code. The http.cookiejar and http.cookies modules do not depend on each other.
The specification of the original Netscape cookie protocol. Though this is still the dominant protocol, the ‘Netscape cookie protocol’ implemented by all the major browsers (and http.cookiejar) only bears a passing resemblance to the one sketched out in cookie_spec.html.
Obsoleted by RFC 2965. Uses Set-Cookie with version=1.
The Netscape protocol with the bugs fixed. Uses Set-Cookie2 in place of Set-Cookie. Not widely used.
Unfinished errata to RFC 2965.
RFC 2964 - Use of HTTP State Management
CookieJar objects support the iterator protocol for iterating over contained Cookie objects.
CookieJar has the following methods:
Add correct Cookie header to request.
If policy allows (ie. the rfc2965 and hide_cookie2 attributes of the CookieJar’s CookiePolicy instance are true and false respectively), the Cookie2 header is also added when appropriate.
The request object (usually a urllib.request.Request instance) must support the methods get_full_url(), get_host(), get_type(), unverifiable(), has_header(), get_header(), header_items(), add_unredirected_header() and origin_req_host attribute as documented by urllib.request.
Changed in version 3.3: request object needs origin_req_host attribute. Dependency on a deprecated method get_origin_req_host() has been removed.
Extract cookies from HTTP response and store them in the CookieJar, where allowed by policy.
The CookieJar will look for allowable Set-Cookie and Set-Cookie2 headers in the response argument, and store cookies as appropriate (subject to the CookiePolicy.set_ok() method’s approval).
The response object (usually the result of a call to urllib.request.urlopen(), or similar) should support an info() method, which returns an email.message.Message instance.
The request object (usually a urllib.request.Request instance) must support the methods get_full_url(), get_host(), unverifiable(), and origin_req_host attribute, as documented by urllib.request. The request is used to set default values for cookie-attributes as well as for checking that the cookie is allowed to be set.
Changed in version 3.3: request object needs origin_req_host attribute. Dependency on a deprecated method get_origin_req_host() has been removed.
Set the CookiePolicy instance to be used.
Return sequence of Cookie objects extracted from response object.
See the documentation for extract_cookies() for the interfaces required of the response and request arguments.
Set a Cookie if policy says it’s OK to do so.
Set a Cookie, without checking with policy to see whether or not it should be set.
Clear some cookies.
If invoked without arguments, clear all cookies. If given a single argument, only cookies belonging to that domain will be removed. If given two arguments, cookies belonging to the specified domain and URL path are removed. If given three arguments, then the cookie with the specified domain, path and name is removed.
Raises KeyError if no matching cookie exists.
Discard all session cookies.
Discards all contained cookies that have a true discard attribute (usually because they had either no max-age or expires cookie-attribute, or an explicit discard cookie-attribute). For interactive browsers, the end of a session usually corresponds to closing the browser window.
Note that the save() method won’t save session cookies anyway, unless you ask otherwise by passing a true ignore_discard argument.
FileCookieJar implements the following additional methods:
Save cookies to a file.
This base class raises NotImplementedError. Subclasses may leave this method unimplemented.
filename is the name of file in which to save cookies. If filename is not specified, self.filename is used (whose default is the value passed to the constructor, if any); if self.filename is None, ValueError is raised.
ignore_discard: save even cookies set to be discarded. ignore_expires: save even cookies that have expired
The file is overwritten if it already exists, thus wiping all the cookies it contains. Saved cookies can be restored later using the load() or revert() methods.
Load cookies from a file.
Old cookies are kept unless overwritten by newly loaded ones.
Arguments are as for save().
The named file must be in the format understood by the class, or LoadError will be raised. Also, OSError may be raised, for example if the file does not exist.
Changed in version 3.3: IOError used to be raised, it is now an alias of OSError.
Clear all cookies and reload cookies from a saved file.
revert() can raise the same exceptions as load(). If there is a failure, the object’s state will not be altered.
FileCookieJar instances have the following public attributes:
Filename of default file in which to keep cookies. This attribute may be assigned to.
If true, load cookies lazily from disk. This attribute should not be assigned to. This is only a hint, since this only affects performance, not behaviour (unless the cookies on disk are changing). A CookieJar object may ignore it. None of the FileCookieJar classes included in the standard library lazily loads cookies.
The following CookieJar subclasses are provided for reading and writing.
A FileCookieJar that can load from and save cookies to disk in the Mozilla cookies.txt file format (which is also used by the Lynx and Netscape browsers).
Note
This loses information about RFC 2965 cookies, and also about newer or non-standard cookie-attributes such as port.
Warning
Back up your cookies before saving if you have cookies whose loss / corruption would be inconvenient (there are some subtleties which may lead to slight changes in the file over a load / save round-trip).
Also note that cookies saved while Mozilla is running will get clobbered by Mozilla.
A FileCookieJar that can load from and save cookies to disk in format compatible with the libwww-perl library’s Set-Cookie3 file format. This is convenient if you want to store cookies in a human-readable file.
Changed in version 3.8: The filename parameter supports a path-like object.
Objects implementing the CookiePolicy interface have the following methods:
Return boolean value indicating whether cookie should be accepted from server.
cookie is a Cookie instance. request is an object implementing the interface defined by the documentation for CookieJar.extract_cookies().
Return boolean value indicating whether cookie should be returned to server.
cookie is a Cookie instance. request is an object implementing the interface defined by the documentation for CookieJar.add_cookie_header().
Return False if cookies should not be returned, given cookie domain.
This method is an optimization. It removes the need for checking every cookie with a particular domain (which might involve reading many files). Returning true from domain_return_ok() and path_return_ok() leaves all the work to return_ok().
If domain_return_ok() returns true for the cookie domain, path_return_ok() is called for the cookie path. Otherwise, path_return_ok() and return_ok() are never called for that cookie domain. If path_return_ok() returns true, return_ok() is called with the Cookie object itself for a full check. Otherwise, return_ok() is never called for that cookie path.
Note that domain_return_ok() is called for every cookie domain, not just for the request domain. For example, the function might be called with both ".example.com" and "www.example.com" if the request domain is "www.example.com". The same goes for path_return_ok().
The request argument is as documented for return_ok().
Return False if cookies should not be returned, given cookie path.
See the documentation for domain_return_ok().
In addition to implementing the methods above, implementations of the CookiePolicy interface must also supply the following attributes, indicating which protocols should be used, and how. All of these attributes may be assigned to.
Implement Netscape protocol.
Implement RFC 2965 protocol.
Don’t add Cookie2 header to requests (the presence of this header indicates to the server that we understand RFC 2965 cookies).
The most useful way to define a CookiePolicy class is by subclassing from DefaultCookiePolicy and overriding some or all of the methods above. CookiePolicy itself may be used as a ‘null policy’ to allow setting and receiving any and all cookies (this is unlikely to be useful).
Implements the standard rules for accepting and returning cookies.
Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is switched off by default.
The easiest way to provide your own policy is to override this class and call its methods in your overridden implementations before adding your own additional checks:
In addition to the features required to implement the CookiePolicy interface, this class allows you to block and allow domains from setting and receiving cookies. There are also some strictness switches that allow you to tighten up the rather loose Netscape protocol rules a little bit (at the cost of blocking some benign cookies).
A domain blacklist and whitelist is provided (both off by default). Only domains not in the blacklist and present in the whitelist (if the whitelist is active) participate in cookie setting and returning. Use the blocked_domains constructor argument, and blocked_domains() and set_blocked_domains() methods (and the corresponding argument and methods for allowed_domains). If you set a whitelist, you can turn it off again by setting it to None.
Domains in block or allow lists that do not start with a dot must equal the cookie domain to be matched. For example, "example.com" matches a blacklist entry of "example.com", but "www.example.com" does not. Domains that do start with a dot are matched by more specific domains too. For example, both "www.example.com" and "www.coyote.example.com" match ".example.com" (but "example.com" itself does not). IP addresses are an exception, and must match exactly. For example, if blocked_domains contains "192.168.1.2" and ".168.1.2", 192.168.1.2 is blocked, but 193.168.1.2 is not.
DefaultCookiePolicy implements the following additional methods:
Return the sequence of blocked domains (as a tuple).
Set the sequence of blocked domains.
Return whether domain is on the blacklist for setting or receiving cookies.
Return None, or the sequence of allowed domains (as a tuple).
Set the sequence of allowed domains, or None.
Return whether domain is not on the whitelist for setting or receiving cookies.
DefaultCookiePolicy instances have the following attributes, which are all initialised from the constructor arguments of the same name, and which may all be assigned to.
If true, request that the CookieJar instance downgrade RFC 2109 cookies (ie. cookies received in a Set-Cookie header with a version cookie-attribute of 1) to Netscape cookies by setting the version attribute of the Cookie instance to 0. The default value is None, in which case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned off. Therefore, RFC 2109 cookies are downgraded by default.
General strictness switches:
Don’t allow sites to set two-component domains with country-code top-level domains like .co.uk, .gov.uk, .co.nz.etc. This is far from perfect and isn’t guaranteed to work!
RFC 2965 protocol strictness switches:
Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable transaction is one resulting from a redirect or a request for an image hosted on another site). If this is false, cookies are never blocked on the basis of verifiability
Netscape protocol strictness switches:
Apply RFC 2965 rules on unverifiable transactions even to Netscape cookies.
Flags indicating how strict to be with domain-matching rules for Netscape cookies. See below for acceptable values.
Ignore cookies in Set-Cookie: headers that have names starting with '$'.
Don’t allow setting cookies whose path doesn’t path-match request URI.
strict_ns_domain is a collection of flags. Its value is constructed by or-ing together (for example, DomainStrictNoDots|DomainStrictNonDomain means both flags are set).
When setting cookies, the ‘host prefix’ must not contain a dot (eg. www.foo.bar.com can’t set a cookie for .bar.com, because www.foo contains a dot).
Cookies that did not explicitly specify a domain cookie-attribute can only be returned to a domain equal to the domain that set the cookie (eg. spam.example.com won’t be returned cookies from example.com that had no domain cookie-attribute).
When setting cookies, require a full RFC 2965 domain-match.
The following attributes are provided for convenience, and are the most useful combinations of the above flags:
Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched off).
Equivalent to DomainStrictNoDots|DomainStrictNonDomain.
Cookie instances have Python attributes roughly corresponding to the standard cookie-attributes specified in the various cookie standards. The correspondence is not one-to-one, because there are complicated rules for assigning default values, because the max-age and expires cookie-attributes contain equivalent information, and because RFC 2109 cookies may be ‘downgraded’ by http.cookiejar from version 1 to version 0 (Netscape) cookies.
Assignment to these attributes should not be necessary other than in rare circumstances in a CookiePolicy method. The class does not enforce internal consistency, so you should know what you’re doing if you do that.
Integer or None. Netscape cookies have version 0. RFC 2965 and RFC 2109 cookies have a version cookie-attribute of 1. However, note that http.cookiejar may ‘downgrade’ RFC 2109 cookies to Netscape cookies, in which case version is 0.
Cookie name (a string).
Cookie value (a string), or None.
String representing a port or a set of ports (eg. ‘80’, or ‘80,8080’), or None.
Cookie path (a string, eg. '/acme/rocket_launchers').
True if cookie should only be returned over a secure connection.
Integer expiry date in seconds since epoch, or None. See also the is_expired() method.
True if this is a session cookie.
String comment from the server explaining the function of this cookie, or None.
URL linking to a comment from the server explaining the function of this cookie, or None.
True if this cookie was received as an RFC 2109 cookie (ie. the cookie arrived in a Set-Cookie header, and the value of the Version cookie-attribute in that header was 1). This attribute is provided because http.cookiejar may ‘downgrade’ RFC 2109 cookies to Netscape cookies, in which case version is 0.
True if a port or set of ports was explicitly specified by the server (in the Set-Cookie / Set-Cookie2 header).
True if a domain was explicitly specified by the server.
True if the domain explicitly specified by the server began with a dot ('.').
Cookies may have additional non-standard cookie-attributes. These may be accessed using the following methods:
Return True if cookie has the named cookie-attribute.
If cookie has the named cookie-attribute, return its value. Otherwise, return default.
Set the value of the named cookie-attribute.
The Cookie class also defines the following method:
True if cookie has passed the time at which the server requested it should expire. If now is given (in seconds since the epoch), return whether the cookie has expired at the specified time.
The first example shows the most common usage of http.cookiejar:
This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx cookies (assumes Unix/Netscape convention for location of the cookies file):
The next example illustrates the use of DefaultCookiePolicy. Turn on RFC 2965 cookies, be more strict about domains when setting and returning Netscape cookies, and block some domains from setting cookies or having them returned:


This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not expected that users of http.cookiejar construct their own Cookie instances. Instead, if necessary, call make_cookies() on a CookieJar instance.


String comment from the server explaining the function of this cookie, or None.


URL linking to a comment from the server explaining the function of this cookie, or None.


True if the domain explicitly specified by the server began with a dot ('.').


True if a domain was explicitly specified by the server.


Integer expiry date in seconds since epoch, or None. See also the is_expired() method.


If cookie has the named cookie-attribute, return its value. Otherwise, return default.


Return True if cookie has the named cookie-attribute.


True if cookie has passed the time at which the server requested it should expire. If now is given (in seconds since the epoch), return whether the cookie has expired at the specified time.


Cookie path (a string, eg. '/acme/rocket_launchers').


String representing a port or a set of ports (eg. ‘80’, or ‘80,8080’), or None.


True if a port or set of ports was explicitly specified by the server (in the Set-Cookie / Set-Cookie2 header).


True if this cookie was received as an RFC 2109 cookie (ie. the cookie arrived in a Set-Cookie header, and the value of the Version cookie-attribute in that header was 1). This attribute is provided because http.cookiejar may ‘downgrade’ RFC 2109 cookies to Netscape cookies, in which case version is 0.


True if cookie should only be returned over a secure connection.


Set the value of the named cookie-attribute.


Integer or None. Netscape cookies have version 0. RFC 2965 and RFC 2109 cookies have a version cookie-attribute of 1. However, note that http.cookiejar may ‘downgrade’ RFC 2109 cookies to Netscape cookies, in which case version is 0.


policy is an object implementing the CookiePolicy interface.
The CookieJar class stores HTTP cookies. It extracts cookies from HTTP requests, and returns them in HTTP responses. CookieJar instances automatically expire contained cookies when necessary. Subclasses are also responsible for storing and retrieving cookies from a file or database.


Add correct Cookie header to request.
If policy allows (ie. the rfc2965 and hide_cookie2 attributes of the CookieJar’s CookiePolicy instance are true and false respectively), the Cookie2 header is also added when appropriate.
The request object (usually a urllib.request.Request instance) must support the methods get_full_url(), get_host(), get_type(), unverifiable(), has_header(), get_header(), header_items(), add_unredirected_header() and origin_req_host attribute as documented by urllib.request.
Changed in version 3.3: request object needs origin_req_host attribute. Dependency on a deprecated method get_origin_req_host() has been removed.


Clear some cookies.
If invoked without arguments, clear all cookies. If given a single argument, only cookies belonging to that domain will be removed. If given two arguments, cookies belonging to the specified domain and URL path are removed. If given three arguments, then the cookie with the specified domain, path and name is removed.
Raises KeyError if no matching cookie exists.


Discard all session cookies.
Discards all contained cookies that have a true discard attribute (usually because they had either no max-age or expires cookie-attribute, or an explicit discard cookie-attribute). For interactive browsers, the end of a session usually corresponds to closing the browser window.
Note that the save() method won’t save session cookies anyway, unless you ask otherwise by passing a true ignore_discard argument.


Extract cookies from HTTP response and store them in the CookieJar, where allowed by policy.
The CookieJar will look for allowable Set-Cookie and Set-Cookie2 headers in the response argument, and store cookies as appropriate (subject to the CookiePolicy.set_ok() method’s approval).
The response object (usually the result of a call to urllib.request.urlopen(), or similar) should support an info() method, which returns an email.message.Message instance.
The request object (usually a urllib.request.Request instance) must support the methods get_full_url(), get_host(), unverifiable(), and origin_req_host attribute, as documented by urllib.request. The request is used to set default values for cookie-attributes as well as for checking that the cookie is allowed to be set.
Changed in version 3.3: request object needs origin_req_host attribute. Dependency on a deprecated method get_origin_req_host() has been removed.


Return sequence of Cookie objects extracted from response object.
See the documentation for extract_cookies() for the interfaces required of the response and request arguments.


Set a Cookie, without checking with policy to see whether or not it should be set.


Set a Cookie if policy says it’s OK to do so.


Set the CookiePolicy instance to be used.


This class is responsible for deciding whether each cookie should be accepted from / returned to the server.


Return False if cookies should not be returned, given cookie domain.
This method is an optimization. It removes the need for checking every cookie with a particular domain (which might involve reading many files). Returning true from domain_return_ok() and path_return_ok() leaves all the work to return_ok().
If domain_return_ok() returns true for the cookie domain, path_return_ok() is called for the cookie path. Otherwise, path_return_ok() and return_ok() are never called for that cookie domain. If path_return_ok() returns true, return_ok() is called with the Cookie object itself for a full check. Otherwise, return_ok() is never called for that cookie path.
Note that domain_return_ok() is called for every cookie domain, not just for the request domain. For example, the function might be called with both ".example.com" and "www.example.com" if the request domain is "www.example.com". The same goes for path_return_ok().
The request argument is as documented for return_ok().


Don’t add Cookie2 header to requests (the presence of this header indicates to the server that we understand RFC 2965 cookies).


Return False if cookies should not be returned, given cookie path.
See the documentation for domain_return_ok().


Return boolean value indicating whether cookie should be returned to server.
cookie is a Cookie instance. request is an object implementing the interface defined by the documentation for CookieJar.add_cookie_header().


Return boolean value indicating whether cookie should be accepted from server.
cookie is a Cookie instance. request is an object implementing the interface defined by the documentation for CookieJar.extract_cookies().


Constructor arguments should be passed as keyword arguments only. blocked_domains is a sequence of domain names that we never accept cookies from, nor return cookies to. allowed_domains if not None, this is a sequence of the only domains for which we accept and return cookies. secure_protocols is a sequence of protocols for which secure cookies can be added to. By default https and wss (secure websocket) are considered secure protocols. For all other arguments, see the documentation for CookiePolicy and DefaultCookiePolicy objects.
DefaultCookiePolicy implements the standard accept / reject rules for Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (ie. cookies received in a Set-Cookie header with a version cookie-attribute of 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling is turned off or rfc2109_as_netscape is True, RFC 2109 cookies are ‘downgraded’ by the CookieJar instance to Netscape cookies, by setting the version attribute of the Cookie instance to 0. DefaultCookiePolicy also provides some parameters to allow some fine-tuning of policy.


Return None, or the sequence of allowed domains (as a tuple).


Return the sequence of blocked domains (as a tuple).


Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched off).


When setting cookies, require a full RFC 2965 domain-match.


When setting cookies, the ‘host prefix’ must not contain a dot (eg. www.foo.bar.com can’t set a cookie for .bar.com, because www.foo contains a dot).


Cookies that did not explicitly specify a domain cookie-attribute can only be returned to a domain equal to the domain that set the cookie (eg. spam.example.com won’t be returned cookies from example.com that had no domain cookie-attribute).


Return whether domain is on the blacklist for setting or receiving cookies.


Return whether domain is not on the whitelist for setting or receiving cookies.


If true, request that the CookieJar instance downgrade RFC 2109 cookies (ie. cookies received in a Set-Cookie header with a version cookie-attribute of 1) to Netscape cookies by setting the version attribute of the Cookie instance to 0. The default value is None, in which case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned off. Therefore, RFC 2109 cookies are downgraded by default.


Set the sequence of allowed domains, or None.


Don’t allow sites to set two-component domains with country-code top-level domains like .co.uk, .gov.uk, .co.nz.etc. This is far from perfect and isn’t guaranteed to work!


Flags indicating how strict to be with domain-matching rules for Netscape cookies. See below for acceptable values.


Ignore cookies in Set-Cookie: headers that have names starting with '$'.


Don’t allow setting cookies whose path doesn’t path-match request URI.


Apply RFC 2965 rules on unverifiable transactions even to Netscape cookies.


Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable transaction is one resulting from a redirect or a request for an image hosted on another site). If this is false, cookies are never blocked on the basis of verifiability


policy is an object implementing the CookiePolicy interface. For the other arguments, see the documentation for the corresponding attributes.
A CookieJar which can load cookies from, and perhaps save cookies to, a file on disk. Cookies are NOT loaded from the named file until either the load() or revert() method is called. Subclasses of this class are documented in section FileCookieJar subclasses and co-operation with web browsers.
Changed in version 3.8: The filename parameter supports a path-like object.


If true, load cookies lazily from disk. This attribute should not be assigned to. This is only a hint, since this only affects performance, not behaviour (unless the cookies on disk are changing). A CookieJar object may ignore it. None of the FileCookieJar classes included in the standard library lazily loads cookies.


Filename of default file in which to keep cookies. This attribute may be assigned to.


Load cookies from a file.
Old cookies are kept unless overwritten by newly loaded ones.
Arguments are as for save().
The named file must be in the format understood by the class, or LoadError will be raised. Also, OSError may be raised, for example if the file does not exist.
Changed in version 3.3: IOError used to be raised, it is now an alias of OSError.


Clear all cookies and reload cookies from a saved file.
revert() can raise the same exceptions as load(). If there is a failure, the object’s state will not be altered.


Save cookies to a file.
This base class raises NotImplementedError. Subclasses may leave this method unimplemented.
filename is the name of file in which to save cookies. If filename is not specified, self.filename is used (whose default is the value passed to the constructor, if any); if self.filename is None, ValueError is raised.
ignore_discard: save even cookies set to be discarded. ignore_expires: save even cookies that have expired
The file is overwritten if it already exists, thus wiping all the cookies it contains. Saved cookies can be restored later using the load() or revert() methods.


Instances of FileCookieJar raise this exception on failure to load cookies from a file. LoadError is a subclass of OSError.
Changed in version 3.3: LoadError was made a subclass of OSError instead of IOError.


A FileCookieJar that can load from and save cookies to disk in format compatible with the libwww-perl library’s Set-Cookie3 file format. This is convenient if you want to store cookies in a human-readable file.
Changed in version 3.8: The filename parameter supports a path-like object.


A FileCookieJar that can load from and save cookies to disk in the Mozilla cookies.txt file format (which is also used by the Lynx and Netscape browsers).
Note
This loses information about RFC 2965 cookies, and also about newer or non-standard cookie-attributes such as port.
Warning
Back up your cookies before saving if you have cookies whose loss / corruption would be inconvenient (there are some subtleties which may lead to slight changes in the file over a load / save round-trip).
Also note that cookies saved while Mozilla is running will get clobbered by Mozilla.


Source code: Lib/http/cookies.py
The http.cookies module defines classes for abstracting the concept of cookies, an HTTP state management mechanism. It supports both simple string-only cookies, and provides an abstraction for having any serializable data-type as cookie value.
The module formerly strictly applied the parsing rules described in the RFC 2109 and RFC 2068 specifications. It has since been discovered that MSIE 3.0x doesn’t follow the character rules outlined in those specs and also many current day browsers and servers have relaxed parsing rules when comes to Cookie handling. As a result, the parsing rules used are a bit less strict.
The character set, string.ascii_letters, string.digits and !#$%&'*+-.^_`|~: denote the set of valid characters allowed by this module in Cookie name (as key).
Changed in version 3.3: Allowed ‘:’ as a valid Cookie name character.
Note
On encountering an invalid cookie, CookieError is raised, so if your cookie data comes from a browser you should always prepare for invalid data and catch CookieError on parsing.
Exception failing because of RFC 2109 invalidity: incorrect attributes, incorrect Set-Cookie header, etc.
This class is a dictionary-like object whose keys are strings and whose values are Morsel instances. Note that upon setting a key to a value, the value is first converted to a Morsel containing the key and the value.
If input is given, it is passed to the load() method.
This class derives from BaseCookie and overrides value_decode() and value_encode(). SimpleCookie supports strings as cookie values. When setting the value, SimpleCookie calls the builtin str() to convert the value to a string. Values received from HTTP are kept as strings.
See also
HTTP cookie handling for web clients. The http.cookiejar and http.cookies modules do not depend on each other.
This is the state management specification implemented by this module.
Return a tuple (real_value, coded_value) from a string representation. real_value can be any type. This method does no decoding in BaseCookie — it exists so it can be overridden.
Return a tuple (real_value, coded_value). val can be any type, but coded_value will always be converted to a string. This method does no encoding in BaseCookie — it exists so it can be overridden.
In general, it should be the case that value_encode() and value_decode() are inverses on the range of value_decode.
Return a string representation suitable to be sent as HTTP headers. attrs and header are sent to each Morsel’s output() method. sep is used to join the headers together, and is by default the combination '\r\n' (CRLF).
Return an embeddable JavaScript snippet, which, if run on a browser which supports JavaScript, will act the same as if the HTTP headers was sent.
The meaning for attrs is the same as in output().
If rawdata is a string, parse it as an HTTP_COOKIE and add the values found there as Morsels. If it is a dictionary, it is equivalent to:
Abstract a key/value pair, which has some RFC 2109 attributes.
Morsels are dictionary-like objects, whose set of keys is constant — the valid RFC 2109 attributes, which are
The attribute httponly specifies that the cookie is only transferred in HTTP requests, and is not accessible through JavaScript. This is intended to mitigate some forms of cross-site scripting.
The attribute samesite specifies that the browser is not allowed to send the cookie along with cross-site requests. This helps to mitigate CSRF attacks. Valid values for this attribute are “Strict” and “Lax”.
The keys are case-insensitive and their default value is ''.
Changed in version 3.5: __eq__() now takes key and value into account.
Changed in version 3.7: Attributes key, value and coded_value are read-only. Use set() for setting them.
Changed in version 3.8: Added support for the samesite attribute.
The value of the cookie.
The encoded value of the cookie — this is what should be sent.
The name of the cookie.
Set the key, value and coded_value attributes.
Whether K is a member of the set of keys of a Morsel.
Return a string representation of the Morsel, suitable to be sent as an HTTP header. By default, all the attributes are included, unless attrs is given, in which case it should be a list of attributes to use. header is by default "Set-Cookie:".
Return an embeddable JavaScript snippet, which, if run on a browser which supports JavaScript, will act the same as if the HTTP header was sent.
The meaning for attrs is the same as in output().
Return a string representing the Morsel, without any surrounding HTTP or JavaScript.
The meaning for attrs is the same as in output().
Update the values in the Morsel dictionary with the values in the dictionary values. Raise an error if any of the keys in the values dict is not a valid RFC 2109 attribute.
Changed in version 3.5: an error is raised for invalid keys.
Return a shallow copy of the Morsel object.
Changed in version 3.5: return a Morsel object instead of a dict.
Raise an error if key is not a valid RFC 2109 attribute, otherwise behave the same as dict.setdefault().
The following example demonstrates how to use the http.cookies module.


This class is a dictionary-like object whose keys are strings and whose values are Morsel instances. Note that upon setting a key to a value, the value is first converted to a Morsel containing the key and the value.
If input is given, it is passed to the load() method.


Return an embeddable JavaScript snippet, which, if run on a browser which supports JavaScript, will act the same as if the HTTP headers was sent.
The meaning for attrs is the same as in output().


If rawdata is a string, parse it as an HTTP_COOKIE and add the values found there as Morsels. If it is a dictionary, it is equivalent to:


Return a string representation suitable to be sent as HTTP headers. attrs and header are sent to each Morsel’s output() method. sep is used to join the headers together, and is by default the combination '\r\n' (CRLF).


Return a tuple (real_value, coded_value) from a string representation. real_value can be any type. This method does no decoding in BaseCookie — it exists so it can be overridden.


Return a tuple (real_value, coded_value). val can be any type, but coded_value will always be converted to a string. This method does no encoding in BaseCookie — it exists so it can be overridden.
In general, it should be the case that value_encode() and value_decode() are inverses on the range of value_decode.


Exception failing because of RFC 2109 invalidity: incorrect attributes, incorrect Set-Cookie header, etc.


Abstract a key/value pair, which has some RFC 2109 attributes.
Morsels are dictionary-like objects, whose set of keys is constant — the valid RFC 2109 attributes, which are
The attribute httponly specifies that the cookie is only transferred in HTTP requests, and is not accessible through JavaScript. This is intended to mitigate some forms of cross-site scripting.
The attribute samesite specifies that the browser is not allowed to send the cookie along with cross-site requests. This helps to mitigate CSRF attacks. Valid values for this attribute are “Strict” and “Lax”.
The keys are case-insensitive and their default value is ''.
Changed in version 3.5: __eq__() now takes key and value into account.
Changed in version 3.7: Attributes key, value and coded_value are read-only. Use set() for setting them.
Changed in version 3.8: Added support for the samesite attribute.


The encoded value of the cookie — this is what should be sent.


Return a shallow copy of the Morsel object.
Changed in version 3.5: return a Morsel object instead of a dict.


Whether K is a member of the set of keys of a Morsel.


Return an embeddable JavaScript snippet, which, if run on a browser which supports JavaScript, will act the same as if the HTTP header was sent.
The meaning for attrs is the same as in output().


Return a string representation of the Morsel, suitable to be sent as an HTTP header. By default, all the attributes are included, unless attrs is given, in which case it should be a list of attributes to use. header is by default "Set-Cookie:".


Return a string representing the Morsel, without any surrounding HTTP or JavaScript.
The meaning for attrs is the same as in output().


Set the key, value and coded_value attributes.


Raise an error if key is not a valid RFC 2109 attribute, otherwise behave the same as dict.setdefault().


Update the values in the Morsel dictionary with the values in the dictionary values. Raise an error if any of the keys in the values dict is not a valid RFC 2109 attribute.
Changed in version 3.5: an error is raised for invalid keys.


This class derives from BaseCookie and overrides value_decode() and value_encode(). SimpleCookie supports strings as cookie values. When setting the value, SimpleCookie calls the builtin str() to convert the value to a string. Values received from HTTP are kept as strings.


New in version 3.5.
A subclass of enum.IntEnum that defines a set of HTTP status codes, reason phrases and long descriptions written in English.
Usage:


Source code: Lib/http/server.py
This module defines classes for implementing HTTP servers (Web servers).
Warning
http.server is not recommended for production. It only implements basic security checks.
One class, HTTPServer, is a socketserver.TCPServer subclass. It creates and listens at the HTTP socket, dispatching the requests to a handler. Code to create and run the server looks like this:
This class builds on the TCPServer class by storing the server address as instance variables named server_name and server_port. The server is accessible by the handler, typically through the handler’s server instance variable.
This class is identical to HTTPServer but uses threads to handle requests by using the ThreadingMixIn. This is useful to handle web browsers pre-opening sockets, on which HTTPServer would wait indefinitely.
New in version 3.7.
The HTTPServer and ThreadingHTTPServer must be given a RequestHandlerClass on instantiation, of which this module provides three different variants:
This class is used to handle the HTTP requests that arrive at the server. By itself, it cannot respond to any actual HTTP requests; it must be subclassed to handle each request method (e.g. GET or POST). BaseHTTPRequestHandler provides a number of class and instance variables, and methods for use by subclasses.
The handler will parse the request and the headers, then call a method specific to the request type. The method name is constructed from the request. For example, for the request method SPAM, the do_SPAM() method will be called with no arguments. All of the relevant information is stored in instance variables of the handler. Subclasses should not need to override or extend the __init__() method.
BaseHTTPRequestHandler has the following instance variables:
Contains a tuple of the form (host, port) referring to the client’s address.
Contains the server instance.
Boolean that should be set before handle_one_request() returns, indicating if another request may be expected, or if the connection should be shut down.
Contains the string representation of the HTTP request line. The terminating CRLF is stripped. This attribute should be set by handle_one_request(). If no valid request line was processed, it should be set to the empty string.
Contains the command (request type). For example, 'GET'.
Contains the request path. If query component of the URL is present, then path includes the query. Using the terminology of RFC 3986, path here includes hier-part and the query.
Contains the version string from the request. For example, 'HTTP/1.0'.
Holds an instance of the class specified by the MessageClass class variable. This instance parses and manages the headers in the HTTP request. The parse_headers() function from http.client is used to parse the headers and it requires that the HTTP request provide a valid RFC 2822 style header.
An io.BufferedIOBase input stream, ready to read from the start of the optional input data.
Contains the output stream for writing a response back to the client. Proper adherence to the HTTP protocol must be used when writing to this stream in order to achieve successful interoperation with HTTP clients.
Changed in version 3.6: This is an io.BufferedIOBase stream.
BaseHTTPRequestHandler has the following attributes:
Specifies the server software version. You may want to override this. The format is multiple whitespace-separated strings, where each string is of the form name[/version]. For example, 'BaseHTTP/0.2'.
Contains the Python system version, in a form usable by the version_string method and the server_version class variable. For example, 'Python/1.4'.
Specifies a format string that should be used by send_error() method for building an error response to the client. The string is filled by default with variables from responses based on the status code that passed to send_error().
Specifies the Content-Type HTTP header of error responses sent to the client. The default value is 'text/html'.
This specifies the HTTP protocol version used in responses. If set to 'HTTP/1.1', the server will permit HTTP persistent connections; however, your server must then include an accurate Content-Length header (using send_header()) in all of its responses to clients. For backwards compatibility, the setting defaults to 'HTTP/1.0'.
Specifies an email.message.Message-like class to parse HTTP headers. Typically, this is not overridden, and it defaults to http.client.HTTPMessage.
This attribute contains a mapping of error code integers to two-element tuples containing a short and long message. For example, {code: (shortmessage,
longmessage)}. The shortmessage is usually used as the message key in an error response, and longmessage as the explain key. It is used by send_response_only() and send_error() methods.
A BaseHTTPRequestHandler instance has the following methods:
Calls handle_one_request() once (or, if persistent connections are enabled, multiple times) to handle incoming HTTP requests. You should never need to override it; instead, implement appropriate do_*() methods.
This method will parse and dispatch the request to the appropriate do_*() method. You should never need to override it.
When a HTTP/1.1 compliant server receives an Expect: 100-continue request header it responds back with a 100 Continue followed by 200
OK headers. This method can be overridden to raise an error if the server does not want the client to continue. For e.g. server can chose to send 417
Expectation Failed as a response header and return False.
New in version 3.2.
Sends and logs a complete error reply to the client. The numeric code specifies the HTTP error code, with message as an optional, short, human readable description of the error. The explain argument can be used to provide more detailed information about the error; it will be formatted using the error_message_format attribute and emitted, after a complete set of headers, as the response body. The responses attribute holds the default values for message and explain that will be used if no value is provided; for unknown codes the default value for both is the string ???. The body will be empty if the method is HEAD or the response code is one of the following: 1xx, 204 No Content, 205 Reset Content, 304 Not Modified.
Changed in version 3.4: The error response includes a Content-Length header. Added the explain argument.
Adds a response header to the headers buffer and logs the accepted request. The HTTP response line is written to the internal buffer, followed by Server and Date headers. The values for these two headers are picked up from the version_string() and date_time_string() methods, respectively. If the server does not intend to send any other headers using the send_header() method, then send_response() should be followed by an end_headers() call.
Changed in version 3.3: Headers are stored to an internal buffer and end_headers() needs to be called explicitly.
Adds the HTTP header to an internal buffer which will be written to the output stream when either end_headers() or flush_headers() is invoked. keyword should specify the header keyword, with value specifying its value. Note that, after the send_header calls are done, end_headers() MUST BE called in order to complete the operation.
Changed in version 3.2: Headers are stored in an internal buffer.
Sends the response header only, used for the purposes when 100
Continue response is sent by the server to the client. The headers not buffered and sent directly the output stream.If the message is not specified, the HTTP message corresponding the response code is sent.
New in version 3.2.
Adds a blank line (indicating the end of the HTTP headers in the response) to the headers buffer and calls flush_headers().
Changed in version 3.2: The buffered headers are written to the output stream.
Finally send the headers to the output stream and flush the internal headers buffer.
New in version 3.3.
Logs an accepted (successful) request. code should specify the numeric HTTP code associated with the response. If a size of the response is available, then it should be passed as the size parameter.
Logs an error when a request cannot be fulfilled. By default, it passes the message to log_message(), so it takes the same arguments (format and additional values).
Logs an arbitrary message to sys.stderr. This is typically overridden to create custom error logging mechanisms. The format argument is a standard printf-style format string, where the additional arguments to log_message() are applied as inputs to the formatting. The client ip address and current date and time are prefixed to every message logged.
Returns the server software’s version string. This is a combination of the server_version and sys_version attributes.
Returns the date and time given by timestamp (which must be None or in the format returned by time.time()), formatted for a message header. If timestamp is omitted, it uses the current date and time.
The result looks like 'Sun, 06 Nov 1994 08:49:37 GMT'.
Returns the current date and time, formatted for logging.
Returns the client address.
Changed in version 3.3: Previously, a name lookup was performed. To avoid name resolution delays, it now always returns the IP address.
This class serves files from the current directory and below, directly mapping the directory structure to HTTP requests.
A lot of the work, such as parsing the request, is done by the base class BaseHTTPRequestHandler. This class implements the do_GET() and do_HEAD() functions.
The following are defined as class-level attributes of SimpleHTTPRequestHandler:
This will be "SimpleHTTP/" + __version__, where __version__ is defined at the module level.
A dictionary mapping suffixes into MIME types, contains custom overrides for the default system mappings. The mapping is used case-insensitively, and so should contain only lower-cased keys.
Changed in version 3.9: This dictionary is no longer filled with the default system mappings, but only contains overrides.
If not specified, the directory to serve is the current working directory.
Changed in version 3.9: Accepts a path-like object.
The SimpleHTTPRequestHandler class defines the following methods:
This method serves the 'HEAD' request type: it sends the headers it would send for the equivalent GET request. See the do_GET() method for a more complete explanation of the possible headers.
The request is mapped to a local file by interpreting the request as a path relative to the current working directory.
If the request was mapped to a directory, the directory is checked for a file named index.html or index.htm (in that order). If found, the file’s contents are returned; otherwise a directory listing is generated by calling the list_directory() method. This method uses os.listdir() to scan the directory, and returns a 404 error response if the listdir() fails.
If the request was mapped to a file, it is opened. Any OSError exception in opening the requested file is mapped to a 404, 'File not found' error. If there was a 'If-Modified-Since' header in the request, and the file was not modified after this time, a 304, 'Not Modified' response is sent. Otherwise, the content type is guessed by calling the guess_type() method, which in turn uses the extensions_map variable, and the file contents are returned.
A 'Content-type:' header with the guessed content type is output, followed by a 'Content-Length:' header with the file’s size and a 'Last-Modified:' header with the file’s modification time.
Then follows a blank line signifying the end of the headers, and then the contents of the file are output. If the file’s MIME type starts with text/ the file is opened in text mode; otherwise binary mode is used.
For example usage, see the implementation of the test() function invocation in the http.server module.
Changed in version 3.7: Support of the 'If-Modified-Since' header.
The SimpleHTTPRequestHandler class can be used in the following manner in order to create a very basic webserver serving files relative to the current directory:
http.server can also be invoked directly using the -m switch of the interpreter with a port number argument. Similar to the previous example, this serves files relative to the current directory:
By default, server binds itself to all interfaces. The option -b/--bind specifies a specific address to which it should bind. Both IPv4 and IPv6 addresses are supported. For example, the following command causes the server to bind to localhost only:
New in version 3.4: --bind argument was introduced.
New in version 3.8: --bind argument enhanced to support IPv6
By default, server uses the current directory. The option -d/--directory specifies a directory to which it should serve the files. For example, the following command uses a specific directory:
New in version 3.7: --directory specify alternate directory
This class is used to serve either files or output of CGI scripts from the current directory and below. Note that mapping HTTP hierarchic structure to local directory structure is exactly as in SimpleHTTPRequestHandler.
Note
CGI scripts run by the CGIHTTPRequestHandler class cannot execute redirects (HTTP code 302), because code 200 (script output follows) is sent prior to execution of the CGI script. This pre-empts the status code.
The class will however, run the CGI script, instead of serving it as a file, if it guesses it to be a CGI script. Only directory-based CGI are used — the other common server configuration is to treat special extensions as denoting CGI scripts.
The do_GET() and do_HEAD() functions are modified to run CGI scripts and serve the output, instead of serving files, if the request leads to somewhere below the cgi_directories path.
The CGIHTTPRequestHandler defines the following data member:
This defaults to ['/cgi-bin', '/htbin'] and describes directories to treat as containing CGI scripts.
The CGIHTTPRequestHandler defines the following method:
This method serves the 'POST' request type, only allowed for CGI scripts. Error 501, “Can only POST to CGI scripts”, is output when trying to POST to a non-CGI url.
Note that CGI scripts will be run with UID of user nobody, for security reasons. Problems with the CGI script will be translated to error 403.
CGIHTTPRequestHandler can be enabled in the command line by passing the --cgi option:


This class is used to handle the HTTP requests that arrive at the server. By itself, it cannot respond to any actual HTTP requests; it must be subclassed to handle each request method (e.g. GET or POST). BaseHTTPRequestHandler provides a number of class and instance variables, and methods for use by subclasses.
The handler will parse the request and the headers, then call a method specific to the request type. The method name is constructed from the request. For example, for the request method SPAM, the do_SPAM() method will be called with no arguments. All of the relevant information is stored in instance variables of the handler. Subclasses should not need to override or extend the __init__() method.
BaseHTTPRequestHandler has the following instance variables:
Contains a tuple of the form (host, port) referring to the client’s address.
Contains the server instance.
Boolean that should be set before handle_one_request() returns, indicating if another request may be expected, or if the connection should be shut down.
Contains the string representation of the HTTP request line. The terminating CRLF is stripped. This attribute should be set by handle_one_request(). If no valid request line was processed, it should be set to the empty string.
Contains the command (request type). For example, 'GET'.
Contains the request path. If query component of the URL is present, then path includes the query. Using the terminology of RFC 3986, path here includes hier-part and the query.
Contains the version string from the request. For example, 'HTTP/1.0'.
Holds an instance of the class specified by the MessageClass class variable. This instance parses and manages the headers in the HTTP request. The parse_headers() function from http.client is used to parse the headers and it requires that the HTTP request provide a valid RFC 2822 style header.
An io.BufferedIOBase input stream, ready to read from the start of the optional input data.
Contains the output stream for writing a response back to the client. Proper adherence to the HTTP protocol must be used when writing to this stream in order to achieve successful interoperation with HTTP clients.
Changed in version 3.6: This is an io.BufferedIOBase stream.
BaseHTTPRequestHandler has the following attributes:
Specifies the server software version. You may want to override this. The format is multiple whitespace-separated strings, where each string is of the form name[/version]. For example, 'BaseHTTP/0.2'.
Contains the Python system version, in a form usable by the version_string method and the server_version class variable. For example, 'Python/1.4'.
Specifies a format string that should be used by send_error() method for building an error response to the client. The string is filled by default with variables from responses based on the status code that passed to send_error().
Specifies the Content-Type HTTP header of error responses sent to the client. The default value is 'text/html'.
This specifies the HTTP protocol version used in responses. If set to 'HTTP/1.1', the server will permit HTTP persistent connections; however, your server must then include an accurate Content-Length header (using send_header()) in all of its responses to clients. For backwards compatibility, the setting defaults to 'HTTP/1.0'.
Specifies an email.message.Message-like class to parse HTTP headers. Typically, this is not overridden, and it defaults to http.client.HTTPMessage.
This attribute contains a mapping of error code integers to two-element tuples containing a short and long message. For example, {code: (shortmessage,
longmessage)}. The shortmessage is usually used as the message key in an error response, and longmessage as the explain key. It is used by send_response_only() and send_error() methods.
A BaseHTTPRequestHandler instance has the following methods:
Calls handle_one_request() once (or, if persistent connections are enabled, multiple times) to handle incoming HTTP requests. You should never need to override it; instead, implement appropriate do_*() methods.
This method will parse and dispatch the request to the appropriate do_*() method. You should never need to override it.
When a HTTP/1.1 compliant server receives an Expect: 100-continue request header it responds back with a 100 Continue followed by 200
OK headers. This method can be overridden to raise an error if the server does not want the client to continue. For e.g. server can chose to send 417
Expectation Failed as a response header and return False.
New in version 3.2.
Sends and logs a complete error reply to the client. The numeric code specifies the HTTP error code, with message as an optional, short, human readable description of the error. The explain argument can be used to provide more detailed information about the error; it will be formatted using the error_message_format attribute and emitted, after a complete set of headers, as the response body. The responses attribute holds the default values for message and explain that will be used if no value is provided; for unknown codes the default value for both is the string ???. The body will be empty if the method is HEAD or the response code is one of the following: 1xx, 204 No Content, 205 Reset Content, 304 Not Modified.
Changed in version 3.4: The error response includes a Content-Length header. Added the explain argument.
Adds a response header to the headers buffer and logs the accepted request. The HTTP response line is written to the internal buffer, followed by Server and Date headers. The values for these two headers are picked up from the version_string() and date_time_string() methods, respectively. If the server does not intend to send any other headers using the send_header() method, then send_response() should be followed by an end_headers() call.
Changed in version 3.3: Headers are stored to an internal buffer and end_headers() needs to be called explicitly.
Adds the HTTP header to an internal buffer which will be written to the output stream when either end_headers() or flush_headers() is invoked. keyword should specify the header keyword, with value specifying its value. Note that, after the send_header calls are done, end_headers() MUST BE called in order to complete the operation.
Changed in version 3.2: Headers are stored in an internal buffer.
Sends the response header only, used for the purposes when 100
Continue response is sent by the server to the client. The headers not buffered and sent directly the output stream.If the message is not specified, the HTTP message corresponding the response code is sent.
New in version 3.2.
Adds a blank line (indicating the end of the HTTP headers in the response) to the headers buffer and calls flush_headers().
Changed in version 3.2: The buffered headers are written to the output stream.
Finally send the headers to the output stream and flush the internal headers buffer.
New in version 3.3.
Logs an accepted (successful) request. code should specify the numeric HTTP code associated with the response. If a size of the response is available, then it should be passed as the size parameter.
Logs an error when a request cannot be fulfilled. By default, it passes the message to log_message(), so it takes the same arguments (format and additional values).
Logs an arbitrary message to sys.stderr. This is typically overridden to create custom error logging mechanisms. The format argument is a standard printf-style format string, where the additional arguments to log_message() are applied as inputs to the formatting. The client ip address and current date and time are prefixed to every message logged.
Returns the server software’s version string. This is a combination of the server_version and sys_version attributes.
Returns the date and time given by timestamp (which must be None or in the format returned by time.time()), formatted for a message header. If timestamp is omitted, it uses the current date and time.
The result looks like 'Sun, 06 Nov 1994 08:49:37 GMT'.
Returns the current date and time, formatted for logging.
Returns the client address.
Changed in version 3.3: Previously, a name lookup was performed. To avoid name resolution delays, it now always returns the IP address.


Returns the client address.
Changed in version 3.3: Previously, a name lookup was performed. To avoid name resolution delays, it now always returns the IP address.


Contains a tuple of the form (host, port) referring to the client’s address.


Boolean that should be set before handle_one_request() returns, indicating if another request may be expected, or if the connection should be shut down.


Contains the command (request type). For example, 'GET'.


Returns the date and time given by timestamp (which must be None or in the format returned by time.time()), formatted for a message header. If timestamp is omitted, it uses the current date and time.
The result looks like 'Sun, 06 Nov 1994 08:49:37 GMT'.


Adds a blank line (indicating the end of the HTTP headers in the response) to the headers buffer and calls flush_headers().
Changed in version 3.2: The buffered headers are written to the output stream.


Specifies the Content-Type HTTP header of error responses sent to the client. The default value is 'text/html'.


Specifies a format string that should be used by send_error() method for building an error response to the client. The string is filled by default with variables from responses based on the status code that passed to send_error().


Finally send the headers to the output stream and flush the internal headers buffer.
New in version 3.3.


Calls handle_one_request() once (or, if persistent connections are enabled, multiple times) to handle incoming HTTP requests. You should never need to override it; instead, implement appropriate do_*() methods.


When a HTTP/1.1 compliant server receives an Expect: 100-continue request header it responds back with a 100 Continue followed by 200
OK headers. This method can be overridden to raise an error if the server does not want the client to continue. For e.g. server can chose to send 417
Expectation Failed as a response header and return False.
New in version 3.2.


This method will parse and dispatch the request to the appropriate do_*() method. You should never need to override it.


Holds an instance of the class specified by the MessageClass class variable. This instance parses and manages the headers in the HTTP request. The parse_headers() function from http.client is used to parse the headers and it requires that the HTTP request provide a valid RFC 2822 style header.


Returns the current date and time, formatted for logging.


Logs an error when a request cannot be fulfilled. By default, it passes the message to log_message(), so it takes the same arguments (format and additional values).


Logs an arbitrary message to sys.stderr. This is typically overridden to create custom error logging mechanisms. The format argument is a standard printf-style format string, where the additional arguments to log_message() are applied as inputs to the formatting. The client ip address and current date and time are prefixed to every message logged.


Logs an accepted (successful) request. code should specify the numeric HTTP code associated with the response. If a size of the response is available, then it should be passed as the size parameter.


Specifies an email.message.Message-like class to parse HTTP headers. Typically, this is not overridden, and it defaults to http.client.HTTPMessage.


Contains the request path. If query component of the URL is present, then path includes the query. Using the terminology of RFC 3986, path here includes hier-part and the query.


This specifies the HTTP protocol version used in responses. If set to 'HTTP/1.1', the server will permit HTTP persistent connections; however, your server must then include an accurate Content-Length header (using send_header()) in all of its responses to clients. For backwards compatibility, the setting defaults to 'HTTP/1.0'.


Contains the string representation of the HTTP request line. The terminating CRLF is stripped. This attribute should be set by handle_one_request(). If no valid request line was processed, it should be set to the empty string.


Contains the version string from the request. For example, 'HTTP/1.0'.


This attribute contains a mapping of error code integers to two-element tuples containing a short and long message. For example, {code: (shortmessage,
longmessage)}. The shortmessage is usually used as the message key in an error response, and longmessage as the explain key. It is used by send_response_only() and send_error() methods.


An io.BufferedIOBase input stream, ready to read from the start of the optional input data.


Sends and logs a complete error reply to the client. The numeric code specifies the HTTP error code, with message as an optional, short, human readable description of the error. The explain argument can be used to provide more detailed information about the error; it will be formatted using the error_message_format attribute and emitted, after a complete set of headers, as the response body. The responses attribute holds the default values for message and explain that will be used if no value is provided; for unknown codes the default value for both is the string ???. The body will be empty if the method is HEAD or the response code is one of the following: 1xx, 204 No Content, 205 Reset Content, 304 Not Modified.
Changed in version 3.4: The error response includes a Content-Length header. Added the explain argument.


Adds the HTTP header to an internal buffer which will be written to the output stream when either end_headers() or flush_headers() is invoked. keyword should specify the header keyword, with value specifying its value. Note that, after the send_header calls are done, end_headers() MUST BE called in order to complete the operation.
Changed in version 3.2: Headers are stored in an internal buffer.


Adds a response header to the headers buffer and logs the accepted request. The HTTP response line is written to the internal buffer, followed by Server and Date headers. The values for these two headers are picked up from the version_string() and date_time_string() methods, respectively. If the server does not intend to send any other headers using the send_header() method, then send_response() should be followed by an end_headers() call.
Changed in version 3.3: Headers are stored to an internal buffer and end_headers() needs to be called explicitly.


Sends the response header only, used for the purposes when 100
Continue response is sent by the server to the client. The headers not buffered and sent directly the output stream.If the message is not specified, the HTTP message corresponding the response code is sent.
New in version 3.2.


Specifies the server software version. You may want to override this. The format is multiple whitespace-separated strings, where each string is of the form name[/version]. For example, 'BaseHTTP/0.2'.


Contains the Python system version, in a form usable by the version_string method and the server_version class variable. For example, 'Python/1.4'.


Returns the server software’s version string. This is a combination of the server_version and sys_version attributes.


Contains the output stream for writing a response back to the client. Proper adherence to the HTTP protocol must be used when writing to this stream in order to achieve successful interoperation with HTTP clients.
Changed in version 3.6: This is an io.BufferedIOBase stream.


This class is used to serve either files or output of CGI scripts from the current directory and below. Note that mapping HTTP hierarchic structure to local directory structure is exactly as in SimpleHTTPRequestHandler.
Note
CGI scripts run by the CGIHTTPRequestHandler class cannot execute redirects (HTTP code 302), because code 200 (script output follows) is sent prior to execution of the CGI script. This pre-empts the status code.
The class will however, run the CGI script, instead of serving it as a file, if it guesses it to be a CGI script. Only directory-based CGI are used — the other common server configuration is to treat special extensions as denoting CGI scripts.
The do_GET() and do_HEAD() functions are modified to run CGI scripts and serve the output, instead of serving files, if the request leads to somewhere below the cgi_directories path.
The CGIHTTPRequestHandler defines the following data member:
This defaults to ['/cgi-bin', '/htbin'] and describes directories to treat as containing CGI scripts.
The CGIHTTPRequestHandler defines the following method:
This method serves the 'POST' request type, only allowed for CGI scripts. Error 501, “Can only POST to CGI scripts”, is output when trying to POST to a non-CGI url.
Note that CGI scripts will be run with UID of user nobody, for security reasons. Problems with the CGI script will be translated to error 403.


This defaults to ['/cgi-bin', '/htbin'] and describes directories to treat as containing CGI scripts.


This method serves the 'POST' request type, only allowed for CGI scripts. Error 501, “Can only POST to CGI scripts”, is output when trying to POST to a non-CGI url.


This class builds on the TCPServer class by storing the server address as instance variables named server_name and server_port. The server is accessible by the handler, typically through the handler’s server instance variable.


This class serves files from the current directory and below, directly mapping the directory structure to HTTP requests.
A lot of the work, such as parsing the request, is done by the base class BaseHTTPRequestHandler. This class implements the do_GET() and do_HEAD() functions.
The following are defined as class-level attributes of SimpleHTTPRequestHandler:
This will be "SimpleHTTP/" + __version__, where __version__ is defined at the module level.
A dictionary mapping suffixes into MIME types, contains custom overrides for the default system mappings. The mapping is used case-insensitively, and so should contain only lower-cased keys.
Changed in version 3.9: This dictionary is no longer filled with the default system mappings, but only contains overrides.
If not specified, the directory to serve is the current working directory.
Changed in version 3.9: Accepts a path-like object.
The SimpleHTTPRequestHandler class defines the following methods:
This method serves the 'HEAD' request type: it sends the headers it would send for the equivalent GET request. See the do_GET() method for a more complete explanation of the possible headers.
The request is mapped to a local file by interpreting the request as a path relative to the current working directory.
If the request was mapped to a directory, the directory is checked for a file named index.html or index.htm (in that order). If found, the file’s contents are returned; otherwise a directory listing is generated by calling the list_directory() method. This method uses os.listdir() to scan the directory, and returns a 404 error response if the listdir() fails.
If the request was mapped to a file, it is opened. Any OSError exception in opening the requested file is mapped to a 404, 'File not found' error. If there was a 'If-Modified-Since' header in the request, and the file was not modified after this time, a 304, 'Not Modified' response is sent. Otherwise, the content type is guessed by calling the guess_type() method, which in turn uses the extensions_map variable, and the file contents are returned.
A 'Content-type:' header with the guessed content type is output, followed by a 'Content-Length:' header with the file’s size and a 'Last-Modified:' header with the file’s modification time.
Then follows a blank line signifying the end of the headers, and then the contents of the file are output. If the file’s MIME type starts with text/ the file is opened in text mode; otherwise binary mode is used.
For example usage, see the implementation of the test() function invocation in the http.server module.
Changed in version 3.7: Support of the 'If-Modified-Since' header.


If not specified, the directory to serve is the current working directory.
Changed in version 3.9: Accepts a path-like object.


The request is mapped to a local file by interpreting the request as a path relative to the current working directory.
If the request was mapped to a directory, the directory is checked for a file named index.html or index.htm (in that order). If found, the file’s contents are returned; otherwise a directory listing is generated by calling the list_directory() method. This method uses os.listdir() to scan the directory, and returns a 404 error response if the listdir() fails.
If the request was mapped to a file, it is opened. Any OSError exception in opening the requested file is mapped to a 404, 'File not found' error. If there was a 'If-Modified-Since' header in the request, and the file was not modified after this time, a 304, 'Not Modified' response is sent. Otherwise, the content type is guessed by calling the guess_type() method, which in turn uses the extensions_map variable, and the file contents are returned.
A 'Content-type:' header with the guessed content type is output, followed by a 'Content-Length:' header with the file’s size and a 'Last-Modified:' header with the file’s modification time.
Then follows a blank line signifying the end of the headers, and then the contents of the file are output. If the file’s MIME type starts with text/ the file is opened in text mode; otherwise binary mode is used.
For example usage, see the implementation of the test() function invocation in the http.server module.
Changed in version 3.7: Support of the 'If-Modified-Since' header.


This method serves the 'HEAD' request type: it sends the headers it would send for the equivalent GET request. See the do_GET() method for a more complete explanation of the possible headers.


A dictionary mapping suffixes into MIME types, contains custom overrides for the default system mappings. The mapping is used case-insensitively, and so should contain only lower-cased keys.
Changed in version 3.9: This dictionary is no longer filled with the default system mappings, but only contains overrides.


This will be "SimpleHTTP/" + __version__, where __version__ is defined at the module level.


This class is identical to HTTPServer but uses threads to handle requests by using the ThreadingMixIn. This is useful to handle web browsers pre-opening sockets, on which HTTPServer would wait indefinitely.
New in version 3.7.


Return the “identity” of an object. This is an integer which is guaranteed to be unique and constant for this object during its lifetime. Two objects with non-overlapping lifetimes may have the same id() value.
CPython implementation detail: This is the address of the object in memory.
Raises an auditing event builtins.id with argument id.