Requests: Python HTTP for Humans

Requests provides several high-level features for modern web interaction, including:

• Connection Management: Keep-Alive & Connection Pooling, Connection Timeouts, and Chunked Requests.
• Security: Browser-style SSL Verification, Basic/Digest Authentication, and HTTP(S) Proxy Support.
• Data Handling: Automatic Content Decoding, Automatic Decompression, Unicode Response Bodies, and Multipart File Uploads.
• Session & State: Sessions with Cookie Persistence and Elegant Key/Value Cookies.
• URL & Domain Support: International Domains and URLs, and .netrc support.
• Downloads: Streaming Downloads.

When accessing Response.text, Requests attempts to guess the encoding:

1. It first checks the HTTP header for an encoding.
2. If absent, it uses charset_normalizer or chardet to guess.

Special Case (RFC 2616): If no explicit charset is present in headers AND the Content-Type header contains text, Requests defaults to ISO-8859-1.

To override this, you can manually set Response.encoding or use Response.content for raw bytes.

If no auth argument is provided, Requests attempts to retrieve credentials for the URL's hostname from the user's .netrc file.

Requests searches for the file at:

• ~/.netrc (Unix/macOS)
• ~/_netrc (Unix/macOS)
• %USERPROFILE%/.netrc (Windows)
• The path specified by the NETRC environment variable.

If credentials are found, the request is sent using HTTP Basic Auth. This behavior overrides raw HTTP authentication headers set via headers=.

To disable this behavior in a session, set trust_env to False.

import requests

# Disable netrc/environment variable lookup
s = requests.Session()
s.trust_env = False
s.get('https://httpbin.org/basic-auth/user/pass')

Requests automatically decompresses gzip-encoded responses and attempts to decode response content to Unicode whenever possible.

To enable automatic decoding of Brotli-encoded responses, you must have either the brotli or brotlicffi package installed in your environment.

If you require low-level access, you can access the raw response or the underlying socket directly.

Every call to requests.get() (or similar methods) involves two main components:

1. A Request object: The object constructed to query the resource.
2. A Response object: The object generated containing the server's response and the original Request object.

You can access the headers sent to the server by inspecting response.request.headers, and the headers received from the server via response.headers.

import requests

r = requests.get('https://en.wikipedia.org/wiki/Monty_Python')

# Access headers sent to the server
print(r.request.headers)

# Access headers received from the server
print(r.headers)

Transport Adapters allow you to define per-service configuration by mounting an adapter to a Session object. When a request URL matches the adapter's prefix (using longest prefix match), that adapter is used.

Note: To avoid accidental matches (e.g., http://localhost matching http://localhost.other.com), it is recommended to terminate hostnames with a / (e.g., https://github.com/).

s = requests.Session()
s.mount('https://github.com/', MyAdapter())

Requests is an elegant and simple HTTP library for Python that allows you to send HTTP/1.1 requests easily. It automates tasks like adding query strings to URLs, form-encoding POST data, and managing keep-alive and connection pooling via urllib3.

>>> import requests
>>> r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
'utf-8'
>>> r.text
'{"type":"User"...'
>>> r.json()
{'private_gists': 419, 'total_private_repos': 77, ...}

Documentation improvements are welcome. Documentation files are located in the docs/ directory and are written in reStructuredText using Sphinx for generation.

Style Guidelines:

• Width: Maintain a soft-limit of 79 characters per line.
• Tone: Use a semi-formal, friendly, and approachable prose style.
• Python Code: When presenting Python code snippets, use single-quoted strings (e.g., 'hello' instead of "hello").