[
{
"path": ".github/CONTRIBUTING.md",
"content": "# Contributing\n\nThank you for being interested in contributing to HTTPX.\nThere are many ways you can contribute to the project:\n\n- Try HTTPX and [report bugs/issues you find](https://github.com/encode/httpx/issues/new)\n- [Implement new features](https://github.com/encode/httpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)\n- [Review Pull Requests of others](https://github.com/encode/httpx/pulls)\n- Write documentation\n- Participate in discussions\n\n## Reporting Bugs or Other Issues\n\nFound something that HTTPX should support?\nStumbled upon some unexpected behaviour?\n\nContributions should generally start out with [a discussion](https://github.com/encode/httpx/discussions).\nPossible bugs may be raised as a \"Potential Issue\" discussion, feature requests may\nbe raised as an \"Ideas\" discussion. We can then determine if the discussion needs\nto be escalated into an \"Issue\" or not, or if we'd consider a pull request.\n\nTry to be more descriptive as you can and in case of a bug report,\nprovide as much information as possible like:\n\n- OS platform\n- Python version\n- Installed dependencies and versions (`python -m pip freeze`)\n- Code snippet\n- Error traceback\n\nYou should always try to reduce any examples to the *simplest possible case*\nthat demonstrates the issue.\n\nSome possibly useful tips for narrowing down potential issues...\n\n- Does the issue exist on HTTP/1.1, or HTTP/2, or both?\n- Does the issue exist with `Client`, `AsyncClient`, or both?\n- When using `AsyncClient` does the issue exist when using `asyncio` or `trio`, or both?\n\n## Development\n\nTo start developing HTTPX create a **fork** of the\n[HTTPX repository](https://github.com/encode/httpx) on GitHub.\n\nThen clone your fork with the following command replacing `YOUR-USERNAME` with\nyour GitHub username:\n\n```shell\n$ git clone https://github.com/YOUR-USERNAME/httpx\n```\n\nYou can now install the project and its dependencies using:\n\n```shell\n$ cd httpx\n$ scripts/install\n```\n\n## Testing and Linting\n\nWe use custom shell scripts to automate testing, linting,\nand documentation building workflow.\n\nTo run the tests, use:\n\n```shell\n$ scripts/test\n```\n\n!!! warning\n The test suite spawns testing servers on ports **8000** and **8001**.\n Make sure these are not in use, so the tests can run properly.\n\nYou can run a single test script like this:\n\n```shell\n$ scripts/test -- tests/test_multipart.py\n```\n\nTo run the code auto-formatting:\n\n```shell\n$ scripts/lint\n```\n\nLastly, to run code checks separately (they are also run as part of `scripts/test`), run:\n\n```shell\n$ scripts/check\n```\n\n## Documenting\n\nDocumentation pages are located under the `docs/` folder.\n\nTo run the documentation site locally (useful for previewing changes), use:\n\n```shell\n$ scripts/docs\n```\n\n## Resolving Build / CI Failures\n\nOnce you've submitted your pull request, the test suite will automatically run, and the results will show up in GitHub.\nIf the test suite fails, you'll want to click through to the \"Details\" link, and try to identify why the test suite failed.\n\n
\n \n
\n\nHere are some common ways the test suite can fail:\n\n### Check Job Failed\n\n
\n \n
\n\nThis job failing means there is either a code formatting issue or type-annotation issue.\nYou can look at the job output to figure out why it's failed or within a shell run:\n\n```shell\n$ scripts/check\n```\n\nIt may be worth it to run `$ scripts/lint` to attempt auto-formatting the code\nand if that job succeeds commit the changes.\n\n### Docs Job Failed\n\nThis job failing means the documentation failed to build. This can happen for\na variety of reasons like invalid markdown or missing configuration within `mkdocs.yml`.\n\n### Python 3.X Job Failed\n\n
\n\nHTTPX is a fully featured HTTP client library for Python 3. It includes **an integrated command line client**, has support for both **HTTP/1.1 and HTTP/2**, and provides both **sync and async APIs**.\n\n---\n\nInstall HTTPX using pip:\n\n```shell\n$ pip install httpx\n```\n\nNow, let's get started:\n\n```pycon\n>>> import httpx\n>>> r = httpx.get('https://www.example.org/')\n>>> r\n\n>>> r.status_code\n200\n>>> r.headers['content-type']\n'text/html; charset=UTF-8'\n>>> r.text\n'\\n\\n\\nExample Domain...'\n```\n\nOr, using the command-line client.\n\n```shell\n$ pip install 'httpx[cli]' # The command line client is an optional dependency.\n```\n\nWhich now allows us to use HTTPX directly from the command-line...\n\n
\n \n
\n\nSending a request...\n\n
\n \n
\n\n## Features\n\nHTTPX builds on the well-established usability of `requests`, and gives you:\n\n* A broadly [requests-compatible API](https://www.python-httpx.org/compatibility/).\n* An integrated command-line client.\n* HTTP/1.1 [and HTTP/2 support](https://www.python-httpx.org/http2/).\n* Standard synchronous interface, but with [async support if you need it](https://www.python-httpx.org/async/).\n* Ability to make requests directly to [WSGI applications](https://www.python-httpx.org/advanced/transports/#wsgi-transport) or [ASGI applications](https://www.python-httpx.org/advanced/transports/#asgi-transport).\n* Strict timeouts everywhere.\n* Fully type annotated.\n* 100% test coverage.\n\nPlus all the standard features of `requests`...\n\n* International Domains and URLs\n* Keep-Alive & Connection Pooling\n* Sessions with Cookie Persistence\n* Browser-style SSL Verification\n* Basic/Digest Authentication\n* Elegant Key/Value Cookies\n* Automatic Decompression\n* Automatic Content Decoding\n* Unicode Response Bodies\n* Multipart File Uploads\n* HTTP(S) Proxy Support\n* Connection Timeouts\n* Streaming Downloads\n* .netrc Support\n* Chunked Requests\n\n## Installation\n\nInstall with pip:\n\n```shell\n$ pip install httpx\n```\n\nOr, to include the optional HTTP/2 support, use:\n\n```shell\n$ pip install httpx[http2]\n```\n\nHTTPX requires Python 3.9+.\n\n## Documentation\n\nProject documentation is available at [https://www.python-httpx.org/](https://www.python-httpx.org/).\n\nFor a run-through of all the basics, head over to the [QuickStart](https://www.python-httpx.org/quickstart/).\n\nFor more advanced topics, see the [Advanced Usage](https://www.python-httpx.org/advanced/) section, the [async support](https://www.python-httpx.org/async/) section, or the [HTTP/2](https://www.python-httpx.org/http2/) section.\n\nThe [Developer Interface](https://www.python-httpx.org/api/) provides a comprehensive API reference.\n\nTo find out about tools that integrate with HTTPX, see [Third Party Packages](https://www.python-httpx.org/third_party_packages/).\n\n## Contribute\n\nIf you want to contribute with HTTPX check out the [Contributing Guide](https://www.python-httpx.org/contributing/) to learn how to start.\n\n## Dependencies\n\nThe HTTPX project relies on these excellent libraries:\n\n* `httpcore` - The underlying transport implementation for `httpx`.\n * `h11` - HTTP/1.1 support.\n* `certifi` - SSL certificates.\n* `idna` - Internationalized domain name support.\n* `sniffio` - Async library autodetection.\n\nAs well as these optional installs:\n\n* `h2` - HTTP/2 support. *(Optional, with `httpx[http2]`)*\n* `socksio` - SOCKS proxy support. *(Optional, with `httpx[socks]`)*\n* `rich` - Rich terminal support. *(Optional, with `httpx[cli]`)*\n* `click` - Command line client support. *(Optional, with `httpx[cli]`)*\n* `brotli` or `brotlicffi` - Decoding for \"brotli\" compressed responses. *(Optional, with `httpx[brotli]`)*\n* `zstandard` - Decoding for \"zstd\" compressed responses. *(Optional, with `httpx[zstd]`)*\n\nA huge amount of credit is due to `requests` for the API layout that\nmuch of this work follows, as well as to `urllib3` for plenty of design\ninspiration around the lower-level networking details.\n\n---\n\n
HTTPX is BSD licensed code. Designed & crafted with care. — 🦋 —
\n"
},
{
"path": "docs/CNAME",
"content": "www.python-httpx.org\n"
},
{
"path": "docs/advanced/authentication.md",
"content": "Authentication can either be included on a per-request basis...\n\n```pycon\n>>> auth = httpx.BasicAuth(username=\"username\", password=\"secret\")\n>>> client = httpx.Client()\n>>> response = client.get(\"https://www.example.com/\", auth=auth)\n```\n\nOr configured on the client instance, ensuring that all outgoing requests will include authentication credentials...\n\n```pycon\n>>> auth = httpx.BasicAuth(username=\"username\", password=\"secret\")\n>>> client = httpx.Client(auth=auth)\n>>> response = client.get(\"https://www.example.com/\")\n```\n\n## Basic authentication\n\nHTTP basic authentication is an unencrypted authentication scheme that uses a simple encoding of the username and password in the request `Authorization` header. Since it is unencrypted it should typically only be used over `https`, although this is not strictly enforced.\n\n```pycon\n>>> auth = httpx.BasicAuth(username=\"finley\", password=\"secret\")\n>>> client = httpx.Client(auth=auth)\n>>> response = client.get(\"https://httpbin.org/basic-auth/finley/secret\")\n>>> response\n\n```\n\n## Digest authentication\n\nHTTP digest authentication is a challenge-response authentication scheme. Unlike basic authentication it provides encryption, and can be used over unencrypted `http` connections. It requires an additional round-trip in order to negotiate the authentication. \n\n```pycon\n>>> auth = httpx.DigestAuth(username=\"olivia\", password=\"secret\")\n>>> client = httpx.Client(auth=auth)\n>>> response = client.get(\"https://httpbin.org/digest-auth/auth/olivia/secret\")\n>>> response\n\n>>> response.history\n[]\n```\n\n## NetRC authentication\n\nHTTPX can be configured to use [a `.netrc` config file](https://everything.curl.dev/usingcurl/netrc) for authentication.\n\nThe `.netrc` config file allows authentication credentials to be associated with specified hosts. When a request is made to a host that is found in the netrc file, the username and password will be included using HTTP basic authentication.\n\nExample `.netrc` file:\n\n```\nmachine example.org\nlogin example-username\npassword example-password\n\nmachine python-httpx.org\nlogin other-username\npassword other-password\n```\n\nSome examples of configuring `.netrc` authentication with `httpx`.\n\nUse the default `.netrc` file in the users home directory:\n\n```pycon\n>>> auth = httpx.NetRCAuth()\n>>> client = httpx.Client(auth=auth)\n```\n\nUse an explicit path to a `.netrc` file:\n\n```pycon\n>>> auth = httpx.NetRCAuth(file=\"/path/to/.netrc\")\n>>> client = httpx.Client(auth=auth)\n```\n\nUse the `NETRC` environment variable to configure a path to the `.netrc` file,\nor fallback to the default.\n\n```pycon\n>>> auth = httpx.NetRCAuth(file=os.environ.get(\"NETRC\"))\n>>> client = httpx.Client(auth=auth)\n```\n\nThe `NetRCAuth()` class uses [the `netrc.netrc()` function from the Python standard library](https://docs.python.org/3/library/netrc.html). See the documentation there for more details on exceptions that may be raised if the `.netrc` file is not found, or cannot be parsed.\n\n## Custom authentication schemes\n\nWhen issuing requests or instantiating a client, the `auth` argument can be used to pass an authentication scheme to use. The `auth` argument may be one of the following...\n\n* A two-tuple of `username`/`password`, to be used with basic authentication.\n* An instance of `httpx.BasicAuth()`, `httpx.DigestAuth()`, or `httpx.NetRCAuth()`.\n* A callable, accepting a request and returning an authenticated request instance.\n* An instance of subclasses of `httpx.Auth`.\n\nThe most involved of these is the last, which allows you to create authentication flows involving one or more requests. A subclass of `httpx.Auth` should implement `def auth_flow(request)`, and yield any requests that need to be made...\n\n```python\nclass MyCustomAuth(httpx.Auth):\n def __init__(self, token):\n self.token = token\n\n def auth_flow(self, request):\n # Send the request, with a custom `X-Authentication` header.\n request.headers['X-Authentication'] = self.token\n yield request\n```\n\nIf the auth flow requires more than one request, you can issue multiple yields, and obtain the response in each case...\n\n```python\nclass MyCustomAuth(httpx.Auth):\n def __init__(self, token):\n self.token = token\n\n def auth_flow(self, request):\n response = yield request\n if response.status_code == 401:\n # If the server issues a 401 response then resend the request,\n # with a custom `X-Authentication` header.\n request.headers['X-Authentication'] = self.token\n yield request\n```\n\nCustom authentication classes are designed to not perform any I/O, so that they may be used with both sync and async client instances. If you are implementing an authentication scheme that requires the request body, then you need to indicate this on the class using a `requires_request_body` property.\n\nYou will then be able to access `request.content` inside the `.auth_flow()` method.\n\n```python\nclass MyCustomAuth(httpx.Auth):\n requires_request_body = True\n\n def __init__(self, token):\n self.token = token\n\n def auth_flow(self, request):\n response = yield request\n if response.status_code == 401:\n # If the server issues a 401 response then resend the request,\n # with a custom `X-Authentication` header.\n request.headers['X-Authentication'] = self.sign_request(...)\n yield request\n\n def sign_request(self, request):\n # Create a request signature, based on `request.method`, `request.url`,\n # `request.headers`, and `request.content`.\n ...\n```\n\nSimilarly, if you are implementing a scheme that requires access to the response body, then use the `requires_response_body` property. You will then be able to access response body properties and methods such as `response.content`, `response.text`, `response.json()`, etc.\n\n```python\nclass MyCustomAuth(httpx.Auth):\n requires_response_body = True\n\n def __init__(self, access_token, refresh_token, refresh_url):\n self.access_token = access_token\n self.refresh_token = refresh_token\n self.refresh_url = refresh_url\n\n def auth_flow(self, request):\n request.headers[\"X-Authentication\"] = self.access_token\n response = yield request\n\n if response.status_code == 401:\n # If the server issues a 401 response, then issue a request to\n # refresh tokens, and resend the request.\n refresh_response = yield self.build_refresh_request()\n self.update_tokens(refresh_response)\n\n request.headers[\"X-Authentication\"] = self.access_token\n yield request\n\n def build_refresh_request(self):\n # Return an `httpx.Request` for refreshing tokens.\n ...\n\n def update_tokens(self, response):\n # Update the `.access_token` and `.refresh_token` tokens\n # based on a refresh response.\n data = response.json()\n ...\n```\n\nIf you _do_ need to perform I/O other than HTTP requests, such as accessing a disk-based cache, or you need to use concurrency primitives, such as locks, then you should override `.sync_auth_flow()` and `.async_auth_flow()` (instead of `.auth_flow()`). The former will be used by `httpx.Client`, while the latter will be used by `httpx.AsyncClient`.\n\n```python\nimport asyncio\nimport threading\nimport httpx\n\n\nclass MyCustomAuth(httpx.Auth):\n def __init__(self):\n self._sync_lock = threading.RLock()\n self._async_lock = asyncio.Lock()\n\n def sync_get_token(self):\n with self._sync_lock:\n ...\n\n def sync_auth_flow(self, request):\n token = self.sync_get_token()\n request.headers[\"Authorization\"] = f\"Token {token}\"\n yield request\n\n async def async_get_token(self):\n async with self._async_lock:\n ...\n\n async def async_auth_flow(self, request):\n token = await self.async_get_token()\n request.headers[\"Authorization\"] = f\"Token {token}\"\n yield request\n```\n\nIf you only want to support one of the two methods, then you should still override it, but raise an explicit `RuntimeError`.\n\n```python\nimport httpx\nimport sync_only_library\n\n\nclass MyCustomAuth(httpx.Auth):\n def sync_auth_flow(self, request):\n token = sync_only_library.get_token(...)\n request.headers[\"Authorization\"] = f\"Token {token}\"\n yield request\n\n async def async_auth_flow(self, request):\n raise RuntimeError(\"Cannot use a sync authentication class with httpx.AsyncClient\")\n```"
},
{
"path": "docs/advanced/clients.md",
"content": "!!! hint\n If you are coming from Requests, `httpx.Client()` is what you can use instead of `requests.Session()`.\n\n## Why use a Client?\n\n!!! note \"TL;DR\"\n If you do anything more than experimentation, one-off scripts, or prototypes, then you should use a `Client` instance.\n\n**More efficient usage of network resources**\n\nWhen you make requests using the top-level API as documented in the [Quickstart](../quickstart.md) guide, HTTPX has to establish a new connection _for every single request_ (connections are not reused). As the number of requests to a host increases, this quickly becomes inefficient.\n\nOn the other hand, a `Client` instance uses [HTTP connection pooling](https://en.wikipedia.org/wiki/HTTP_persistent_connection). This means that when you make several requests to the same host, the `Client` will reuse the underlying TCP connection, instead of recreating one for every single request.\n\nThis can bring **significant performance improvements** compared to using the top-level API, including:\n\n- Reduced latency across requests (no handshaking).\n- Reduced CPU usage and round-trips.\n- Reduced network congestion.\n\n**Extra features**\n\n`Client` instances also support features that aren't available at the top-level API, such as:\n\n- Cookie persistence across requests.\n- Applying configuration across all outgoing requests.\n- Sending requests through HTTP proxies.\n- Using [HTTP/2](../http2.md).\n\nThe other sections on this page go into further detail about what you can do with a `Client` instance.\n\n## Usage\n\nThe recommended way to use a `Client` is as a context manager. This will ensure that connections are properly cleaned up when leaving the `with` block:\n\n```python\nwith httpx.Client() as client:\n ...\n```\n\nAlternatively, you can explicitly close the connection pool without block-usage using `.close()`:\n\n```python\nclient = httpx.Client()\ntry:\n ...\nfinally:\n client.close()\n```\n\n## Making requests\n\nOnce you have a `Client`, you can send requests using `.get()`, `.post()`, etc. For example:\n\n```pycon\n>>> with httpx.Client() as client:\n... r = client.get('https://example.com')\n...\n>>> r\n\n```\n\nThese methods accept the same arguments as `httpx.get()`, `httpx.post()`, etc. This means that all features documented in the [Quickstart](../quickstart.md) guide are also available at the client level.\n\nFor example, to send a request with custom headers:\n\n```pycon\n>>> with httpx.Client() as client:\n... headers = {'X-Custom': 'value'}\n... r = client.get('https://example.com', headers=headers)\n...\n>>> r.request.headers['X-Custom']\n'value'\n```\n\n## Sharing configuration across requests\n\nClients allow you to apply configuration to all outgoing requests by passing parameters to the `Client` constructor.\n\nFor example, to apply a set of custom headers _on every request_:\n\n```pycon\n>>> url = 'http://httpbin.org/headers'\n>>> headers = {'user-agent': 'my-app/0.0.1'}\n>>> with httpx.Client(headers=headers) as client:\n... r = client.get(url)\n...\n>>> r.json()['headers']['User-Agent']\n'my-app/0.0.1'\n```\n\n## Merging of configuration\n\nWhen a configuration option is provided at both the client-level and request-level, one of two things can happen:\n\n- For headers, query parameters and cookies, the values are combined together. For example:\n\n```pycon\n>>> headers = {'X-Auth': 'from-client'}\n>>> params = {'client_id': 'client1'}\n>>> with httpx.Client(headers=headers, params=params) as client:\n... headers = {'X-Custom': 'from-request'}\n... params = {'request_id': 'request1'}\n... r = client.get('https://example.com', headers=headers, params=params)\n...\n>>> r.request.url\nURL('https://example.com?client_id=client1&request_id=request1')\n>>> r.request.headers['X-Auth']\n'from-client'\n>>> r.request.headers['X-Custom']\n'from-request'\n```\n\n- For all other parameters, the request-level value takes priority. For example:\n\n```pycon\n>>> with httpx.Client(auth=('tom', 'mot123')) as client:\n... r = client.get('https://example.com', auth=('alice', 'ecila123'))\n...\n>>> _, _, auth = r.request.headers['Authorization'].partition(' ')\n>>> import base64\n>>> base64.b64decode(auth)\nb'alice:ecila123'\n```\n\nIf you need finer-grained control on the merging of client-level and request-level parameters, see [Request instances](#request-instances).\n\n## Other Client-only configuration options\n\nAdditionally, `Client` accepts some configuration options that aren't available at the request level.\n\nFor example, `base_url` allows you to prepend an URL to all outgoing requests:\n\n```pycon\n>>> with httpx.Client(base_url='http://httpbin.org') as client:\n... r = client.get('/headers')\n...\n>>> r.request.url\nURL('http://httpbin.org/headers')\n```\n\nFor a list of all available client parameters, see the [`Client`](../api.md#client) API reference.\n\n---\n\n## Request instances\n\nFor maximum control on what gets sent over the wire, HTTPX supports building explicit [`Request`](../api.md#request) instances:\n\n```python\nrequest = httpx.Request(\"GET\", \"https://example.com\")\n```\n\nTo dispatch a `Request` instance across to the network, create a [`Client` instance](#client-instances) and use `.send()`:\n\n```python\nwith httpx.Client() as client:\n response = client.send(request)\n ...\n```\n\nIf you need to mix client-level and request-level options in a way that is not supported by the default [Merging of parameters](#merging-of-parameters), you can use `.build_request()` and then make arbitrary modifications to the `Request` instance. For example:\n\n```python\nheaders = {\"X-Api-Key\": \"...\", \"X-Client-ID\": \"ABC123\"}\n\nwith httpx.Client(headers=headers) as client:\n request = client.build_request(\"GET\", \"https://api.example.com\")\n\n print(request.headers[\"X-Client-ID\"]) # \"ABC123\"\n\n # Don't send the API key for this particular request.\n del request.headers[\"X-Api-Key\"]\n\n response = client.send(request)\n ...\n```\n\n## Monitoring download progress\n\nIf you need to monitor download progress of large responses, you can use response streaming and inspect the `response.num_bytes_downloaded` property.\n\nThis interface is required for properly determining download progress, because the total number of bytes returned by `response.content` or `response.iter_content()` will not always correspond with the raw content length of the response if HTTP response compression is being used.\n\nFor example, showing a progress bar using the [`tqdm`](https://github.com/tqdm/tqdm) library while a response is being downloaded could be done like this…\n\n```python\nimport tempfile\n\nimport httpx\nfrom tqdm import tqdm\n\nwith tempfile.NamedTemporaryFile() as download_file:\n url = \"https://speed.hetzner.de/100MB.bin\"\n with httpx.stream(\"GET\", url) as response:\n total = int(response.headers[\"Content-Length\"])\n\n with tqdm(total=total, unit_scale=True, unit_divisor=1024, unit=\"B\") as progress:\n num_bytes_downloaded = response.num_bytes_downloaded\n for chunk in response.iter_bytes():\n download_file.write(chunk)\n progress.update(response.num_bytes_downloaded - num_bytes_downloaded)\n num_bytes_downloaded = response.num_bytes_downloaded\n```\n\n\n\nOr an alternate example, this time using the [`rich`](https://github.com/willmcgugan/rich) library…\n\n```python\nimport tempfile\nimport httpx\nimport rich.progress\n\nwith tempfile.NamedTemporaryFile() as download_file:\n url = \"https://speed.hetzner.de/100MB.bin\"\n with httpx.stream(\"GET\", url) as response:\n total = int(response.headers[\"Content-Length\"])\n\n with rich.progress.Progress(\n \"[progress.percentage]{task.percentage:>3.0f}%\",\n rich.progress.BarColumn(bar_width=None),\n rich.progress.DownloadColumn(),\n rich.progress.TransferSpeedColumn(),\n ) as progress:\n download_task = progress.add_task(\"Download\", total=total)\n for chunk in response.iter_bytes():\n download_file.write(chunk)\n progress.update(download_task, completed=response.num_bytes_downloaded)\n```\n\n\n\n## Monitoring upload progress\n\nIf you need to monitor upload progress of large responses, you can use request content generator streaming.\n\nFor example, showing a progress bar using the [`tqdm`](https://github.com/tqdm/tqdm) library.\n\n```python\nimport io\nimport random\n\nimport httpx\nfrom tqdm import tqdm\n\n\ndef gen():\n \"\"\"\n this is a complete example with generated random bytes.\n you can replace `io.BytesIO` with real file object.\n \"\"\"\n total = 32 * 1024 * 1024 # 32m\n with tqdm(ascii=True, unit_scale=True, unit='B', unit_divisor=1024, total=total) as bar:\n with io.BytesIO(random.randbytes(total)) as f:\n while data := f.read(1024):\n yield data\n bar.update(len(data))\n\n\nhttpx.post(\"https://httpbin.org/post\", content=gen())\n```\n\n\n\n## Multipart file encoding\n\nAs mentioned in the [quickstart](../quickstart.md#sending-multipart-file-uploads)\nmultipart file encoding is available by passing a dictionary with the\nname of the payloads as keys and either tuple of elements or a file-like object or a string as values.\n\n```pycon\n>>> with open('report.xls', 'rb') as report_file:\n... files = {'upload-file': ('report.xls', report_file, 'application/vnd.ms-excel')}\n... r = httpx.post(\"https://httpbin.org/post\", files=files)\n>>> print(r.text)\n{\n ...\n \"files\": {\n \"upload-file\": \"<... binary content ...>\"\n },\n ...\n}\n```\n\nMore specifically, if a tuple is used as a value, it must have between 2 and 3 elements:\n\n- The first element is an optional file name which can be set to `None`.\n- The second element may be a file-like object or a string which will be automatically\nencoded in UTF-8.\n- An optional third element can be used to specify the\n[MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_Types)\nof the file being uploaded. If not specified HTTPX will attempt to guess the MIME type based\non the file name, with unknown file extensions defaulting to \"application/octet-stream\".\nIf the file name is explicitly set to `None` then HTTPX will not include a content-type\nMIME header field.\n\n```pycon\n>>> files = {'upload-file': (None, 'text content', 'text/plain')}\n>>> r = httpx.post(\"https://httpbin.org/post\", files=files)\n>>> print(r.text)\n{\n ...\n \"files\": {},\n \"form\": {\n \"upload-file\": \"text-content\"\n },\n ...\n}\n```\n\n!!! tip\n It is safe to upload large files this way. File uploads are streaming by default, meaning that only one chunk will be loaded into memory at a time.\n\n Non-file data fields can be included in the multipart form using by passing them to `data=...`.\n\nYou can also send multiple files in one go with a multiple file field form.\nTo do that, pass a list of `(field, )` items instead of a dictionary, allowing you to pass multiple items with the same `field`.\nFor instance this request sends 2 files, `foo.png` and `bar.png` in one request on the `images` form field:\n\n```pycon\n>>> with open('foo.png', 'rb') as foo_file, open('bar.png', 'rb') as bar_file:\n... files = [\n... ('images', ('foo.png', foo_file, 'image/png')),\n... ('images', ('bar.png', bar_file, 'image/png')),\n... ]\n... r = httpx.post(\"https://httpbin.org/post\", files=files)\n```\n"
},
{
"path": "docs/advanced/event-hooks.md",
"content": "HTTPX allows you to register \"event hooks\" with the client, that are called\nevery time a particular type of event takes place.\n\nThere are currently two event hooks:\n\n* `request` - Called after a request is fully prepared, but before it is sent to the network. Passed the `request` instance.\n* `response` - Called after the response has been fetched from the network, but before it is returned to the caller. Passed the `response` instance.\n\nThese allow you to install client-wide functionality such as logging, monitoring or tracing.\n\n```python\ndef log_request(request):\n print(f\"Request event hook: {request.method} {request.url} - Waiting for response\")\n\ndef log_response(response):\n request = response.request\n print(f\"Response event hook: {request.method} {request.url} - Status {response.status_code}\")\n\nclient = httpx.Client(event_hooks={'request': [log_request], 'response': [log_response]})\n```\n\nYou can also use these hooks to install response processing code, such as this\nexample, which creates a client instance that always raises `httpx.HTTPStatusError`\non 4xx and 5xx responses.\n\n```python\ndef raise_on_4xx_5xx(response):\n response.raise_for_status()\n\nclient = httpx.Client(event_hooks={'response': [raise_on_4xx_5xx]})\n```\n\n!!! note\n Response event hooks are called before determining if the response body\n should be read or not.\n\n If you need access to the response body inside an event hook, you'll\n need to call `response.read()`, or for AsyncClients, `response.aread()`.\n\nThe hooks are also allowed to modify `request` and `response` objects.\n\n```python\ndef add_timestamp(request):\n request.headers['x-request-timestamp'] = datetime.now(tz=datetime.utc).isoformat()\n\nclient = httpx.Client(event_hooks={'request': [add_timestamp]})\n```\n\nEvent hooks must always be set as a **list of callables**, and you may register\nmultiple event hooks for each type of event.\n\nAs well as being able to set event hooks on instantiating the client, there\nis also an `.event_hooks` property, that allows you to inspect and modify\nthe installed hooks.\n\n```python\nclient = httpx.Client()\nclient.event_hooks['request'] = [log_request]\nclient.event_hooks['response'] = [log_response, raise_on_4xx_5xx]\n```\n\n!!! note\n If you are using HTTPX's async support, then you need to be aware that\n hooks registered with `httpx.AsyncClient` MUST be async functions,\n rather than plain functions.\n"
},
{
"path": "docs/advanced/extensions.md",
"content": "# Extensions\n\nRequest and response extensions provide a untyped space where additional information may be added.\n\nExtensions should be used for features that may not be available on all transports, and that do not fit neatly into [the simplified request/response model](https://www.encode.io/httpcore/extensions/) that the underlying `httpcore` package uses as its API.\n\nSeveral extensions are supported on the request:\n\n```python\n# Request timeouts actually implemented as an extension on\n# the request, ensuring that they are passed throughout the\n# entire call stack.\nclient = httpx.Client()\nresponse = client.get(\n \"https://www.example.com\",\n extensions={\"timeout\": {\"connect\": 5.0}}\n)\nresponse.request.extensions[\"timeout\"]\n{\"connect\": 5.0}\n```\n\nAnd on the response:\n\n```python\nclient = httpx.Client()\nresponse = client.get(\"https://www.example.com\")\nprint(response.extensions[\"http_version\"]) # b\"HTTP/1.1\"\n# Other server responses could have been\n# b\"HTTP/0.9\", b\"HTTP/1.0\", or b\"HTTP/1.1\"\n```\n\n## Request Extensions\n\n### `\"trace\"`\n\nThe trace extension allows a callback handler to be installed to monitor the internal\nflow of events within the underlying `httpcore` transport.\n\nThe simplest way to explain this is with an example:\n\n```python\nimport httpx\n\ndef log(event_name, info):\n print(event_name, info)\n\nclient = httpx.Client()\nresponse = client.get(\"https://www.example.com/\", extensions={\"trace\": log})\n# connection.connect_tcp.started {'host': 'www.example.com', 'port': 443, 'local_address': None, 'timeout': None}\n# connection.connect_tcp.complete {'return_value': }\n# connection.start_tls.started {'ssl_context': , 'server_hostname': b'www.example.com', 'timeout': None}\n# connection.start_tls.complete {'return_value': }\n# http11.send_request_headers.started {'request': }\n# http11.send_request_headers.complete {'return_value': None}\n# http11.send_request_body.started {'request': }\n# http11.send_request_body.complete {'return_value': None}\n# http11.receive_response_headers.started {'request': }\n# http11.receive_response_headers.complete {'return_value': (b'HTTP/1.1', 200, b'OK', [(b'Age', b'553715'), (b'Cache-Control', b'max-age=604800'), (b'Content-Type', b'text/html; charset=UTF-8'), (b'Date', b'Thu, 21 Oct 2021 17:08:42 GMT'), (b'Etag', b'\"3147526947+ident\"'), (b'Expires', b'Thu, 28 Oct 2021 17:08:42 GMT'), (b'Last-Modified', b'Thu, 17 Oct 2019 07:18:26 GMT'), (b'Server', b'ECS (nyb/1DCD)'), (b'Vary', b'Accept-Encoding'), (b'X-Cache', b'HIT'), (b'Content-Length', b'1256')])}\n# http11.receive_response_body.started {'request': }\n# http11.receive_response_body.complete {'return_value': None}\n# http11.response_closed.started {}\n# http11.response_closed.complete {'return_value': None}\n```\n\nThe `event_name` and `info` arguments here will be one of the following:\n\n* `{event_type}.{event_name}.started`, ``\n* `{event_type}.{event_name}.complete`, `{\"return_value\": <...>}`\n* `{event_type}.{event_name}.failed`, `{\"exception\": <...>}`\n\nNote that when using async code the handler function passed to `\"trace\"` must be an `async def ...` function.\n\nThe following event types are currently exposed...\n\n**Establishing the connection**\n\n* `\"connection.connect_tcp\"`\n* `\"connection.connect_unix_socket\"`\n* `\"connection.start_tls\"`\n\n**HTTP/1.1 events**\n\n* `\"http11.send_request_headers\"`\n* `\"http11.send_request_body\"`\n* `\"http11.receive_response\"`\n* `\"http11.receive_response_body\"`\n* `\"http11.response_closed\"`\n\n**HTTP/2 events**\n\n* `\"http2.send_connection_init\"`\n* `\"http2.send_request_headers\"`\n* `\"http2.send_request_body\"`\n* `\"http2.receive_response_headers\"`\n* `\"http2.receive_response_body\"`\n* `\"http2.response_closed\"`\n\nThe exact set of trace events may be subject to change across different versions of `httpcore`. If you need to rely on a particular set of events it is recommended that you pin installation of the package to a fixed version.\n\n### `\"sni_hostname\"`\n\nThe server's hostname, which is used to confirm the hostname supplied by the SSL certificate.\n\nIf you want to connect to an explicit IP address rather than using the standard DNS hostname lookup, then you'll need to use this request extension.\n\nFor example:\n\n``` python\n# Connect to '185.199.108.153' but use 'www.encode.io' in the Host header,\n# and use 'www.encode.io' when SSL verifying the server hostname.\nclient = httpx.Client()\nheaders = {\"Host\": \"www.encode.io\"}\nextensions = {\"sni_hostname\": \"www.encode.io\"}\nresponse = client.get(\n \"https://185.199.108.153/path\",\n headers=headers,\n extensions=extensions\n)\n```\n\n### `\"timeout\"`\n\nA dictionary of `str: Optional[float]` timeout values.\n\nMay include values for `'connect'`, `'read'`, `'write'`, or `'pool'`.\n\nFor example:\n\n```python\n# Timeout if a connection takes more than 5 seconds to established, or if\n# we are blocked waiting on the connection pool for more than 10 seconds.\nclient = httpx.Client()\nresponse = client.get(\n \"https://www.example.com\",\n extensions={\"timeout\": {\"connect\": 5.0, \"pool\": 10.0}}\n)\n```\n\nThis extension is how the `httpx` timeouts are implemented, ensuring that the timeout values are associated with the request instance and passed throughout the stack. You shouldn't typically be working with this extension directly, but use the higher level `timeout` API instead.\n\n### `\"target\"`\n\nThe target that is used as [the HTTP target instead of the URL path](https://datatracker.ietf.org/doc/html/rfc2616#section-5.1.2).\n\nThis enables support constructing requests that would otherwise be unsupported.\n\n* URL paths with non-standard escaping applied.\n* Forward proxy requests using an absolute URI.\n* Tunneling proxy requests using `CONNECT` with hostname as the target.\n* Server-wide `OPTIONS *` requests.\n\nSome examples:\n\nUsing the 'target' extension to send requests without the standard path escaping rules...\n\n```python\n# Typically a request to \"https://www.example.com/test^path\" would\n# connect to \"www.example.com\" and send an HTTP/1.1 request like...\n#\n# GET /test%5Epath HTTP/1.1\n#\n# Using the target extension we can include the literal '^'...\n#\n# GET /test^path HTTP/1.1\n#\n# Note that requests must still be valid HTTP requests.\n# For example including whitespace in the target will raise a `LocalProtocolError`.\nextensions = {\"target\": b\"/test^path\"}\nresponse = httpx.get(\"https://www.example.com\", extensions=extensions)\n```\n\nThe `target` extension also allows server-wide `OPTIONS *` requests to be constructed...\n\n```python\n# This will send the following request...\n#\n# CONNECT * HTTP/1.1\nextensions = {\"target\": b\"*\"}\nresponse = httpx.request(\"CONNECT\", \"https://www.example.com\", extensions=extensions)\n```\n\n## Response Extensions\n\n### `\"http_version\"`\n\nThe HTTP version, as bytes. Eg. `b\"HTTP/1.1\"`.\n\nWhen using HTTP/1.1 the response line includes an explicit version, and the value of this key could feasibly be one of `b\"HTTP/0.9\"`, `b\"HTTP/1.0\"`, or `b\"HTTP/1.1\"`.\n\nWhen using HTTP/2 there is no further response versioning included in the protocol, and the value of this key will always be `b\"HTTP/2\"`.\n\n### `\"reason_phrase\"`\n\nThe reason-phrase of the HTTP response, as bytes. For example `b\"OK\"`. Some servers may include a custom reason phrase, although this is not recommended.\n\nHTTP/2 onwards does not include a reason phrase on the wire.\n\nWhen no key is included, a default based on the status code may be used.\n\n### `\"stream_id\"`\n\nWhen HTTP/2 is being used the `\"stream_id\"` response extension can be accessed to determine the ID of the data stream that the response was sent on.\n\n### `\"network_stream\"`\n\nThe `\"network_stream\"` extension allows developers to handle HTTP `CONNECT` and `Upgrade` requests, by providing an API that steps outside the standard request/response model, and can directly read or write to the network.\n\nThe interface provided by the network stream:\n\n* `read(max_bytes, timeout = None) -> bytes`\n* `write(buffer, timeout = None)`\n* `close()`\n* `start_tls(ssl_context, server_hostname = None, timeout = None) -> NetworkStream`\n* `get_extra_info(info) -> Any`\n\nThis API can be used as the foundation for working with HTTP proxies, WebSocket upgrades, and other advanced use-cases.\n\nSee the [network backends documentation](https://www.encode.io/httpcore/network-backends/) for more information on working directly with network streams.\n\n**Extra network information**\n\nThe network stream abstraction also allows access to various low-level information that may be exposed by the underlying socket:\n\n```python\nresponse = httpx.get(\"https://www.example.com\")\nnetwork_stream = response.extensions[\"network_stream\"]\n\nclient_addr = network_stream.get_extra_info(\"client_addr\")\nserver_addr = network_stream.get_extra_info(\"server_addr\")\nprint(\"Client address\", client_addr)\nprint(\"Server address\", server_addr)\n```\n\nThe socket SSL information is also available through this interface, although you need to ensure that the underlying connection is still open, in order to access it...\n\n```python\nwith httpx.stream(\"GET\", \"https://www.example.com\") as response:\n network_stream = response.extensions[\"network_stream\"]\n\n ssl_object = network_stream.get_extra_info(\"ssl_object\")\n print(\"TLS version\", ssl_object.version())\n```\n"
},
{
"path": "docs/advanced/proxies.md",
"content": "HTTPX supports setting up [HTTP proxies](https://en.wikipedia.org/wiki/Proxy_server#Web_proxy_servers) via the `proxy` parameter to be passed on client initialization or top-level API functions like `httpx.get(..., proxy=...)`.\n\n
\n \n Diagram of how a proxy works (source: Wikipedia). The left hand side \"Internet\" blob may be your HTTPX client requesting example.com through a proxy.\n
\n\n## HTTP Proxies\n\nTo route all traffic (HTTP and HTTPS) to a proxy located at `http://localhost:8030`, pass the proxy URL to the client...\n\n```python\nwith httpx.Client(proxy=\"http://localhost:8030\") as client:\n ...\n```\n\nFor more advanced use cases, pass a mounts `dict`. For example, to route HTTP and HTTPS requests to 2 different proxies, respectively located at `http://localhost:8030`, and `http://localhost:8031`, pass a `dict` of proxy URLs:\n\n```python\nproxy_mounts = {\n \"http://\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n \"https://\": httpx.HTTPTransport(proxy=\"http://localhost:8031\"),\n}\n\nwith httpx.Client(mounts=proxy_mounts) as client:\n ...\n```\n\nFor detailed information about proxy routing, see the [Routing](#routing) section.\n\n!!! tip \"Gotcha\"\n In most cases, the proxy URL for the `https://` key _should_ use the `http://` scheme (that's not a typo!).\n\n This is because HTTP proxying requires initiating a connection with the proxy server. While it's possible that your proxy supports doing it via HTTPS, most proxies only support doing it via HTTP.\n\n For more information, see [FORWARD vs TUNNEL](#forward-vs-tunnel).\n\n## Authentication\n\nProxy credentials can be passed as the `userinfo` section of the proxy URL. For example:\n\n```python\nwith httpx.Client(proxy=\"http://username:password@localhost:8030\") as client:\n ...\n```\n\n## Proxy mechanisms\n\n!!! note\n This section describes **advanced** proxy concepts and functionality.\n\n### FORWARD vs TUNNEL\n\nIn general, the flow for making an HTTP request through a proxy is as follows:\n\n1. The client connects to the proxy (initial connection request).\n2. The proxy transfers data to the server on your behalf.\n\nHow exactly step 2/ is performed depends on which of two proxying mechanisms is used:\n\n* **Forwarding**: the proxy makes the request for you, and sends back the response it obtained from the server.\n* **Tunnelling**: the proxy establishes a TCP connection to the server on your behalf, and the client reuses this connection to send the request and receive the response. This is known as an [HTTP Tunnel](https://en.wikipedia.org/wiki/HTTP_tunnel). This mechanism is how you can access websites that use HTTPS from an HTTP proxy (the client \"upgrades\" the connection to HTTPS by performing the TLS handshake with the server over the TCP connection provided by the proxy).\n\n### Troubleshooting proxies\n\nIf you encounter issues when setting up proxies, please refer to our [Troubleshooting guide](../troubleshooting.md#proxies).\n\n## SOCKS\n\nIn addition to HTTP proxies, `httpcore` also supports proxies using the SOCKS protocol.\nThis is an optional feature that requires an additional third-party library be installed before use.\n\nYou can install SOCKS support using `pip`:\n\n```shell\n$ pip install httpx[socks]\n```\n\nYou can now configure a client to make requests via a proxy using the SOCKS protocol:\n\n```python\nhttpx.Client(proxy='socks5://user:pass@host:port')\n```\n"
},
{
"path": "docs/advanced/resource-limits.md",
"content": "You can control the connection pool size using the `limits` keyword\nargument on the client. It takes instances of `httpx.Limits` which define:\n\n- `max_keepalive_connections`, number of allowable keep-alive connections, or `None` to always\nallow. (Defaults 20)\n- `max_connections`, maximum number of allowable connections, or `None` for no limits.\n(Default 100)\n- `keepalive_expiry`, time limit on idle keep-alive connections in seconds, or `None` for no limits. (Default 5)\n\n```python\nlimits = httpx.Limits(max_keepalive_connections=5, max_connections=10)\nclient = httpx.Client(limits=limits)\n```"
},
{
"path": "docs/advanced/ssl.md",
"content": "When making a request over HTTPS, HTTPX needs to verify the identity of the requested host. To do this, it uses a bundle of SSL certificates (a.k.a. CA bundle) delivered by a trusted certificate authority (CA).\n\n### Enabling and disabling verification\n\nBy default httpx will verify HTTPS connections, and raise an error for invalid SSL cases...\n\n```pycon\n>>> httpx.get(\"https://expired.badssl.com/\")\nhttpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: certificate has expired (_ssl.c:997)\n```\n\nYou can disable SSL verification completely and allow insecure requests...\n\n```pycon\n>>> httpx.get(\"https://expired.badssl.com/\", verify=False)\n\n```\n\n### Configuring client instances\n\nIf you're using a `Client()` instance you should pass any `verify=<...>` configuration when instantiating the client.\n\nBy default the [certifi CA bundle](https://certifiio.readthedocs.io/en/latest/) is used for SSL verification.\n\nFor more complex configurations you can pass an [SSL Context](https://docs.python.org/3/library/ssl.html) instance...\n\n```python\nimport certifi\nimport httpx\nimport ssl\n\n# This SSL context is equivalent to the default `verify=True`.\nctx = ssl.create_default_context(cafile=certifi.where())\nclient = httpx.Client(verify=ctx)\n```\n\nUsing [the `truststore` package](https://truststore.readthedocs.io/) to support system certificate stores...\n\n```python\nimport ssl\nimport truststore\nimport httpx\n\n# Use system certificate stores.\nctx = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)\nclient = httpx.Client(verify=ctx)\n```\n\nLoding an alternative certificate verification store using [the standard SSL context API](https://docs.python.org/3/library/ssl.html)...\n\n```python\nimport httpx\nimport ssl\n\n# Use an explicitly configured certificate store.\nctx = ssl.create_default_context(cafile=\"path/to/certs.pem\") # Either cafile or capath.\nclient = httpx.Client(verify=ctx)\n```\n\n### Client side certificates\n\nClient side certificates allow a remote server to verify the client. They tend to be used within private organizations to authenticate requests to remote servers.\n\nYou can specify client-side certificates, using the [`.load_cert_chain()`](https://docs.python.org/3/library/ssl.html#ssl.SSLContext.load_cert_chain) API...\n\n```python\nctx = ssl.create_default_context()\nctx.load_cert_chain(certfile=\"path/to/client.pem\") # Optionally also keyfile or password.\nclient = httpx.Client(verify=ctx)\n```\n\n### Working with `SSL_CERT_FILE` and `SSL_CERT_DIR`\n\n`httpx` does respect the `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables by default. For details, refer to [the section on the environment variables page](../environment_variables.md#ssl_cert_file).\n\n### Making HTTPS requests to a local server\n\nWhen making requests to local servers, such as a development server running on `localhost`, you will typically be using unencrypted HTTP connections.\n\nIf you do need to make HTTPS connections to a local server, for example to test an HTTPS-only service, you will need to create and use your own certificates. Here's one way to do it...\n\n1. Use [trustme](https://github.com/python-trio/trustme) to generate a pair of server key/cert files, and a client cert file.\n2. Pass the server key/cert files when starting your local server. (This depends on the particular web server you're using. For example, [Uvicorn](https://www.uvicorn.org) provides the `--ssl-keyfile` and `--ssl-certfile` options.)\n3. Configure `httpx` to use the certificates stored in `client.pem`.\n\n```python\nctx = ssl.create_default_context(cafile=\"client.pem\")\nclient = httpx.Client(verify=ctx)\n```\n"
},
{
"path": "docs/advanced/text-encodings.md",
"content": "When accessing `response.text`, we need to decode the response bytes into a unicode text representation.\n\nBy default `httpx` will use `\"charset\"` information included in the response `Content-Type` header to determine how the response bytes should be decoded into text.\n\nIn cases where no charset information is included on the response, the default behaviour is to assume \"utf-8\" encoding, which is by far the most widely used text encoding on the internet.\n\n## Using the default encoding\n\nTo understand this better let's start by looking at the default behaviour for text decoding...\n\n```python\nimport httpx\n# Instantiate a client with the default configuration.\nclient = httpx.Client()\n# Using the client...\nresponse = client.get(...)\nprint(response.encoding) # This will either print the charset given in\n # the Content-Type charset, or else \"utf-8\".\nprint(response.text) # The text will either be decoded with the Content-Type\n # charset, or using \"utf-8\".\n```\n\nThis is normally absolutely fine. Most servers will respond with a properly formatted Content-Type header, including a charset encoding. And in most cases where no charset encoding is included, UTF-8 is very likely to be used, since it is so widely adopted.\n\n## Using an explicit encoding\n\nIn some cases we might be making requests to a site where no character set information is being set explicitly by the server, but we know what the encoding is. In this case it's best to set the default encoding explicitly on the client.\n\n```python\nimport httpx\n# Instantiate a client with a Japanese character set as the default encoding.\nclient = httpx.Client(default_encoding=\"shift-jis\")\n# Using the client...\nresponse = client.get(...)\nprint(response.encoding) # This will either print the charset given in\n # the Content-Type charset, or else \"shift-jis\".\nprint(response.text) # The text will either be decoded with the Content-Type\n # charset, or using \"shift-jis\".\n```\n\n## Using auto-detection\n\nIn cases where the server is not reliably including character set information, and where we don't know what encoding is being used, we can enable auto-detection to make a best-guess attempt when decoding from bytes to text.\n\nTo use auto-detection you need to set the `default_encoding` argument to a callable instead of a string. This callable should be a function which takes the input bytes as an argument and returns the character set to use for decoding those bytes to text.\n\nThere are two widely used Python packages which both handle this functionality:\n\n* [`chardet`](https://chardet.readthedocs.io/) - This is a well established package, and is a port of [the auto-detection code in Mozilla](https://www-archive.mozilla.org/projects/intl/chardet.html).\n* [`charset-normalizer`](https://charset-normalizer.readthedocs.io/) - A newer package, motivated by `chardet`, with a different approach.\n\nLet's take a look at installing autodetection using one of these packages...\n\n```shell\n$ pip install httpx\n$ pip install chardet\n```\n\nOnce `chardet` is installed, we can configure a client to use character-set autodetection.\n\n```python\nimport httpx\nimport chardet\n\ndef autodetect(content):\n return chardet.detect(content).get(\"encoding\")\n\n# Using a client with character-set autodetection enabled.\nclient = httpx.Client(default_encoding=autodetect)\nresponse = client.get(...)\nprint(response.encoding) # This will either print the charset given in\n # the Content-Type charset, or else the auto-detected\n # character set.\nprint(response.text)\n```\n"
},
{
"path": "docs/advanced/timeouts.md",
"content": "HTTPX is careful to enforce timeouts everywhere by default.\n\nThe default behavior is to raise a `TimeoutException` after 5 seconds of\nnetwork inactivity.\n\n## Setting and disabling timeouts\n\nYou can set timeouts for an individual request:\n\n```python\n# Using the top-level API:\nhttpx.get('http://example.com/api/v1/example', timeout=10.0)\n\n# Using a client instance:\nwith httpx.Client() as client:\n client.get(\"http://example.com/api/v1/example\", timeout=10.0)\n```\n\nOr disable timeouts for an individual request:\n\n```python\n# Using the top-level API:\nhttpx.get('http://example.com/api/v1/example', timeout=None)\n\n# Using a client instance:\nwith httpx.Client() as client:\n client.get(\"http://example.com/api/v1/example\", timeout=None)\n```\n\n## Setting a default timeout on a client\n\nYou can set a timeout on a client instance, which results in the given\n`timeout` being used as the default for requests made with this client:\n\n```python\nclient = httpx.Client() # Use a default 5s timeout everywhere.\nclient = httpx.Client(timeout=10.0) # Use a default 10s timeout everywhere.\nclient = httpx.Client(timeout=None) # Disable all timeouts by default.\n```\n\n## Fine tuning the configuration\n\nHTTPX also allows you to specify the timeout behavior in more fine grained detail.\n\nThere are four different types of timeouts that may occur. These are **connect**,\n**read**, **write**, and **pool** timeouts.\n\n* The **connect** timeout specifies the maximum amount of time to wait until\na socket connection to the requested host is established. If HTTPX is unable to connect\nwithin this time frame, a `ConnectTimeout` exception is raised.\n* The **read** timeout specifies the maximum duration to wait for a chunk of\ndata to be received (for example, a chunk of the response body). If HTTPX is\nunable to receive data within this time frame, a `ReadTimeout` exception is raised.\n* The **write** timeout specifies the maximum duration to wait for a chunk of\ndata to be sent (for example, a chunk of the request body). If HTTPX is unable\nto send data within this time frame, a `WriteTimeout` exception is raised.\n* The **pool** timeout specifies the maximum duration to wait for acquiring\na connection from the connection pool. If HTTPX is unable to acquire a connection\nwithin this time frame, a `PoolTimeout` exception is raised. A related\nconfiguration here is the maximum number of allowable connections in the\nconnection pool, which is configured by the `limits` argument.\n\nYou can configure the timeout behavior for any of these values...\n\n```python\n# A client with a 60s timeout for connecting, and a 10s timeout elsewhere.\ntimeout = httpx.Timeout(10.0, connect=60.0)\nclient = httpx.Client(timeout=timeout)\n\nresponse = client.get('http://example.com/')\n```"
},
{
"path": "docs/advanced/transports.md",
"content": "HTTPX's `Client` also accepts a `transport` argument. This argument allows you\nto provide a custom Transport object that will be used to perform the actual\nsending of the requests.\n\n## HTTP Transport\n\nFor some advanced configuration you might need to instantiate a transport\nclass directly, and pass it to the client instance. One example is the\n`local_address` configuration which is only available via this low-level API.\n\n```pycon\n>>> import httpx\n>>> transport = httpx.HTTPTransport(local_address=\"0.0.0.0\")\n>>> client = httpx.Client(transport=transport)\n```\n\nConnection retries are also available via this interface. Requests will be retried the given number of times in case an `httpx.ConnectError` or an `httpx.ConnectTimeout` occurs, allowing smoother operation under flaky networks. If you need other forms of retry behaviors, such as handling read/write errors or reacting to `503 Service Unavailable`, consider general-purpose tools such as [tenacity](https://github.com/jd/tenacity).\n\n```pycon\n>>> import httpx\n>>> transport = httpx.HTTPTransport(retries=1)\n>>> client = httpx.Client(transport=transport)\n```\n\nSimilarly, instantiating a transport directly provides a `uds` option for\nconnecting via a Unix Domain Socket that is only available via this low-level API:\n\n```pycon\n>>> import httpx\n>>> # Connect to the Docker API via a Unix Socket.\n>>> transport = httpx.HTTPTransport(uds=\"/var/run/docker.sock\")\n>>> client = httpx.Client(transport=transport)\n>>> response = client.get(\"http://docker/info\")\n>>> response.json()\n{\"ID\": \"...\", \"Containers\": 4, \"Images\": 74, ...}\n```\n\n## WSGI Transport\n\nYou can configure an `httpx` client to call directly into a Python web application using the WSGI protocol.\n\nThis is particularly useful for two main use-cases:\n\n* Using `httpx` as a client inside test cases.\n* Mocking out external services during tests or in dev or staging environments.\n\n### Example\n\nHere's an example of integrating against a Flask application:\n\n```python\nfrom flask import Flask\nimport httpx\n\n\napp = Flask(__name__)\n\n@app.route(\"/\")\ndef hello():\n return \"Hello World!\"\n\ntransport = httpx.WSGITransport(app=app)\nwith httpx.Client(transport=transport, base_url=\"http://testserver\") as client:\n r = client.get(\"/\")\n assert r.status_code == 200\n assert r.text == \"Hello World!\"\n```\n\n### Configuration\n\nFor some more complex cases you might need to customize the WSGI transport. This allows you to:\n\n* Inspect 500 error responses rather than raise exceptions by setting `raise_app_exceptions=False`.\n* Mount the WSGI application at a subpath by setting `script_name` (WSGI).\n* Use a given client address for requests by setting `remote_addr` (WSGI).\n\nFor example:\n\n```python\n# Instantiate a client that makes WSGI requests with a client IP of \"1.2.3.4\".\ntransport = httpx.WSGITransport(app=app, remote_addr=\"1.2.3.4\")\nwith httpx.Client(transport=transport, base_url=\"http://testserver\") as client:\n ...\n```\n\n## ASGI Transport\n\nYou can configure an `httpx` client to call directly into an async Python web application using the ASGI protocol.\n\nThis is particularly useful for two main use-cases:\n\n* Using `httpx` as a client inside test cases.\n* Mocking out external services during tests or in dev or staging environments.\n\n### Example\n\nLet's take this Starlette application as an example:\n\n```python\nfrom starlette.applications import Starlette\nfrom starlette.responses import HTMLResponse\nfrom starlette.routing import Route\n\n\nasync def hello(request):\n return HTMLResponse(\"Hello World!\")\n\n\napp = Starlette(routes=[Route(\"/\", hello)])\n```\n\nWe can make requests directly against the application, like so:\n\n```python\ntransport = httpx.ASGITransport(app=app)\n\nasync with httpx.AsyncClient(transport=transport, base_url=\"http://testserver\") as client:\n r = await client.get(\"/\")\n assert r.status_code == 200\n assert r.text == \"Hello World!\"\n```\n\n### Configuration\n\nFor some more complex cases you might need to customise the ASGI transport. This allows you to:\n\n* Inspect 500 error responses rather than raise exceptions by setting `raise_app_exceptions=False`.\n* Mount the ASGI application at a subpath by setting `root_path`.\n* Use a given client address for requests by setting `client`.\n\nFor example:\n\n```python\n# Instantiate a client that makes ASGI requests with a client IP of \"1.2.3.4\",\n# on port 123.\ntransport = httpx.ASGITransport(app=app, client=(\"1.2.3.4\", 123))\nasync with httpx.AsyncClient(transport=transport, base_url=\"http://testserver\") as client:\n ...\n```\n\nSee [the ASGI documentation](https://asgi.readthedocs.io/en/latest/specs/www.html#connection-scope) for more details on the `client` and `root_path` keys.\n\n### ASGI startup and shutdown\n\nIt is not in the scope of HTTPX to trigger ASGI lifespan events of your app.\n\nHowever it is suggested to use `LifespanManager` from [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan#usage) in pair with `AsyncClient`.\n\n## Custom transports\n\nA transport instance must implement the low-level Transport API which deals\nwith sending a single request, and returning a response. You should either\nsubclass `httpx.BaseTransport` to implement a transport to use with `Client`,\nor subclass `httpx.AsyncBaseTransport` to implement a transport to\nuse with `AsyncClient`.\n\nAt the layer of the transport API we're using the familiar `Request` and\n`Response` models.\n\nSee the `handle_request` and `handle_async_request` docstrings for more details\non the specifics of the Transport API.\n\nA complete example of a custom transport implementation would be:\n\n```python\nimport json\nimport httpx\n\nclass HelloWorldTransport(httpx.BaseTransport):\n \"\"\"\n A mock transport that always returns a JSON \"Hello, world!\" response.\n \"\"\"\n\n def handle_request(self, request):\n return httpx.Response(200, json={\"text\": \"Hello, world!\"})\n```\n\nOr this example, which uses a custom transport and `httpx.Mounts` to always redirect `http://` requests.\n\n```python\nclass HTTPSRedirect(httpx.BaseTransport):\n \"\"\"\n A transport that always redirects to HTTPS.\n \"\"\"\n def handle_request(self, request):\n url = request.url.copy_with(scheme=\"https\")\n return httpx.Response(303, headers={\"Location\": str(url)})\n\n# A client where any `http` requests are always redirected to `https`\ntransport = httpx.Mounts({\n 'http://': HTTPSRedirect()\n 'https://': httpx.HTTPTransport()\n})\nclient = httpx.Client(transport=transport)\n```\n\nA useful pattern here is custom transport classes that wrap the default HTTP implementation. For example...\n\n```python\nclass DebuggingTransport(httpx.BaseTransport):\n def __init__(self, **kwargs):\n self._wrapper = httpx.HTTPTransport(**kwargs)\n\n def handle_request(self, request):\n print(f\">>> {request}\")\n response = self._wrapper.handle_request(request)\n print(f\"<<< {response}\")\n return response\n\n def close(self):\n self._wrapper.close()\n\ntransport = DebuggingTransport()\nclient = httpx.Client(transport=transport)\n```\n\nHere's another case, where we're using a round-robin across a number of different proxies...\n\n```python\nclass ProxyRoundRobin(httpx.BaseTransport):\n def __init__(self, proxies, **kwargs):\n self._transports = [\n httpx.HTTPTransport(proxy=proxy, **kwargs)\n for proxy in proxies\n ]\n self._idx = 0\n\n def handle_request(self, request):\n transport = self._transports[self._idx]\n self._idx = (self._idx + 1) % len(self._transports)\n return transport.handle_request(request)\n\n def close(self):\n for transport in self._transports:\n transport.close()\n\nproxies = [\n httpx.Proxy(\"http://127.0.0.1:8081\"),\n httpx.Proxy(\"http://127.0.0.1:8082\"),\n httpx.Proxy(\"http://127.0.0.1:8083\"),\n]\ntransport = ProxyRoundRobin(proxies=proxies)\nclient = httpx.Client(transport=transport)\n```\n\n## Mock transports\n\nDuring testing it can often be useful to be able to mock out a transport,\nand return pre-determined responses, rather than making actual network requests.\n\nThe `httpx.MockTransport` class accepts a handler function, which can be used\nto map requests onto pre-determined responses:\n\n```python\ndef handler(request):\n return httpx.Response(200, json={\"text\": \"Hello, world!\"})\n\n\n# Switch to a mock transport, if the TESTING environment variable is set.\nif os.environ.get('TESTING', '').upper() == \"TRUE\":\n transport = httpx.MockTransport(handler)\nelse:\n transport = httpx.HTTPTransport()\n\nclient = httpx.Client(transport=transport)\n```\n\nFor more advanced use-cases you might want to take a look at either [the third-party\nmocking library, RESPX](https://lundberg.github.io/respx/), or the [pytest-httpx library](https://github.com/Colin-b/pytest_httpx).\n\n## Mounting transports\n\nYou can also mount transports against given schemes or domains, to control\nwhich transport an outgoing request should be routed via, with [the same style\nused for specifying proxy routing](#routing).\n\n```python\nimport httpx\n\nclass HTTPSRedirectTransport(httpx.BaseTransport):\n \"\"\"\n A transport that always redirects to HTTPS.\n \"\"\"\n\n def handle_request(self, method, url, headers, stream, extensions):\n scheme, host, port, path = url\n if port is None:\n location = b\"https://%s%s\" % (host, path)\n else:\n location = b\"https://%s:%d%s\" % (host, port, path)\n stream = httpx.ByteStream(b\"\")\n headers = [(b\"location\", location)]\n extensions = {}\n return 303, headers, stream, extensions\n\n\n# A client where any `http` requests are always redirected to `https`\nmounts = {'http://': HTTPSRedirectTransport()}\nclient = httpx.Client(mounts=mounts)\n```\n\nA couple of other sketches of how you might take advantage of mounted transports...\n\nDisabling HTTP/2 on a single given domain...\n\n```python\nmounts = {\n \"all://\": httpx.HTTPTransport(http2=True),\n \"all://*example.org\": httpx.HTTPTransport()\n}\nclient = httpx.Client(mounts=mounts)\n```\n\nMocking requests to a given domain:\n\n```python\n# All requests to \"example.org\" should be mocked out.\n# Other requests occur as usual.\ndef handler(request):\n return httpx.Response(200, json={\"text\": \"Hello, World!\"})\n\nmounts = {\"all://example.org\": httpx.MockTransport(handler)}\nclient = httpx.Client(mounts=mounts)\n```\n\nAdding support for custom schemes:\n\n```python\n# Support URLs like \"file:///Users/sylvia_green/websites/new_client/index.html\"\nmounts = {\"file://\": FileSystemTransport()}\nclient = httpx.Client(mounts=mounts)\n```\n\n### Routing\n\nHTTPX provides a powerful mechanism for routing requests, allowing you to write complex rules that specify which transport should be used for each request.\n\nThe `mounts` dictionary maps URL patterns to HTTP transports. HTTPX matches requested URLs against URL patterns to decide which transport should be used, if any. Matching is done from most specific URL patterns (e.g. `https://:`) to least specific ones (e.g. `https://`).\n\nHTTPX supports routing requests based on **scheme**, **domain**, **port**, or a combination of these.\n\n### Wildcard routing\n\nRoute everything through a transport...\n\n```python\nmounts = {\n \"all://\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n}\n```\n\n### Scheme routing\n\nRoute HTTP requests through one transport, and HTTPS requests through another...\n\n```python\nmounts = {\n \"http://\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n \"https://\": httpx.HTTPTransport(proxy=\"http://localhost:8031\"),\n}\n```\n\n### Domain routing\n\nProxy all requests on domain \"example.com\", let other requests pass through...\n\n```python\nmounts = {\n \"all://example.com\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n}\n```\n\nProxy HTTP requests on domain \"example.com\", let HTTPS and other requests pass through...\n\n```python\nmounts = {\n \"http://example.com\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n}\n```\n\nProxy all requests to \"example.com\" and its subdomains, let other requests pass through...\n\n```python\nmounts = {\n \"all://*example.com\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n}\n```\n\nProxy all requests to strict subdomains of \"example.com\", let \"example.com\" and other requests pass through...\n\n```python\nmounts = {\n \"all://*.example.com\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n}\n```\n\n### Port routing\n\nProxy HTTPS requests on port 1234 to \"example.com\"...\n\n```python\nmounts = {\n \"https://example.com:1234\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n}\n```\n\nProxy all requests on port 1234...\n\n```python\nmounts = {\n \"all://*:1234\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n}\n```\n\n### No-proxy support\n\nIt is also possible to define requests that _shouldn't_ be routed through the transport.\n\nTo do so, pass `None` as the proxy URL. For example...\n\n```python\nmounts = {\n # Route requests through a proxy by default...\n \"all://\": httpx.HTTPTransport(proxy=\"http://localhost:8031\"),\n # Except those for \"example.com\".\n \"all://example.com\": None,\n}\n```\n\n### Complex configuration example\n\nYou can combine the routing features outlined above to build complex proxy routing configurations. For example...\n\n```python\nmounts = {\n # Route all traffic through a proxy by default...\n \"all://\": httpx.HTTPTransport(proxy=\"http://localhost:8030\"),\n # But don't use proxies for HTTPS requests to \"domain.io\"...\n \"https://domain.io\": None,\n # And use another proxy for requests to \"example.com\" and its subdomains...\n \"all://*example.com\": httpx.HTTPTransport(proxy=\"http://localhost:8031\"),\n # And yet another proxy if HTTP is used,\n # and the \"internal\" subdomain on port 5550 is requested...\n \"http://internal.example.com:5550\": httpx.HTTPTransport(proxy=\"http://localhost:8032\"),\n}\n```\n\n### Environment variables\n\nThere are also environment variables that can be used to control the dictionary of the client mounts. \nThey can be used to configure HTTP proxying for clients.\n\nSee documentation on [`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`](../environment_variables.md#http_proxy-https_proxy-all_proxy)\nand [`NO_PROXY`](../environment_variables.md#no_proxy) for more information.\n"
},
{
"path": "docs/api.md",
"content": "# Developer Interface\n\n## Helper Functions\n\n!!! note\n Only use these functions if you're testing HTTPX in a console\n or making a small number of requests. Using a `Client` will\n enable HTTP/2 and connection pooling for more efficient and\n long-lived connections.\n\n::: httpx.request\n :docstring:\n\n::: httpx.get\n :docstring:\n\n::: httpx.options\n :docstring:\n\n::: httpx.head\n :docstring:\n\n::: httpx.post\n :docstring:\n\n::: httpx.put\n :docstring:\n\n::: httpx.patch\n :docstring:\n\n::: httpx.delete\n :docstring:\n\n::: httpx.stream\n :docstring:\n\n## `Client`\n\n::: httpx.Client\n :docstring:\n :members: headers cookies params auth request get head options post put patch delete stream build_request send close\n\n## `AsyncClient`\n\n::: httpx.AsyncClient\n :docstring:\n :members: headers cookies params auth request get head options post put patch delete stream build_request send aclose\n\n\n## `Response`\n\n*An HTTP response.*\n\n* `def __init__(...)`\n* `.status_code` - **int**\n* `.reason_phrase` - **str**\n* `.http_version` - `\"HTTP/2\"` or `\"HTTP/1.1\"`\n* `.url` - **URL**\n* `.headers` - **Headers**\n* `.content` - **bytes**\n* `.text` - **str**\n* `.encoding` - **str**\n* `.is_redirect` - **bool**\n* `.request` - **Request**\n* `.next_request` - **Optional[Request]**\n* `.cookies` - **Cookies**\n* `.history` - **List[Response]**\n* `.elapsed` - **[timedelta](https://docs.python.org/3/library/datetime.html)**\n * The amount of time elapsed between sending the request and calling `close()` on the corresponding response received for that request.\n [total_seconds()](https://docs.python.org/3/library/datetime.html#datetime.timedelta.total_seconds) to correctly get\n the total elapsed seconds.\n* `def .raise_for_status()` - **Response**\n* `def .json()` - **Any**\n* `def .read()` - **bytes**\n* `def .iter_raw([chunk_size])` - **bytes iterator**\n* `def .iter_bytes([chunk_size])` - **bytes iterator**\n* `def .iter_text([chunk_size])` - **text iterator**\n* `def .iter_lines()` - **text iterator**\n* `def .close()` - **None**\n* `def .next()` - **Response**\n* `def .aread()` - **bytes**\n* `def .aiter_raw([chunk_size])` - **async bytes iterator**\n* `def .aiter_bytes([chunk_size])` - **async bytes iterator**\n* `def .aiter_text([chunk_size])` - **async text iterator**\n* `def .aiter_lines()` - **async text iterator**\n* `def .aclose()` - **None**\n* `def .anext()` - **Response**\n\n## `Request`\n\n*An HTTP request. Can be constructed explicitly for more control over exactly\nwhat gets sent over the wire.*\n\n```pycon\n>>> request = httpx.Request(\"GET\", \"https://example.org\", headers={'host': 'example.org'})\n>>> response = client.send(request)\n```\n\n* `def __init__(method, url, [params], [headers], [cookies], [content], [data], [files], [json], [stream])`\n* `.method` - **str**\n* `.url` - **URL**\n* `.content` - **byte**, **byte iterator**, or **byte async iterator**\n* `.headers` - **Headers**\n* `.cookies` - **Cookies**\n\n## `URL`\n\n*A normalized, IDNA supporting URL.*\n\n```pycon\n>>> url = URL(\"https://example.org/\")\n>>> url.host\n'example.org'\n```\n\n* `def __init__(url, **kwargs)`\n* `.scheme` - **str**\n* `.authority` - **str**\n* `.host` - **str**\n* `.port` - **int**\n* `.path` - **str**\n* `.query` - **str**\n* `.raw_path` - **str**\n* `.fragment` - **str**\n* `.is_ssl` - **bool**\n* `.is_absolute_url` - **bool**\n* `.is_relative_url` - **bool**\n* `def .copy_with([scheme], [authority], [path], [query], [fragment])` - **URL**\n\n## `Headers`\n\n*A case-insensitive multi-dict.*\n\n```pycon\n>>> headers = Headers({'Content-Type': 'application/json'})\n>>> headers['content-type']\n'application/json'\n```\n\n* `def __init__(self, headers, encoding=None)`\n* `def copy()` - **Headers**\n\n## `Cookies`\n\n*A dict-like cookie store.*\n\n```pycon\n>>> cookies = Cookies()\n>>> cookies.set(\"name\", \"value\", domain=\"example.org\")\n```\n\n* `def __init__(cookies: [dict, Cookies, CookieJar])`\n* `.jar` - **CookieJar**\n* `def extract_cookies(response)`\n* `def set_cookie_header(request)`\n* `def set(name, value, [domain], [path])`\n* `def get(name, [domain], [path])`\n* `def delete(name, [domain], [path])`\n* `def clear([domain], [path])`\n* *Standard mutable mapping interface*\n\n## `Proxy`\n\n*A configuration of the proxy server.*\n\n```pycon\n>>> proxy = Proxy(\"http://proxy.example.com:8030\")\n>>> client = Client(proxy=proxy)\n```\n\n* `def __init__(url, [ssl_context], [auth], [headers])`\n* `.url` - **URL**\n* `.auth` - **tuple[str, str]**\n* `.headers` - **Headers**\n* `.ssl_context` - **SSLContext**\n"
},
{
"path": "docs/async.md",
"content": "# Async Support\n\nHTTPX offers a standard synchronous API by default, but also gives you\nthe option of an async client if you need it.\n\nAsync is a concurrency model that is far more efficient than multi-threading,\nand can provide significant performance benefits and enable the use of\nlong-lived network connections such as WebSockets.\n\nIf you're working with an async web framework then you'll also want to use an\nasync client for sending outgoing HTTP requests.\n\n## Making Async requests\n\nTo make asynchronous requests, you'll need an `AsyncClient`.\n\n```pycon\n>>> async with httpx.AsyncClient() as client:\n... r = await client.get('https://www.example.com/')\n...\n>>> r\n\n```\n\n!!! tip\n Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.9+ with `python -m asyncio` to try this code interactively, as they support executing `async`/`await` expressions in the console.\n\n## API Differences\n\nIf you're using an async client then there are a few bits of API that\nuse async methods.\n\n### Making requests\n\nThe request methods are all async, so you should use `response = await client.get(...)` style for all of the following:\n\n* `AsyncClient.get(url, ...)`\n* `AsyncClient.options(url, ...)`\n* `AsyncClient.head(url, ...)`\n* `AsyncClient.post(url, ...)`\n* `AsyncClient.put(url, ...)`\n* `AsyncClient.patch(url, ...)`\n* `AsyncClient.delete(url, ...)`\n* `AsyncClient.request(method, url, ...)`\n* `AsyncClient.send(request, ...)`\n\n### Opening and closing clients\n\nUse `async with httpx.AsyncClient()` if you want a context-managed client...\n\n```python\nasync with httpx.AsyncClient() as client:\n ...\n```\n\n!!! warning\n In order to get the most benefit from connection pooling, make sure you're not instantiating multiple client instances - for example by using `async with` inside a \"hot loop\". This can be achieved either by having a single scoped client that's passed throughout wherever it's needed, or by having a single global client instance.\n\nAlternatively, use `await client.aclose()` if you want to close a client explicitly:\n\n```python\nclient = httpx.AsyncClient()\n...\nawait client.aclose()\n```\n\n### Streaming responses\n\nThe `AsyncClient.stream(method, url, ...)` method is an async context block.\n\n```pycon\n>>> client = httpx.AsyncClient()\n>>> async with client.stream('GET', 'https://www.example.com/') as response:\n... async for chunk in response.aiter_bytes():\n... ...\n```\n\nThe async response streaming methods are:\n\n* `Response.aread()` - For conditionally reading a response inside a stream block.\n* `Response.aiter_bytes()` - For streaming the response content as bytes.\n* `Response.aiter_text()` - For streaming the response content as text.\n* `Response.aiter_lines()` - For streaming the response content as lines of text.\n* `Response.aiter_raw()` - For streaming the raw response bytes, without applying content decoding.\n* `Response.aclose()` - For closing the response. You don't usually need this, since `.stream` block closes the response automatically on exit.\n\nFor situations when context block usage is not practical, it is possible to enter \"manual mode\" by sending a [`Request` instance](advanced/clients.md#request-instances) using `client.send(..., stream=True)`.\n\nExample in the context of forwarding the response to a streaming web endpoint with [Starlette](https://www.starlette.io):\n\n```python\nimport httpx\nfrom starlette.background import BackgroundTask\nfrom starlette.responses import StreamingResponse\n\nclient = httpx.AsyncClient()\n\nasync def home(request):\n req = client.build_request(\"GET\", \"https://www.example.com/\")\n r = await client.send(req, stream=True)\n return StreamingResponse(r.aiter_text(), background=BackgroundTask(r.aclose))\n```\n\n!!! warning\n When using this \"manual streaming mode\", it is your duty as a developer to make sure that `Response.aclose()` is called eventually. Failing to do so would leave connections open, most likely resulting in resource leaks down the line.\n\n### Streaming requests\n\nWhen sending a streaming request body with an `AsyncClient` instance, you should use an async bytes generator instead of a bytes generator:\n\n```python\nasync def upload_bytes():\n ... # yield byte content\n\nawait client.post(url, content=upload_bytes())\n```\n\n### Explicit transport instances\n\nWhen instantiating a transport instance directly, you need to use `httpx.AsyncHTTPTransport`.\n\nFor instance:\n\n```pycon\n>>> import httpx\n>>> transport = httpx.AsyncHTTPTransport(retries=1)\n>>> async with httpx.AsyncClient(transport=transport) as client:\n>>> ...\n```\n\n## Supported async environments\n\nHTTPX supports either `asyncio` or `trio` as an async environment.\n\nIt will auto-detect which of those two to use as the backend\nfor socket operations and concurrency primitives.\n\n### [AsyncIO](https://docs.python.org/3/library/asyncio.html)\n\nAsyncIO is Python's [built-in library](https://docs.python.org/3/library/asyncio.html)\nfor writing concurrent code with the async/await syntax.\n\n```python\nimport asyncio\nimport httpx\n\nasync def main():\n async with httpx.AsyncClient() as client:\n response = await client.get('https://www.example.com/')\n print(response)\n\nasyncio.run(main())\n```\n\n### [Trio](https://github.com/python-trio/trio)\n\nTrio is [an alternative async library](https://trio.readthedocs.io/en/stable/),\ndesigned around the [the principles of structured concurrency](https://en.wikipedia.org/wiki/Structured_concurrency).\n\n```python\nimport httpx\nimport trio\n\nasync def main():\n async with httpx.AsyncClient() as client:\n response = await client.get('https://www.example.com/')\n print(response)\n\ntrio.run(main)\n```\n\n!!! important\n The `trio` package must be installed to use the Trio backend.\n\n\n### [AnyIO](https://github.com/agronholm/anyio)\n\nAnyIO is an [asynchronous networking and concurrency library](https://anyio.readthedocs.io/) that works on top of either `asyncio` or `trio`. It blends in with native libraries of your chosen backend (defaults to `asyncio`).\n\n```python\nimport httpx\nimport anyio\n\nasync def main():\n async with httpx.AsyncClient() as client:\n response = await client.get('https://www.example.com/')\n print(response)\n\nanyio.run(main, backend='trio')\n```\n\n## Calling into Python Web Apps\n\nFor details on calling directly into ASGI applications, see [the `ASGITransport` docs](../advanced/transports#asgitransport)."
},
{
"path": "docs/code_of_conduct.md",
"content": "# Code of Conduct\n\nWe expect contributors to our projects and online spaces to follow [the Python Software Foundation’s Code of Conduct](https://www.python.org/psf/conduct/).\n\nThe Python community is made up of members from around the globe with a diverse set of skills, personalities, and experiences. It is through these differences that our community experiences great successes and continued growth. When you're working with members of the community, this Code of Conduct will help steer your interactions and keep Python a positive, successful, and growing community.\n\n## Our Community\n\nMembers of the Python community are **open, considerate, and respectful**. Behaviours that reinforce these values contribute to a positive environment, and include:\n\n* **Being open.** Members of the community are open to collaboration, whether it's on PEPs, patches, problems, or otherwise.\n* **Focusing on what is best for the community.** We're respectful of the processes set forth in the community, and we work within them.\n* **Acknowledging time and effort.** We're respectful of the volunteer efforts that permeate the Python community. We're thoughtful when addressing the efforts of others, keeping in mind that often times the labor was completed simply for the good of the community.\n* **Being respectful of differing viewpoints and experiences.** We're receptive to constructive comments and criticism, as the experiences and skill sets of other members contribute to the whole of our efforts.\n* **Showing empathy towards other community members.** We're attentive in our communications, whether in person or online, and we're tactful when approaching differing views.\n* **Being considerate.** Members of the community are considerate of their peers -- other Python users.\n* **Being respectful.** We're respectful of others, their positions, their skills, their commitments, and their efforts.\n* **Gracefully accepting constructive criticism.** When we disagree, we are courteous in raising our issues.\n* **Using welcoming and inclusive language.** We're accepting of all who wish to take part in our activities, fostering an environment where anyone can participate and everyone can make a difference.\n\n## Our Standards\n\nEvery member of our community has the right to have their identity respected. The Python community is dedicated to providing a positive experience for everyone, regardless of age, gender identity and expression, sexual orientation, disability, physical appearance, body size, ethnicity, nationality, race, or religion (or lack thereof), education, or socio-economic status.\n\n## Inappropriate Behavior\n\nExamples of unacceptable behavior by participants include:\n\n* Harassment of any participants in any form\n* Deliberate intimidation, stalking, or following\n* Logging or taking screenshots of online activity for harassment purposes\n* Publishing others' private information, such as a physical or electronic address, without explicit permission\n* Violent threats or language directed against another person\n* Incitement of violence or harassment towards any individual, including encouraging a person to commit suicide or to engage in self-harm\n* Creating additional online accounts in order to harass another person or circumvent a ban\n* Sexual language and imagery in online communities or in any conference venue, including talks\n* Insults, put downs, or jokes that are based upon stereotypes, that are exclusionary, or that hold others up for ridicule\n* Excessive swearing\n* Unwelcome sexual attention or advances\n* Unwelcome physical contact, including simulated physical contact (eg, textual descriptions like \"hug\" or \"backrub\") without consent or after a request to stop\n* Pattern of inappropriate social contact, such as requesting/assuming inappropriate levels of intimacy with others\n* Sustained disruption of online community discussions, in-person presentations, or other in-person events\n* Continued one-on-one communication after requests to cease\n* Other conduct that is inappropriate for a professional audience including people of many different backgrounds\n\nCommunity members asked to stop any inappropriate behavior are expected to comply immediately.\n\n## Enforcement\n\nWe take Code of Conduct violations seriously, and will act to ensure our spaces are welcoming, inclusive, and professional environments to communicate in.\n\nIf you need to raise a Code of Conduct report, you may do so privately by email to tom@tomchristie.com.\n\nReports will be treated confidentially.\n\nAlternately you may [make a report to the Python Software Foundation](https://www.python.org/psf/conduct/reporting/).\n"
},
{
"path": "docs/compatibility.md",
"content": "# Requests Compatibility Guide\n\nHTTPX aims to be broadly compatible with the `requests` API, although there are a\nfew design differences in places.\n\nThis documentation outlines places where the API differs...\n\n## Redirects\n\nUnlike `requests`, HTTPX does **not follow redirects by default**.\n\nWe differ in behaviour here [because auto-redirects can easily mask unnecessary network\ncalls being made](https://github.com/encode/httpx/discussions/1785).\n\nYou can still enable behaviour to automatically follow redirects, but you need to\ndo so explicitly...\n\n```python\nresponse = client.get(url, follow_redirects=True)\n```\n\nOr else instantiate a client, with redirect following enabled by default...\n\n```python\nclient = httpx.Client(follow_redirects=True)\n```\n\n## Client instances\n\nThe HTTPX equivalent of `requests.Session` is `httpx.Client`.\n\n```python\nsession = requests.Session(**kwargs)\n```\n\nis generally equivalent to\n\n```python\nclient = httpx.Client(**kwargs)\n```\n\n## Request URLs\n\nAccessing `response.url` will return a `URL` instance, rather than a string.\n\nUse `str(response.url)` if you need a string instance.\n\n## Determining the next redirect request\n\nThe `requests` library exposes an attribute `response.next`, which can be used to obtain the next redirect request.\n\n```python\nsession = requests.Session()\nrequest = requests.Request(\"GET\", ...).prepare()\nwhile request is not None:\n response = session.send(request, allow_redirects=False)\n request = response.next\n```\n\nIn HTTPX, this attribute is instead named `response.next_request`. For example:\n\n```python\nclient = httpx.Client()\nrequest = client.build_request(\"GET\", ...)\nwhile request is not None:\n response = client.send(request)\n request = response.next_request\n```\n\n## Request Content\n\nFor uploading raw text or binary content we prefer to use a `content` parameter,\nin order to better separate this usage from the case of uploading form data.\n\nFor example, using `content=...` to upload raw content:\n\n```python\n# Uploading text, bytes, or a bytes iterator.\nhttpx.post(..., content=b\"Hello, world\")\n```\n\nAnd using `data=...` to send form data:\n\n```python\n# Uploading form data.\nhttpx.post(..., data={\"message\": \"Hello, world\"})\n```\n\nUsing the `data=` will raise a deprecation warning,\nand is expected to be fully removed with the HTTPX 1.0 release.\n\n## Upload files\n\nHTTPX strictly enforces that upload files must be opened in binary mode, in order\nto avoid character encoding issues that can result from attempting to upload files\nopened in text mode.\n\n## Content encoding\n\nHTTPX uses `utf-8` for encoding `str` request bodies. For example, when using `content=` the request body will be encoded to `utf-8` before being sent over the wire. This differs from Requests which uses `latin1`. If you need an explicit encoding, pass encoded bytes explicitly, e.g. `content=.encode(\"latin1\")`.\nFor response bodies, assuming the server didn't send an explicit encoding then HTTPX will do its best to figure out an appropriate encoding. HTTPX makes a guess at the encoding to use for decoding the response using `charset_normalizer`. Fallback to that or any content with less than 32 octets will be decoded using `utf-8` with the `error=\"replace\"` decoder strategy.\n\n## Cookies\n\nIf using a client instance, then cookies should always be set on the client rather than on a per-request basis.\n\nThis usage is supported:\n\n```python\nclient = httpx.Client(cookies=...)\nclient.post(...)\n```\n\nThis usage is **not** supported:\n\n```python\nclient = httpx.Client()\nclient.post(..., cookies=...)\n```\n\nWe prefer enforcing a stricter API here because it provides clearer expectations around cookie persistence, particularly when redirects occur.\n\n## Status Codes\n\nIn our documentation we prefer the uppercased versions, such as `codes.NOT_FOUND`, but also provide lower-cased versions for API compatibility with `requests`.\n\nRequests includes various synonyms for status codes that HTTPX does not support.\n\n## Streaming responses\n\nHTTPX provides a `.stream()` interface rather than using `stream=True`. This ensures that streaming responses are always properly closed outside of the stream block, and makes it visually clearer at which points streaming I/O APIs may be used with a response.\n\nFor example:\n\n```python\nwith httpx.stream(\"GET\", \"https://www.example.com\") as response:\n ...\n```\n\nWithin a `stream()` block request data is made available with:\n\n* `.iter_bytes()` - Instead of `response.iter_content()`\n* `.iter_text()` - Instead of `response.iter_content(decode_unicode=True)`\n* `.iter_lines()` - Corresponding to `response.iter_lines()`\n* `.iter_raw()` - Use this instead of `response.raw`\n* `.read()` - Read the entire response body, making `response.text` and `response.content` available.\n\n## Timeouts\n\nHTTPX defaults to including reasonable [timeouts](quickstart.md#timeouts) for all network operations, while Requests has no timeouts by default.\n\nTo get the same behavior as Requests, set the `timeout` parameter to `None`:\n\n```python\nhttpx.get('https://www.example.com', timeout=None)\n```\n\n## Proxy keys\n\nHTTPX uses the mounts argument for HTTP proxying and transport routing.\nIt can do much more than proxies and allows you to configure more than just the proxy route.\nFor more detailed documentation, see [Mounting Transports](advanced/transports.md#mounting-transports).\n\nWhen using `httpx.Client(mounts={...})` to map to a selection of different transports, we use full URL schemes, such as `mounts={\"http://\": ..., \"https://\": ...}`.\n\nThis is different to the `requests` usage of `proxies={\"http\": ..., \"https\": ...}`.\n\nThis change is for better consistency with more complex mappings, that might also include domain names, such as `mounts={\"all://\": ..., httpx.HTTPTransport(proxy=\"all://www.example.com\": None})` which maps all requests onto a proxy, except for requests to \"www.example.com\" which have an explicit exclusion.\n\nAlso note that `requests.Session.request(...)` allows a `proxies=...` parameter, whereas `httpx.Client.request(...)` does not allow `mounts=...`.\n\n## SSL configuration\n\nWhen using a `Client` instance, the ssl configurations should always be passed on client instantiation, rather than passed to the request method.\n\nIf you need more than one different SSL configuration, you should use different client instances for each SSL configuration.\n\n## Request body on HTTP methods\n\nThe HTTP `GET`, `DELETE`, `HEAD`, and `OPTIONS` methods are specified as not supporting a request body. To stay in line with this, the `.get`, `.delete`, `.head` and `.options` functions do not support `content`, `files`, `data`, or `json` arguments.\n\nIf you really do need to send request data using these http methods you should use the generic `.request` function instead.\n\n```python\nhttpx.request(\n method=\"DELETE\",\n url=\"https://www.example.com/\",\n content=b'A request body on a DELETE request.'\n)\n```\n\n## Checking for success and failure responses\n\nWe don't support `response.is_ok` since the naming is ambiguous there, and might incorrectly imply an equivalence to `response.status_code == codes.OK`. Instead we provide the `response.is_success` property, which can be used to check for a 2xx response.\n\n## Request instantiation\n\nThere is no notion of [prepared requests](https://requests.readthedocs.io/en/stable/user/advanced/#prepared-requests) in HTTPX. If you need to customize request instantiation, see [Request instances](advanced/clients.md#request-instances).\n\nBesides, `httpx.Request()` does not support the `auth`, `timeout`, `follow_redirects`, `mounts`, `verify` and `cert` parameters. However these are available in `httpx.request`, `httpx.get`, `httpx.post` etc., as well as on [`Client` instances](advanced/clients.md#client-instances).\n\n## Mocking\n\nIf you need to mock HTTPX the same way that test utilities like `responses` and `requests-mock` does for `requests`, see [RESPX](https://github.com/lundberg/respx).\n\n## Caching\n\nIf you use `cachecontrol` or `requests-cache` to add HTTP Caching support to the `requests` library, you can use [Hishel](https://hishel.com) for HTTPX.\n\n## Networking layer\n\n`requests` defers most of its HTTP networking code to the excellent [`urllib3` library](https://urllib3.readthedocs.io/en/latest/).\n\nOn the other hand, HTTPX uses [HTTPCore](https://github.com/encode/httpcore) as its core HTTP networking layer, which is a different project than `urllib3`.\n\n## Query Parameters\n\n`requests` omits `params` whose values are `None` (e.g. `requests.get(..., params={\"foo\": None})`). This is not supported by HTTPX.\n\nFor both query params (`params=`) and form data (`data=`), `requests` supports sending a list of tuples (e.g. `requests.get(..., params=[('key1', 'value1'), ('key1', 'value2')])`). This is not supported by HTTPX. Instead, use a dictionary with lists as values. E.g.: `httpx.get(..., params={'key1': ['value1', 'value2']})` or with form data: `httpx.post(..., data={'key1': ['value1', 'value2']})`.\n\n## Event Hooks\n\n`requests` allows event hooks to mutate `Request` and `Response` objects. See [examples](https://requests.readthedocs.io/en/master/user/advanced/#event-hooks) given in the documentation for `requests`.\n\nIn HTTPX, event hooks may access properties of requests and responses, but event hook callbacks cannot mutate the original request/response.\n\nIf you are looking for more control, consider checking out [Custom Transports](advanced/transports.md#custom-transports).\n\n## Exceptions and Errors\n\n`requests` exception hierarchy is slightly different to the `httpx` exception hierarchy. `requests` exposes a top level `RequestException`, where as `httpx` exposes a top level `HTTPError`. see the exceptions exposes in requests [here](https://requests.readthedocs.io/en/latest/_modules/requests/exceptions/). See the `httpx` error hierarchy [here](https://www.python-httpx.org/exceptions/).\n"
},
{
"path": "docs/contributing.md",
"content": "# Contributing\n\nThank you for being interested in contributing to HTTPX.\nThere are many ways you can contribute to the project:\n\n- Try HTTPX and [report bugs/issues you find](https://github.com/encode/httpx/issues/new)\n- [Implement new features](https://github.com/encode/httpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)\n- [Review Pull Requests of others](https://github.com/encode/httpx/pulls)\n- Write documentation\n- Participate in discussions\n\n## Reporting Bugs or Other Issues\n\nFound something that HTTPX should support?\nStumbled upon some unexpected behaviour?\n\nContributions should generally start out with [a discussion](https://github.com/encode/httpx/discussions).\nPossible bugs may be raised as a \"Potential Issue\" discussion, feature requests may\nbe raised as an \"Ideas\" discussion. We can then determine if the discussion needs\nto be escalated into an \"Issue\" or not, or if we'd consider a pull request.\n\nTry to be more descriptive as you can and in case of a bug report,\nprovide as much information as possible like:\n\n- OS platform\n- Python version\n- Installed dependencies and versions (`python -m pip freeze`)\n- Code snippet\n- Error traceback\n\nYou should always try to reduce any examples to the *simplest possible case*\nthat demonstrates the issue.\n\nSome possibly useful tips for narrowing down potential issues...\n\n- Does the issue exist on HTTP/1.1, or HTTP/2, or both?\n- Does the issue exist with `Client`, `AsyncClient`, or both?\n- When using `AsyncClient` does the issue exist when using `asyncio` or `trio`, or both?\n\n## Development\n\nTo start developing HTTPX create a **fork** of the\n[HTTPX repository](https://github.com/encode/httpx) on GitHub.\n\nThen clone your fork with the following command replacing `YOUR-USERNAME` with\nyour GitHub username:\n\n```shell\n$ git clone https://github.com/YOUR-USERNAME/httpx\n```\n\nYou can now install the project and its dependencies using:\n\n```shell\n$ cd httpx\n$ scripts/install\n```\n\n## Testing and Linting\n\nWe use custom shell scripts to automate testing, linting,\nand documentation building workflow.\n\nTo run the tests, use:\n\n```shell\n$ scripts/test\n```\n\n!!! warning\n The test suite spawns testing servers on ports **8000** and **8001**.\n Make sure these are not in use, so the tests can run properly.\n\nAny additional arguments will be passed to `pytest`. See the [pytest documentation](https://docs.pytest.org/en/latest/how-to/usage.html) for more information.\n\nFor example, to run a single test script:\n\n```shell\n$ scripts/test tests/test_multipart.py\n```\n\nTo run the code auto-formatting:\n\n```shell\n$ scripts/lint\n```\n\nLastly, to run code checks separately (they are also run as part of `scripts/test`), run:\n\n```shell\n$ scripts/check\n```\n\n## Documenting\n\nDocumentation pages are located under the `docs/` folder.\n\nTo run the documentation site locally (useful for previewing changes), use:\n\n```shell\n$ scripts/docs\n```\n\n## Resolving Build / CI Failures\n\nOnce you've submitted your pull request, the test suite will automatically run, and the results will show up in GitHub.\nIf the test suite fails, you'll want to click through to the \"Details\" link, and try to identify why the test suite failed.\n\n
\n \n
\n\nHere are some common ways the test suite can fail:\n\n### Check Job Failed\n\n
\n \n
\n\nThis job failing means there is either a code formatting issue or type-annotation issue.\nYou can look at the job output to figure out why it's failed or within a shell run:\n\n```shell\n$ scripts/check\n```\n\nIt may be worth it to run `$ scripts/lint` to attempt auto-formatting the code\nand if that job succeeds commit the changes.\n\n### Docs Job Failed\n\nThis job failing means the documentation failed to build. This can happen for\na variety of reasons like invalid markdown or missing configuration within `mkdocs.yml`.\n\n### Python 3.X Job Failed\n\n
\n \n
\n\nThis job failing means the unit tests failed or not all code paths are covered by unit tests.\n\nIf tests are failing you will see this message under the coverage report:\n\n`=== 1 failed, 435 passed, 1 skipped, 1 xfailed in 11.09s ===`\n\nIf tests succeed but coverage doesn't reach our current threshold, you will see this\nmessage under the coverage report:\n\n`FAIL Required test coverage of 100% not reached. Total coverage: 99.00%`\n\n## Releasing\n\n*This section is targeted at HTTPX maintainers.*\n\nBefore releasing a new version, create a pull request that includes:\n\n- **An update to the changelog**:\n - We follow the format from [keepachangelog](https://keepachangelog.com/en/1.0.0/).\n - [Compare](https://github.com/encode/httpx/compare/) `master` with the tag of the latest release, and list all entries that are of interest to our users:\n - Things that **must** go in the changelog: added, changed, deprecated or removed features, and bug fixes.\n - Things that **should not** go in the changelog: changes to documentation, tests or tooling.\n - Try sorting entries in descending order of impact / importance.\n - Keep it concise and to-the-point. 🎯\n- **A version bump**: see `__version__.py`.\n\nFor an example, see [#1006](https://github.com/encode/httpx/pull/1006).\n\nOnce the release PR is merged, create a\n[new release](https://github.com/encode/httpx/releases/new) including:\n\n- Tag version like `0.13.3`.\n- Release title `Version 0.13.3`\n- Description copied from the changelog.\n\nOnce created this release will be automatically uploaded to PyPI.\n\nIf something goes wrong with the PyPI job the release can be published using the\n`scripts/publish` script.\n\n## Development proxy setup\n\nTo test and debug requests via a proxy it's best to run a proxy server locally.\nAny server should do but HTTPCore's test suite uses\n[`mitmproxy`](https://mitmproxy.org/) which is written in Python, it's fully\nfeatured and has excellent UI and tools for introspection of requests.\n\nYou can install `mitmproxy` using `pip install mitmproxy` or [several\nother ways](https://docs.mitmproxy.org/stable/overview-installation/).\n\n`mitmproxy` does require setting up local TLS certificates for HTTPS requests,\nas its main purpose is to allow developers to inspect requests that pass through\nit. We can set them up follows:\n\n1. [`pip install trustme-cli`](https://github.com/sethmlarson/trustme-cli/).\n2. `trustme-cli -i example.org www.example.org`, assuming you want to test\nconnecting to that domain, this will create three files: `server.pem`,\n`server.key` and `client.pem`.\n3. `mitmproxy` requires a PEM file that includes the private key and the\ncertificate so we need to concatenate them:\n`cat server.key server.pem > server.withkey.pem`.\n4. Start the proxy server `mitmproxy --certs server.withkey.pem`, or use the\n[other mitmproxy commands](https://docs.mitmproxy.org/stable/) with different\nUI options.\n\nAt this point the server is ready to start serving requests, you'll need to\nconfigure HTTPX as described in the\n[proxy section](https://www.python-httpx.org/advanced/proxies/#http-proxies) and\nthe [SSL certificates section](https://www.python-httpx.org/advanced/ssl/),\nthis is where our previously generated `client.pem` comes in:\n\n```python\nctx = ssl.create_default_context(cafile=\"/path/to/client.pem\")\nclient = httpx.Client(proxy=\"http://127.0.0.1:8080/\", verify=ctx)\n```\n\nNote, however, that HTTPS requests will only succeed to the host specified\nin the SSL/TLS certificate we generated, HTTPS requests to other hosts will\nraise an error like:\n\n```\nssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate\nverify failed: Hostname mismatch, certificate is not valid for\n'duckduckgo.com'. (_ssl.c:1108)\n```\n\nIf you want to make requests to more hosts you'll need to regenerate the\ncertificates and include all the hosts you intend to connect to in the\nseconds step, i.e.\n\n`trustme-cli -i example.org www.example.org duckduckgo.com www.duckduckgo.com`\n"
},
{
"path": "docs/css/custom.css",
"content": "div.autodoc-docstring {\n padding-left: 20px;\n margin-bottom: 30px;\n border-left: 5px solid rgba(230, 230, 230);\n}\n\ndiv.autodoc-members {\n padding-left: 20px;\n margin-bottom: 15px;\n}\n"
},
{
"path": "docs/environment_variables.md",
"content": "# Environment Variables\n\nThe HTTPX library can be configured via environment variables.\nEnvironment variables are used by default. To ignore environment variables, `trust_env` has to be set `False`. There are two ways to set `trust_env` to disable environment variables:\n\n* On the client via `httpx.Client(trust_env=False)`.\n* Using the top-level API, such as `httpx.get(\"\", trust_env=False)`.\n\nHere is a list of environment variables that HTTPX recognizes and what function they serve:\n\n## Proxies\n\nThe environment variables documented below are used as a convention by various HTTP tooling, including:\n\n* [cURL](https://github.com/curl/curl/blob/master/docs/MANUAL.md#environment-variables)\n* [requests](https://github.com/psf/requests/blob/master/docs/user/advanced.rst#proxies)\n\nFor more information on using proxies in HTTPX, see [HTTP Proxying](advanced/proxies.md#http-proxying).\n\n### `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`\n\nValid values: A URL to a proxy\n\n`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` set the proxy to be used for `http`, `https`, or all requests respectively.\n\n```bash\nexport HTTP_PROXY=http://my-external-proxy.com:1234\n\n# This request will be sent through the proxy\npython -c \"import httpx; httpx.get('http://example.com')\"\n\n# This request will be sent directly, as we set `trust_env=False`\npython -c \"import httpx; httpx.get('http://example.com', trust_env=False)\"\n\n```\n\n### `NO_PROXY`\n\nValid values: a comma-separated list of hostnames/urls\n\n`NO_PROXY` disables the proxy for specific urls\n\n```bash\nexport HTTP_PROXY=http://my-external-proxy.com:1234\nexport NO_PROXY=http://127.0.0.1,python-httpx.org\n\n# As in the previous example, this request will be sent through the proxy\npython -c \"import httpx; httpx.get('http://example.com')\"\n\n# These requests will be sent directly, bypassing the proxy\npython -c \"import httpx; httpx.get('http://127.0.0.1:5000/my-api')\"\npython -c \"import httpx; httpx.get('https://www.python-httpx.org')\"\n```\n\n## `SSL_CERT_FILE`\n\nValid values: a filename\n\nIf this environment variable is set then HTTPX will load\nCA certificate from the specified file instead of the default\nlocation.\n\nExample:\n\n```console\nSSL_CERT_FILE=/path/to/ca-certs/ca-bundle.crt python -c \"import httpx; httpx.get('https://example.com')\"\n```\n\n## `SSL_CERT_DIR`\n\nValid values: a directory following an [OpenSSL specific layout](https://www.openssl.org/docs/manmaster/man3/SSL_CTX_load_verify_locations.html).\n\nIf this environment variable is set and the directory follows an [OpenSSL specific layout](https://www.openssl.org/docs/manmaster/man3/SSL_CTX_load_verify_locations.html) (ie. you ran `c_rehash`) then HTTPX will load CA certificates from this directory instead of the default location.\n\nExample:\n\n```console\nSSL_CERT_DIR=/path/to/ca-certs/ python -c \"import httpx; httpx.get('https://example.com')\"\n```\n"
},
{
"path": "docs/exceptions.md",
"content": "# Exceptions\n\nThis page lists exceptions that may be raised when using HTTPX.\n\nFor an overview of how to work with HTTPX exceptions, see [Exceptions (Quickstart)](quickstart.md#exceptions).\n\n## The exception hierarchy\n\n* HTTPError\n * RequestError\n * TransportError\n * TimeoutException\n * ConnectTimeout\n * ReadTimeout\n * WriteTimeout\n * PoolTimeout\n * NetworkError\n * ConnectError\n * ReadError\n * WriteError\n * CloseError\n * ProtocolError\n * LocalProtocolError\n * RemoteProtocolError\n * ProxyError\n * UnsupportedProtocol\n * DecodingError\n * TooManyRedirects\n * HTTPStatusError\n* InvalidURL\n* CookieConflict\n* StreamError\n * StreamConsumed\n * ResponseNotRead\n * RequestNotRead\n * StreamClosed\n\n---\n\n## Exception classes\n\n::: httpx.HTTPError\n :docstring:\n\n::: httpx.RequestError\n :docstring:\n\n::: httpx.TransportError\n :docstring:\n\n::: httpx.TimeoutException\n :docstring:\n\n::: httpx.ConnectTimeout\n :docstring:\n\n::: httpx.ReadTimeout\n :docstring:\n\n::: httpx.WriteTimeout\n :docstring:\n\n::: httpx.PoolTimeout\n :docstring:\n\n::: httpx.NetworkError\n :docstring:\n\n::: httpx.ConnectError\n :docstring:\n\n::: httpx.ReadError\n :docstring:\n\n::: httpx.WriteError\n :docstring:\n\n::: httpx.CloseError\n :docstring:\n\n::: httpx.ProtocolError\n :docstring:\n\n::: httpx.LocalProtocolError\n :docstring:\n\n::: httpx.RemoteProtocolError\n :docstring:\n\n::: httpx.ProxyError\n :docstring:\n\n::: httpx.UnsupportedProtocol\n :docstring:\n\n::: httpx.DecodingError\n :docstring:\n\n::: httpx.TooManyRedirects\n :docstring:\n\n::: httpx.HTTPStatusError\n :docstring:\n\n::: httpx.InvalidURL\n :docstring:\n\n::: httpx.CookieConflict\n :docstring:\n\n::: httpx.StreamError\n :docstring:\n\n::: httpx.StreamConsumed\n :docstring:\n\n::: httpx.StreamClosed\n :docstring:\n\n::: httpx.ResponseNotRead\n :docstring:\n\n::: httpx.RequestNotRead\n :docstring:\n"
},
{
"path": "docs/http2.md",
"content": "# HTTP/2\n\nHTTP/2 is a major new iteration of the HTTP protocol, that provides a far more\nefficient transport, with potential performance benefits. HTTP/2 does not change\nthe core semantics of the request or response, but alters the way that data is\nsent to and from the server.\n\nRather than the text format that HTTP/1.1 uses, HTTP/2 is a binary format.\nThe binary format provides full request and response multiplexing, and efficient\ncompression of HTTP headers. The stream multiplexing means that where HTTP/1.1\nrequires one TCP stream for each concurrent request, HTTP/2 allows a single TCP\nstream to handle multiple concurrent requests.\n\nHTTP/2 also provides support for functionality such as response prioritization,\nand server push.\n\nFor a comprehensive guide to HTTP/2 you may want to check out \"[http2 explained](https://http2-explained.haxx.se/)\".\n\n## Enabling HTTP/2\n\nWhen using the `httpx` client, HTTP/2 support is not enabled by default, because\nHTTP/1.1 is a mature, battle-hardened transport layer, and our HTTP/1.1\nimplementation may be considered the more robust option at this point in time.\nIt is possible that a future version of `httpx` may enable HTTP/2 support by default.\n\nIf you're issuing highly concurrent requests you might want to consider\ntrying out our HTTP/2 support. You can do so by first making sure to install\nthe optional HTTP/2 dependencies...\n\n```shell\n$ pip install httpx[http2]\n```\n\nAnd then instantiating a client with HTTP/2 support enabled:\n\n```python\nclient = httpx.AsyncClient(http2=True)\n...\n```\n\nYou can also instantiate a client as a context manager, to ensure that all\nHTTP connections are nicely scoped, and will be closed once the context block\nis exited.\n\n```python\nasync with httpx.AsyncClient(http2=True) as client:\n ...\n```\n\nHTTP/2 support is available on both `Client` and `AsyncClient`, although it's\ntypically more useful in async contexts if you're issuing lots of concurrent\nrequests.\n\n## Inspecting the HTTP version\n\nEnabling HTTP/2 support on the client does not *necessarily* mean that your\nrequests and responses will be transported over HTTP/2, since both the client\n*and* the server need to support HTTP/2. If you connect to a server that only\nsupports HTTP/1.1 the client will use a standard HTTP/1.1 connection instead.\n\nYou can determine which version of the HTTP protocol was used by examining\nthe `.http_version` property on the response.\n\n```python\nclient = httpx.AsyncClient(http2=True)\nresponse = await client.get(...)\nprint(response.http_version) # \"HTTP/1.0\", \"HTTP/1.1\", or \"HTTP/2\".\n```\n"
},
{
"path": "docs/index.md",
"content": "
\n\nHTTPX is a fully featured HTTP client for Python 3, which provides sync and async APIs, and support for both HTTP/1.1 and HTTP/2.\n\n---\n\nInstall HTTPX using pip:\n\n```shell\n$ pip install httpx\n```\n\nNow, let's get started:\n\n```pycon\n>>> import httpx\n>>> r = httpx.get('https://www.example.org/')\n>>> r\n\n>>> r.status_code\n200\n>>> r.headers['content-type']\n'text/html; charset=UTF-8'\n>>> r.text\n'\\n\\n\\nExample Domain...'\n```\n\nOr, using the command-line client.\n\n```shell\n# The command line client is an optional dependency.\n$ pip install 'httpx[cli]'\n```\n\nWhich now allows us to use HTTPX directly from the command-line...\n\n\n\nSending a request...\n\n\n\n## Features\n\nHTTPX builds on the well-established usability of `requests`, and gives you:\n\n* A broadly [requests-compatible API](compatibility.md).\n* Standard synchronous interface, but with [async support if you need it](async.md).\n* HTTP/1.1 [and HTTP/2 support](http2.md).\n* Ability to make requests directly to [WSGI applications](advanced/transports.md#wsgi-transport) or [ASGI applications](advanced/transports.md#asgi-transport).\n* Strict timeouts everywhere.\n* Fully type annotated.\n* 100% test coverage.\n\nPlus all the standard features of `requests`...\n\n* International Domains and URLs\n* Keep-Alive & Connection Pooling\n* Sessions with Cookie Persistence\n* Browser-style SSL Verification\n* Basic/Digest Authentication\n* Elegant Key/Value Cookies\n* Automatic Decompression\n* Automatic Content Decoding\n* Unicode Response Bodies\n* Multipart File Uploads\n* HTTP(S) Proxy Support\n* Connection Timeouts\n* Streaming Downloads\n* .netrc Support\n* Chunked Requests\n\n## Documentation\n\nFor a run-through of all the basics, head over to the [QuickStart](quickstart.md).\n\nFor more advanced topics, see the **Advanced** section,\nthe [async support](async.md) section, or the [HTTP/2](http2.md) section.\n\nThe [Developer Interface](api.md) provides a comprehensive API reference.\n\nTo find out about tools that integrate with HTTPX, see [Third Party Packages](third_party_packages.md).\n\n## Dependencies\n\nThe HTTPX project relies on these excellent libraries:\n\n* `httpcore` - The underlying transport implementation for `httpx`.\n * `h11` - HTTP/1.1 support.\n* `certifi` - SSL certificates.\n* `idna` - Internationalized domain name support.\n* `sniffio` - Async library autodetection.\n\nAs well as these optional installs:\n\n* `h2` - HTTP/2 support. *(Optional, with `httpx[http2]`)*\n* `socksio` - SOCKS proxy support. *(Optional, with `httpx[socks]`)*\n* `rich` - Rich terminal support. *(Optional, with `httpx[cli]`)*\n* `click` - Command line client support. *(Optional, with `httpx[cli]`)*\n* `brotli` or `brotlicffi` - Decoding for \"brotli\" compressed responses. *(Optional, with `httpx[brotli]`)*\n* `zstandard` - Decoding for \"zstd\" compressed responses. *(Optional, with `httpx[zstd]`)*\n\nA huge amount of credit is due to `requests` for the API layout that\nmuch of this work follows, as well as to `urllib3` for plenty of design\ninspiration around the lower-level networking details.\n\n## Installation\n\nInstall with pip:\n\n```shell\n$ pip install httpx\n```\n\nOr, to include the optional HTTP/2 support, use:\n\n```shell\n$ pip install httpx[http2]\n```\n\nTo include the optional brotli and zstandard decoders support, use:\n\n```shell\n$ pip install httpx[brotli,zstd]\n```\n\nHTTPX requires Python 3.9+\n\n[sync-support]: https://github.com/encode/httpx/issues/572\n"
},
{
"path": "docs/logging.md",
"content": "# Logging\n\nIf you need to inspect the internal behaviour of `httpx`, you can use Python's standard logging to output information about the underlying network behaviour.\n\nFor example, the following configuration...\n\n```python\nimport logging\nimport httpx\n\nlogging.basicConfig(\n format=\"%(levelname)s [%(asctime)s] %(name)s - %(message)s\",\n datefmt=\"%Y-%m-%d %H:%M:%S\",\n level=logging.DEBUG\n)\n\nhttpx.get(\"https://www.example.com\")\n```\n\nWill send debug level output to the console, or wherever `stdout` is directed too...\n\n```\nDEBUG [2024-09-28 17:27:40] httpcore.connection - connect_tcp.started host='www.example.com' port=443 local_address=None timeout=5.0 socket_options=None\nDEBUG [2024-09-28 17:27:41] httpcore.connection - connect_tcp.complete return_value=\nDEBUG [2024-09-28 17:27:41] httpcore.connection - start_tls.started ssl_context=SSLContext(verify=True) server_hostname='www.example.com' timeout=5.0\nDEBUG [2024-09-28 17:27:41] httpcore.connection - start_tls.complete return_value=\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - send_request_headers.started request=\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - send_request_headers.complete\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - send_request_body.started request=\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - send_request_body.complete\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - receive_response_headers.started request=\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - receive_response_headers.complete return_value=(b'HTTP/1.1', 200, b'OK', [(b'Content-Encoding', b'gzip'), (b'Accept-Ranges', b'bytes'), (b'Age', b'407727'), (b'Cache-Control', b'max-age=604800'), (b'Content-Type', b'text/html; charset=UTF-8'), (b'Date', b'Sat, 28 Sep 2024 13:27:42 GMT'), (b'Etag', b'\"3147526947+gzip\"'), (b'Expires', b'Sat, 05 Oct 2024 13:27:42 GMT'), (b'Last-Modified', b'Thu, 17 Oct 2019 07:18:26 GMT'), (b'Server', b'ECAcc (dcd/7D43)'), (b'Vary', b'Accept-Encoding'), (b'X-Cache', b'HIT'), (b'Content-Length', b'648')])\nINFO [2024-09-28 17:27:41] httpx - HTTP Request: GET https://www.example.com \"HTTP/1.1 200 OK\"\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - receive_response_body.started request=\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - receive_response_body.complete\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - response_closed.started\nDEBUG [2024-09-28 17:27:41] httpcore.http11 - response_closed.complete\nDEBUG [2024-09-28 17:27:41] httpcore.connection - close.started\nDEBUG [2024-09-28 17:27:41] httpcore.connection - close.complete\n```\n\nLogging output includes information from both the high-level `httpx` logger, and the network-level `httpcore` logger, which can be configured separately.\n\nFor handling more complex logging configurations you might want to use the dictionary configuration style...\n\n```python\nimport logging.config\nimport httpx\n\nLOGGING_CONFIG = {\n \"version\": 1,\n \"handlers\": {\n \"default\": {\n \"class\": \"logging.StreamHandler\",\n \"formatter\": \"http\",\n \"stream\": \"ext://sys.stderr\"\n }\n },\n \"formatters\": {\n \"http\": {\n \"format\": \"%(levelname)s [%(asctime)s] %(name)s - %(message)s\",\n \"datefmt\": \"%Y-%m-%d %H:%M:%S\",\n }\n },\n 'loggers': {\n 'httpx': {\n 'handlers': ['default'],\n 'level': 'DEBUG',\n },\n 'httpcore': {\n 'handlers': ['default'],\n 'level': 'DEBUG',\n },\n }\n}\n\nlogging.config.dictConfig(LOGGING_CONFIG)\nhttpx.get('https://www.example.com')\n```\n\nThe exact formatting of the debug logging may be subject to change across different versions of `httpx` and `httpcore`. If you need to rely on a particular format it is recommended that you pin installation of these packages to fixed versions.\n"
},
{
"path": "docs/overrides/partials/nav.html",
"content": "{% import \"partials/nav-item.html\" as item with context %}\n\n\n {% set class = \"md-nav md-nav--primary\" %}\n {% if \"navigation.tabs\" in features %}\n {% set class = class ~ \" md-nav--lifted\" %}\n {% endif %}\n {% if \"toc.integrate\" in features %}\n {% set class = class ~ \" md-nav--integrated\" %}\n {% endif %}\n\n \n \n\n \n \n\n \n {% if config.repo_url %}\n
\n {% include \"partials/source.html\" %}\n
\n {% endif %}\n\n \n
\n {% for nav_item in nav %}\n {% set path = \"__nav_\" ~ loop.index %}\n {{ item.render(nav_item, path, 1) }}\n {% endfor %}\n
\n\n
\n
\n \n
\n
\n \n "
},
{
"path": "docs/quickstart.md",
"content": "# QuickStart\n\nFirst, start by importing HTTPX:\n\n```pycon\n>>> import httpx\n```\n\nNow, let’s try to get a webpage.\n\n```pycon\n>>> r = httpx.get('https://httpbin.org/get')\n>>> r\n\n```\n\nSimilarly, to make an HTTP POST request:\n\n```pycon\n>>> r = httpx.post('https://httpbin.org/post', data={'key': 'value'})\n```\n\nThe PUT, DELETE, HEAD, and OPTIONS requests all follow the same style:\n\n```pycon\n>>> r = httpx.put('https://httpbin.org/put', data={'key': 'value'})\n>>> r = httpx.delete('https://httpbin.org/delete')\n>>> r = httpx.head('https://httpbin.org/get')\n>>> r = httpx.options('https://httpbin.org/get')\n```\n\n## Passing Parameters in URLs\n\nTo include URL query parameters in the request, use the `params` keyword:\n\n```pycon\n>>> params = {'key1': 'value1', 'key2': 'value2'}\n>>> r = httpx.get('https://httpbin.org/get', params=params)\n```\n\nTo see how the values get encoding into the URL string, we can inspect the\nresulting URL that was used to make the request:\n\n```pycon\n>>> r.url\nURL('https://httpbin.org/get?key2=value2&key1=value1')\n```\n\nYou can also pass a list of items as a value:\n\n```pycon\n>>> params = {'key1': 'value1', 'key2': ['value2', 'value3']}\n>>> r = httpx.get('https://httpbin.org/get', params=params)\n>>> r.url\nURL('https://httpbin.org/get?key1=value1&key2=value2&key2=value3')\n```\n\n## Response Content\n\nHTTPX will automatically handle decoding the response content into Unicode text.\n\n```pycon\n>>> r = httpx.get('https://www.example.org/')\n>>> r.text\n'\\n\\n\\nExample Domain...'\n```\n\nYou can inspect what encoding will be used to decode the response.\n\n```pycon\n>>> r.encoding\n'UTF-8'\n```\n\nIn some cases the response may not contain an explicit encoding, in which case HTTPX\nwill attempt to automatically determine an encoding to use.\n\n```pycon\n>>> r.encoding\nNone\n>>> r.text\n'\\n\\n\\nExample Domain...'\n```\n\nIf you need to override the standard behaviour and explicitly set the encoding to\nuse, then you can do that too.\n\n```pycon\n>>> r.encoding = 'ISO-8859-1'\n```\n\n## Binary Response Content\n\nThe response content can also be accessed as bytes, for non-text responses:\n\n```pycon\n>>> r.content\nb'\\n\\n\\nExample Domain...'\n```\n\nAny `gzip` and `deflate` HTTP response encodings will automatically\nbe decoded for you. If `brotlipy` is installed, then the `brotli` response\nencoding will be supported. If `zstandard` is installed, then `zstd`\nresponse encodings will also be supported.\n\nFor example, to create an image from binary data returned by a request, you can use the following code:\n\n```pycon\n>>> from PIL import Image\n>>> from io import BytesIO\n>>> i = Image.open(BytesIO(r.content))\n```\n\n## JSON Response Content\n\nOften Web API responses will be encoded as JSON.\n\n```pycon\n>>> r = httpx.get('https://api.github.com/events')\n>>> r.json()\n[{u'repository': {u'open_issues': 0, u'url': 'https://github.com/...' ... }}]\n```\n\n## Custom Headers\n\nTo include additional headers in the outgoing request, use the `headers` keyword argument:\n\n```pycon\n>>> url = 'https://httpbin.org/headers'\n>>> headers = {'user-agent': 'my-app/0.0.1'}\n>>> r = httpx.get(url, headers=headers)\n```\n\n## Sending Form Encoded Data\n\nSome types of HTTP requests, such as `POST` and `PUT` requests, can include data\nin the request body. One common way of including that is as form-encoded data,\nwhich is used for HTML forms.\n\n```pycon\n>>> data = {'key1': 'value1', 'key2': 'value2'}\n>>> r = httpx.post(\"https://httpbin.org/post\", data=data)\n>>> print(r.text)\n{\n ...\n \"form\": {\n \"key2\": \"value2\",\n \"key1\": \"value1\"\n },\n ...\n}\n```\n\nForm encoded data can also include multiple values from a given key.\n\n```pycon\n>>> data = {'key1': ['value1', 'value2']}\n>>> r = httpx.post(\"https://httpbin.org/post\", data=data)\n>>> print(r.text)\n{\n ...\n \"form\": {\n \"key1\": [\n \"value1\",\n \"value2\"\n ]\n },\n ...\n}\n```\n\n## Sending Multipart File Uploads\n\nYou can also upload files, using HTTP multipart encoding:\n\n```pycon\n>>> with open('report.xls', 'rb') as report_file:\n... files = {'upload-file': report_file}\n... r = httpx.post(\"https://httpbin.org/post\", files=files)\n>>> print(r.text)\n{\n ...\n \"files\": {\n \"upload-file\": \"<... binary content ...>\"\n },\n ...\n}\n```\n\nYou can also explicitly set the filename and content type, by using a tuple\nof items for the file value:\n\n```pycon\n>>> with open('report.xls', 'rb') as report_file:\n... files = {'upload-file': ('report.xls', report_file, 'application/vnd.ms-excel')}\n... r = httpx.post(\"https://httpbin.org/post\", files=files)\n>>> print(r.text)\n{\n ...\n \"files\": {\n \"upload-file\": \"<... binary content ...>\"\n },\n ...\n}\n```\n\nIf you need to include non-file data fields in the multipart form, use the `data=...` parameter:\n\n```pycon\n>>> data = {'message': 'Hello, world!'}\n>>> with open('report.xls', 'rb') as report_file:\n... files = {'file': report_file}\n... r = httpx.post(\"https://httpbin.org/post\", data=data, files=files)\n>>> print(r.text)\n{\n ...\n \"files\": {\n \"file\": \"<... binary content ...>\"\n },\n \"form\": {\n \"message\": \"Hello, world!\",\n },\n ...\n}\n```\n\n## Sending JSON Encoded Data\n\nForm encoded data is okay if all you need is a simple key-value data structure.\nFor more complicated data structures you'll often want to use JSON encoding instead.\n\n```pycon\n>>> data = {'integer': 123, 'boolean': True, 'list': ['a', 'b', 'c']}\n>>> r = httpx.post(\"https://httpbin.org/post\", json=data)\n>>> print(r.text)\n{\n ...\n \"json\": {\n \"boolean\": true,\n \"integer\": 123,\n \"list\": [\n \"a\",\n \"b\",\n \"c\"\n ]\n },\n ...\n}\n```\n\n## Sending Binary Request Data\n\nFor other encodings, you should use the `content=...` parameter, passing\neither a `bytes` type or a generator that yields `bytes`.\n\n```pycon\n>>> content = b'Hello, world'\n>>> r = httpx.post(\"https://httpbin.org/post\", content=content)\n```\n\nYou may also want to set a custom `Content-Type` header when uploading\nbinary data.\n\n## Response Status Codes\n\nWe can inspect the HTTP status code of the response:\n\n```pycon\n>>> r = httpx.get('https://httpbin.org/get')\n>>> r.status_code\n200\n```\n\nHTTPX also includes an easy shortcut for accessing status codes by their text phrase.\n\n```pycon\n>>> r.status_code == httpx.codes.OK\nTrue\n```\n\nWe can raise an exception for any responses which are not a 2xx success code:\n\n```pycon\n>>> not_found = httpx.get('https://httpbin.org/status/404')\n>>> not_found.status_code\n404\n>>> not_found.raise_for_status()\nTraceback (most recent call last):\n File \"/Users/tomchristie/GitHub/encode/httpcore/httpx/models.py\", line 837, in raise_for_status\n raise HTTPStatusError(message, response=self)\nhttpx._exceptions.HTTPStatusError: 404 Client Error: Not Found for url: https://httpbin.org/status/404\nFor more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404\n```\n\nAny successful response codes will return the `Response` instance rather than raising an exception.\n\n```pycon\n>>> r.raise_for_status()\n```\n\nThe method returns the response instance, allowing you to use it inline. For example:\n\n```pycon\n>>> r = httpx.get('...').raise_for_status()\n>>> data = httpx.get('...').raise_for_status().json()\n```\n\n## Response Headers\n\nThe response headers are available as a dictionary-like interface.\n\n```pycon\n>>> r.headers\nHeaders({\n 'content-encoding': 'gzip',\n 'transfer-encoding': 'chunked',\n 'connection': 'close',\n 'server': 'nginx/1.0.4',\n 'x-runtime': '148ms',\n 'etag': '\"e1ca502697e5c9317743dc078f67693f\"',\n 'content-type': 'application/json'\n})\n```\n\nThe `Headers` data type is case-insensitive, so you can use any capitalization.\n\n```pycon\n>>> r.headers['Content-Type']\n'application/json'\n\n>>> r.headers.get('content-type')\n'application/json'\n```\n\nMultiple values for a single response header are represented as a single comma-separated value, as per [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2):\n\n> A recipient MAY combine multiple header fields with the same field name into one “field-name: field-value” pair, without changing the semantics of the message, by appending each subsequent field-value to the combined field value in order, separated by a comma.\n\n## Streaming Responses\n\nFor large downloads you may want to use streaming responses that do not load the entire response body into memory at once.\n\nYou can stream the binary content of the response...\n\n```pycon\n>>> with httpx.stream(\"GET\", \"https://www.example.com\") as r:\n... for data in r.iter_bytes():\n... print(data)\n```\n\nOr the text of the response...\n\n```pycon\n>>> with httpx.stream(\"GET\", \"https://www.example.com\") as r:\n... for text in r.iter_text():\n... print(text)\n```\n\nOr stream the text, on a line-by-line basis...\n\n```pycon\n>>> with httpx.stream(\"GET\", \"https://www.example.com\") as r:\n... for line in r.iter_lines():\n... print(line)\n```\n\nHTTPX will use universal line endings, normalising all cases to `\\n`.\n\nIn some cases you might want to access the raw bytes on the response without applying any HTTP content decoding. In this case any content encoding that the web server has applied such as `gzip`, `deflate`, `brotli`, or `zstd` will\nnot be automatically decoded.\n\n```pycon\n>>> with httpx.stream(\"GET\", \"https://www.example.com\") as r:\n... for chunk in r.iter_raw():\n... print(chunk)\n```\n\nIf you're using streaming responses in any of these ways then the `response.content` and `response.text` attributes will not be available, and will raise errors if accessed. However you can also use the response streaming functionality to conditionally load the response body:\n\n```pycon\n>>> with httpx.stream(\"GET\", \"https://www.example.com\") as r:\n... if int(r.headers['Content-Length']) < TOO_LONG:\n... r.read()\n... print(r.text)\n```\n\n## Cookies\n\nAny cookies that are set on the response can be easily accessed:\n\n```pycon\n>>> r = httpx.get('https://httpbin.org/cookies/set?chocolate=chip')\n>>> r.cookies['chocolate']\n'chip'\n```\n\nTo include cookies in an outgoing request, use the `cookies` parameter:\n\n```pycon\n>>> cookies = {\"peanut\": \"butter\"}\n>>> r = httpx.get('https://httpbin.org/cookies', cookies=cookies)\n>>> r.json()\n{'cookies': {'peanut': 'butter'}}\n```\n\nCookies are returned in a `Cookies` instance, which is a dict-like data structure\nwith additional API for accessing cookies by their domain or path.\n\n```pycon\n>>> cookies = httpx.Cookies()\n>>> cookies.set('cookie_on_domain', 'hello, there!', domain='httpbin.org')\n>>> cookies.set('cookie_off_domain', 'nope.', domain='example.org')\n>>> r = httpx.get('http://httpbin.org/cookies', cookies=cookies)\n>>> r.json()\n{'cookies': {'cookie_on_domain': 'hello, there!'}}\n```\n\n## Redirection and History\n\nBy default, HTTPX will **not** follow redirects for all HTTP methods, although\nthis can be explicitly enabled.\n\nFor example, GitHub redirects all HTTP requests to HTTPS.\n\n```pycon\n>>> r = httpx.get('http://github.com/')\n>>> r.status_code\n301\n>>> r.history\n[]\n>>> r.next_request\n\n```\n\nYou can modify the default redirection handling with the `follow_redirects` parameter:\n\n```pycon\n>>> r = httpx.get('http://github.com/', follow_redirects=True)\n>>> r.url\nURL('https://github.com/')\n>>> r.status_code\n200\n>>> r.history\n[]\n```\n\nThe `history` property of the response can be used to inspect any followed redirects.\nIt contains a list of any redirect responses that were followed, in the order\nin which they were made.\n\n## Timeouts\n\nHTTPX defaults to including reasonable timeouts for all network operations,\nmeaning that if a connection is not properly established then it should always\nraise an error rather than hanging indefinitely.\n\nThe default timeout for network inactivity is five seconds. You can modify the\nvalue to be more or less strict:\n\n```pycon\n>>> httpx.get('https://github.com/', timeout=0.001)\n```\n\nYou can also disable the timeout behavior completely...\n\n```pycon\n>>> httpx.get('https://github.com/', timeout=None)\n```\n\nFor advanced timeout management, see [Timeout fine-tuning](advanced/timeouts.md#fine-tuning-the-configuration).\n\n## Authentication\n\nHTTPX supports Basic and Digest HTTP authentication.\n\nTo provide Basic authentication credentials, pass a 2-tuple of\nplaintext `str` or `bytes` objects as the `auth` argument to the request\nfunctions:\n\n```pycon\n>>> httpx.get(\"https://example.com\", auth=(\"my_user\", \"password123\"))\n```\n\nTo provide credentials for Digest authentication you'll need to instantiate\na `DigestAuth` object with the plaintext username and password as arguments.\nThis object can be then passed as the `auth` argument to the request methods\nas above:\n\n```pycon\n>>> auth = httpx.DigestAuth(\"my_user\", \"password123\")\n>>> httpx.get(\"https://example.com\", auth=auth)\n\n```\n\n## Exceptions\n\nHTTPX will raise exceptions if an error occurs.\n\nThe most important exception classes in HTTPX are `RequestError` and `HTTPStatusError`.\n\nThe `RequestError` class is a superclass that encompasses any exception that occurs\nwhile issuing an HTTP request. These exceptions include a `.request` attribute.\n\n```python\ntry:\n response = httpx.get(\"https://www.example.com/\")\nexcept httpx.RequestError as exc:\n print(f\"An error occurred while requesting {exc.request.url!r}.\")\n```\n\nThe `HTTPStatusError` class is raised by `response.raise_for_status()` on responses which are not a 2xx success code.\nThese exceptions include both a `.request` and a `.response` attribute.\n\n```python\nresponse = httpx.get(\"https://www.example.com/\")\ntry:\n response.raise_for_status()\nexcept httpx.HTTPStatusError as exc:\n print(f\"Error response {exc.response.status_code} while requesting {exc.request.url!r}.\")\n```\n\nThere is also a base class `HTTPError` that includes both of these categories, and can be used\nto catch either failed requests, or 4xx and 5xx responses.\n\nYou can either use this base class to catch both categories...\n\n```python\ntry:\n response = httpx.get(\"https://www.example.com/\")\n response.raise_for_status()\nexcept httpx.HTTPError as exc:\n print(f\"Error while requesting {exc.request.url!r}.\")\n```\n\nOr handle each case explicitly...\n\n```python\ntry:\n response = httpx.get(\"https://www.example.com/\")\n response.raise_for_status()\nexcept httpx.RequestError as exc:\n print(f\"An error occurred while requesting {exc.request.url!r}.\")\nexcept httpx.HTTPStatusError as exc:\n print(f\"Error response {exc.response.status_code} while requesting {exc.request.url!r}.\")\n```\n\nFor a full list of available exceptions, see [Exceptions (API Reference)](exceptions.md).\n"
},
{
"path": "docs/third_party_packages.md",
"content": "# Third Party Packages\n\nAs HTTPX usage grows, there is an expanding community of developers building tools and libraries that integrate with HTTPX, or depend on HTTPX. Here are some of them.\n\n\n\n## Plugins\n\n### Hishel\n\n[GitHub](https://github.com/karpetrosyan/hishel) - [Documentation](https://hishel.com/)\n\nAn elegant HTTP Cache implementation for HTTPX and HTTP Core.\n\n### HTTPX-Auth\n\n[GitHub](https://github.com/Colin-b/httpx_auth) - [Documentation](https://colin-b.github.io/httpx_auth/)\n\nProvides authentication classes to be used with HTTPX's [authentication parameter](advanced/authentication.md#customizing-authentication).\n\n### httpx-caching\n\n[Github](https://github.com/johtso/httpx-caching)\n\nThis package adds caching functionality to HTTPX\n\n### httpx-secure\n\n[GitHub](https://github.com/Zaczero/httpx-secure)\n\nDrop-in SSRF protection for httpx with DNS caching and custom validation support.\n\n### httpx-socks\n\n[GitHub](https://github.com/romis2012/httpx-socks)\n\nProxy (HTTP, SOCKS) transports for httpx.\n\n### httpx-sse\n\n[GitHub](https://github.com/florimondmanca/httpx-sse)\n\nAllows consuming Server-Sent Events (SSE) with HTTPX.\n\n### httpx-retries\n\n[GitHub](https://github.com/will-ockmore/httpx-retries) - [Documentation](https://will-ockmore.github.io/httpx-retries/)\n\nA retry layer for HTTPX.\n\n### httpx-ws\n\n[GitHub](https://github.com/frankie567/httpx-ws) - [Documentation](https://frankie567.github.io/httpx-ws/)\n\nWebSocket support for HTTPX.\n\n### pytest-HTTPX\n\n[GitHub](https://github.com/Colin-b/pytest_httpx) - [Documentation](https://colin-b.github.io/pytest_httpx/)\n\nProvides a [pytest](https://docs.pytest.org/en/latest/) fixture to mock HTTPX within test cases.\n\n### RESPX\n\n[GitHub](https://github.com/lundberg/respx) - [Documentation](https://lundberg.github.io/respx/)\n\nA utility for mocking out HTTPX.\n\n### rpc.py\n\n[Github](https://github.com/abersheeran/rpc.py) - [Documentation](https://github.com/abersheeran/rpc.py#rpcpy)\n\nA fast and powerful RPC framework based on ASGI/WSGI. Use HTTPX as the client of the RPC service.\n\n## Libraries with HTTPX support\n\n### Authlib\n\n[GitHub](https://github.com/lepture/authlib) - [Documentation](https://docs.authlib.org/en/latest/)\n\nA python library for building OAuth and OpenID Connect clients and servers. Includes an [OAuth HTTPX client](https://docs.authlib.org/en/latest/client/httpx.html).\n\n### Gidgethub\n\n[GitHub](https://github.com/brettcannon/gidgethub) - [Documentation](https://gidgethub.readthedocs.io/en/latest/index.html)\n\nAn asynchronous GitHub API library. Includes [HTTPX support](https://gidgethub.readthedocs.io/en/latest/httpx.html).\n\n### httpdbg\n\n[GitHub](https://github.com/cle-b/httpdbg) - [Documentation](https://httpdbg.readthedocs.io/)\n\nA tool for python developers to easily debug the HTTP(S) client requests in a python program.\n\n### VCR.py\n\n[GitHub](https://github.com/kevin1024/vcrpy) - [Documentation](https://vcrpy.readthedocs.io/)\n\nRecord and repeat requests.\n\n## Gists\n\n### urllib3-transport\n\n[GitHub](https://gist.github.com/florimondmanca/d56764d78d748eb9f73165da388e546e)\n\nThis public gist provides an example implementation for a [custom transport](advanced/transports.md#custom-transports) implementation on top of the battle-tested [`urllib3`](https://urllib3.readthedocs.io) library.\n"
},
{
"path": "docs/troubleshooting.md",
"content": "# Troubleshooting\n\nThis page lists some common problems or issues you could encounter while developing with HTTPX, as well as possible solutions.\n\n## Proxies\n\n---\n\n### \"`The handshake operation timed out`\" on HTTPS requests when using a proxy\n\n**Description**: When using a proxy and making an HTTPS request, you see an exception looking like this:\n\n```console\nhttpx.ProxyError: _ssl.c:1091: The handshake operation timed out\n```\n\n**Similar issues**: [encode/httpx#1412](https://github.com/encode/httpx/issues/1412), [encode/httpx#1433](https://github.com/encode/httpx/issues/1433)\n\n**Resolution**: it is likely that you've set up your proxies like this...\n\n```python\nmounts = {\n \"http://\": httpx.HTTPTransport(proxy=\"http://myproxy.org\"),\n \"https://\": httpx.HTTPTransport(proxy=\"https://myproxy.org\"),\n}\n```\n\nUsing this setup, you're telling HTTPX to connect to the proxy using HTTP for HTTP requests, and using HTTPS for HTTPS requests.\n\nBut if you get the error above, it is likely that your proxy doesn't support connecting via HTTPS. Don't worry: that's a [common gotcha](advanced/proxies.md#http-proxies).\n\nChange the scheme of your HTTPS proxy to `http://...` instead of `https://...`:\n\n```python\nmounts = {\n \"http://\": httpx.HTTPTransport(proxy=\"http://myproxy.org\"),\n \"https://\": httpx.HTTPTransport(proxy=\"http://myproxy.org\"),\n}\n```\n\nThis can be simplified to:\n\n```python\nproxy = \"http://myproxy.org\"\nwith httpx.Client(proxy=proxy) as client:\n ...\n```\n\nFor more information, see [Proxies: FORWARD vs TUNNEL](advanced/proxies.md#forward-vs-tunnel).\n\n---\n\n### Error when making requests to an HTTPS proxy\n\n**Description**: your proxy _does_ support connecting via HTTPS, but you are seeing errors along the lines of...\n\n```console\nhttpx.ProxyError: [SSL: PRE_MAC_LENGTH_TOO_LONG] invalid alert (_ssl.c:1091)\n```\n\n**Similar issues**: [encode/httpx#1424](https://github.com/encode/httpx/issues/1424).\n\n**Resolution**: HTTPX does not properly support HTTPS proxies at this time. If that's something you're interested in having, please see [encode/httpx#1434](https://github.com/encode/httpx/issues/1434) and consider lending a hand there.\n"
},
{
"path": "httpx/__init__.py",
"content": "from .__version__ import __description__, __title__, __version__\nfrom ._api import *\nfrom ._auth import *\nfrom ._client import *\nfrom ._config import *\nfrom ._content import *\nfrom ._exceptions import *\nfrom ._models import *\nfrom ._status_codes import *\nfrom ._transports import *\nfrom ._types import *\nfrom ._urls import *\n\ntry:\n from ._main import main\nexcept ImportError: # pragma: no cover\n\n def main() -> None: # type: ignore\n import sys\n\n print(\n \"The httpx command line client could not run because the required \"\n \"dependencies were not installed.\\nMake sure you've installed \"\n \"everything with: pip install 'httpx[cli]'\"\n )\n sys.exit(1)\n\n\n__all__ = [\n \"__description__\",\n \"__title__\",\n \"__version__\",\n \"ASGITransport\",\n \"AsyncBaseTransport\",\n \"AsyncByteStream\",\n \"AsyncClient\",\n \"AsyncHTTPTransport\",\n \"Auth\",\n \"BaseTransport\",\n \"BasicAuth\",\n \"ByteStream\",\n \"Client\",\n \"CloseError\",\n \"codes\",\n \"ConnectError\",\n \"ConnectTimeout\",\n \"CookieConflict\",\n \"Cookies\",\n \"create_ssl_context\",\n \"DecodingError\",\n \"delete\",\n \"DigestAuth\",\n \"FunctionAuth\",\n \"get\",\n \"head\",\n \"Headers\",\n \"HTTPError\",\n \"HTTPStatusError\",\n \"HTTPTransport\",\n \"InvalidURL\",\n \"Limits\",\n \"LocalProtocolError\",\n \"main\",\n \"MockTransport\",\n \"NetRCAuth\",\n \"NetworkError\",\n \"options\",\n \"patch\",\n \"PoolTimeout\",\n \"post\",\n \"ProtocolError\",\n \"Proxy\",\n \"ProxyError\",\n \"put\",\n \"QueryParams\",\n \"ReadError\",\n \"ReadTimeout\",\n \"RemoteProtocolError\",\n \"request\",\n \"Request\",\n \"RequestError\",\n \"RequestNotRead\",\n \"Response\",\n \"ResponseNotRead\",\n \"stream\",\n \"StreamClosed\",\n \"StreamConsumed\",\n \"StreamError\",\n \"SyncByteStream\",\n \"Timeout\",\n \"TimeoutException\",\n \"TooManyRedirects\",\n \"TransportError\",\n \"UnsupportedProtocol\",\n \"URL\",\n \"USE_CLIENT_DEFAULT\",\n \"WriteError\",\n \"WriteTimeout\",\n \"WSGITransport\",\n]\n\n\n__locals = locals()\nfor __name in __all__:\n if not __name.startswith(\"__\"):\n setattr(__locals[__name], \"__module__\", \"httpx\") # noqa\n"
},
{
"path": "httpx/__version__.py",
"content": "__title__ = \"httpx\"\n__description__ = \"A next generation HTTP client, for Python 3.\"\n__version__ = \"0.28.1\"\n"
},
{
"path": "httpx/_api.py",
"content": "from __future__ import annotations\n\nimport typing\nfrom contextlib import contextmanager\n\nfrom ._client import Client\nfrom ._config import DEFAULT_TIMEOUT_CONFIG\nfrom ._models import Response\nfrom ._types import (\n AuthTypes,\n CookieTypes,\n HeaderTypes,\n ProxyTypes,\n QueryParamTypes,\n RequestContent,\n RequestData,\n RequestFiles,\n TimeoutTypes,\n)\nfrom ._urls import URL\n\nif typing.TYPE_CHECKING:\n import ssl # pragma: no cover\n\n\n__all__ = [\n \"delete\",\n \"get\",\n \"head\",\n \"options\",\n \"patch\",\n \"post\",\n \"put\",\n \"request\",\n \"stream\",\n]\n\n\ndef request(\n method: str,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | None = None,\n proxy: ProxyTypes | None = None,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n follow_redirects: bool = False,\n verify: ssl.SSLContext | str | bool = True,\n trust_env: bool = True,\n) -> Response:\n \"\"\"\n Sends an HTTP request.\n\n **Parameters:**\n\n * **method** - HTTP method for the new `Request` object: `GET`, `OPTIONS`,\n `HEAD`, `POST`, `PUT`, `PATCH`, or `DELETE`.\n * **url** - URL for the new `Request` object.\n * **params** - *(optional)* Query parameters to include in the URL, as a\n string, dictionary, or sequence of two-tuples.\n * **content** - *(optional)* Binary content to include in the body of the\n request, as bytes or a byte iterator.\n * **data** - *(optional)* Form data to include in the body of the request,\n as a dictionary.\n * **files** - *(optional)* A dictionary of upload files to include in the\n body of the request.\n * **json** - *(optional)* A JSON serializable object to include in the body\n of the request.\n * **headers** - *(optional)* Dictionary of HTTP headers to include in the\n request.\n * **cookies** - *(optional)* Dictionary of Cookie items to include in the\n request.\n * **auth** - *(optional)* An authentication class to use when sending the\n request.\n * **proxy** - *(optional)* A proxy URL where all the traffic should be routed.\n * **timeout** - *(optional)* The timeout configuration to use when sending\n the request.\n * **follow_redirects** - *(optional)* Enables or disables HTTP redirects.\n * **verify** - *(optional)* Either `True` to use an SSL context with the\n default CA bundle, `False` to disable verification, or an instance of\n `ssl.SSLContext` to use a custom context.\n * **trust_env** - *(optional)* Enables or disables usage of environment\n variables for configuration.\n\n **Returns:** `Response`\n\n Usage:\n\n ```\n >>> import httpx\n >>> response = httpx.request('GET', 'https://httpbin.org/get')\n >>> response\n \n ```\n \"\"\"\n with Client(\n cookies=cookies,\n proxy=proxy,\n verify=verify,\n timeout=timeout,\n trust_env=trust_env,\n ) as client:\n return client.request(\n method=method,\n url=url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n auth=auth,\n follow_redirects=follow_redirects,\n )\n\n\n@contextmanager\ndef stream(\n method: str,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | None = None,\n proxy: ProxyTypes | None = None,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n follow_redirects: bool = False,\n verify: ssl.SSLContext | str | bool = True,\n trust_env: bool = True,\n) -> typing.Iterator[Response]:\n \"\"\"\n Alternative to `httpx.request()` that streams the response body\n instead of loading it into memory at once.\n\n **Parameters**: See `httpx.request`.\n\n See also: [Streaming Responses][0]\n\n [0]: /quickstart#streaming-responses\n \"\"\"\n with Client(\n cookies=cookies,\n proxy=proxy,\n verify=verify,\n timeout=timeout,\n trust_env=trust_env,\n ) as client:\n with client.stream(\n method=method,\n url=url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n auth=auth,\n follow_redirects=follow_redirects,\n ) as response:\n yield response\n\n\ndef get(\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | None = None,\n proxy: ProxyTypes | None = None,\n follow_redirects: bool = False,\n verify: ssl.SSLContext | str | bool = True,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n trust_env: bool = True,\n) -> Response:\n \"\"\"\n Sends a `GET` request.\n\n **Parameters**: See `httpx.request`.\n\n Note that the `data`, `files`, `json` and `content` parameters are not available\n on this function, as `GET` requests should not include a request body.\n \"\"\"\n return request(\n \"GET\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n proxy=proxy,\n follow_redirects=follow_redirects,\n verify=verify,\n timeout=timeout,\n trust_env=trust_env,\n )\n\n\ndef options(\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | None = None,\n proxy: ProxyTypes | None = None,\n follow_redirects: bool = False,\n verify: ssl.SSLContext | str | bool = True,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n trust_env: bool = True,\n) -> Response:\n \"\"\"\n Sends an `OPTIONS` request.\n\n **Parameters**: See `httpx.request`.\n\n Note that the `data`, `files`, `json` and `content` parameters are not available\n on this function, as `OPTIONS` requests should not include a request body.\n \"\"\"\n return request(\n \"OPTIONS\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n proxy=proxy,\n follow_redirects=follow_redirects,\n verify=verify,\n timeout=timeout,\n trust_env=trust_env,\n )\n\n\ndef head(\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | None = None,\n proxy: ProxyTypes | None = None,\n follow_redirects: bool = False,\n verify: ssl.SSLContext | str | bool = True,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n trust_env: bool = True,\n) -> Response:\n \"\"\"\n Sends a `HEAD` request.\n\n **Parameters**: See `httpx.request`.\n\n Note that the `data`, `files`, `json` and `content` parameters are not available\n on this function, as `HEAD` requests should not include a request body.\n \"\"\"\n return request(\n \"HEAD\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n proxy=proxy,\n follow_redirects=follow_redirects,\n verify=verify,\n timeout=timeout,\n trust_env=trust_env,\n )\n\n\ndef post(\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | None = None,\n proxy: ProxyTypes | None = None,\n follow_redirects: bool = False,\n verify: ssl.SSLContext | str | bool = True,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n trust_env: bool = True,\n) -> Response:\n \"\"\"\n Sends a `POST` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return request(\n \"POST\",\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n proxy=proxy,\n follow_redirects=follow_redirects,\n verify=verify,\n timeout=timeout,\n trust_env=trust_env,\n )\n\n\ndef put(\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | None = None,\n proxy: ProxyTypes | None = None,\n follow_redirects: bool = False,\n verify: ssl.SSLContext | str | bool = True,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n trust_env: bool = True,\n) -> Response:\n \"\"\"\n Sends a `PUT` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return request(\n \"PUT\",\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n proxy=proxy,\n follow_redirects=follow_redirects,\n verify=verify,\n timeout=timeout,\n trust_env=trust_env,\n )\n\n\ndef patch(\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | None = None,\n proxy: ProxyTypes | None = None,\n follow_redirects: bool = False,\n verify: ssl.SSLContext | str | bool = True,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n trust_env: bool = True,\n) -> Response:\n \"\"\"\n Sends a `PATCH` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return request(\n \"PATCH\",\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n proxy=proxy,\n follow_redirects=follow_redirects,\n verify=verify,\n timeout=timeout,\n trust_env=trust_env,\n )\n\n\ndef delete(\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | None = None,\n proxy: ProxyTypes | None = None,\n follow_redirects: bool = False,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n verify: ssl.SSLContext | str | bool = True,\n trust_env: bool = True,\n) -> Response:\n \"\"\"\n Sends a `DELETE` request.\n\n **Parameters**: See `httpx.request`.\n\n Note that the `data`, `files`, `json` and `content` parameters are not available\n on this function, as `DELETE` requests should not include a request body.\n \"\"\"\n return request(\n \"DELETE\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n proxy=proxy,\n follow_redirects=follow_redirects,\n verify=verify,\n timeout=timeout,\n trust_env=trust_env,\n )\n"
},
{
"path": "httpx/_auth.py",
"content": "from __future__ import annotations\n\nimport hashlib\nimport os\nimport re\nimport time\nimport typing\nfrom base64 import b64encode\nfrom urllib.request import parse_http_list\n\nfrom ._exceptions import ProtocolError\nfrom ._models import Cookies, Request, Response\nfrom ._utils import to_bytes, to_str, unquote\n\nif typing.TYPE_CHECKING: # pragma: no cover\n from hashlib import _Hash\n\n\n__all__ = [\"Auth\", \"BasicAuth\", \"DigestAuth\", \"FunctionAuth\", \"NetRCAuth\"]\n\n\nclass Auth:\n \"\"\"\n Base class for all authentication schemes.\n\n To implement a custom authentication scheme, subclass `Auth` and override\n the `.auth_flow()` method.\n\n If the authentication scheme does I/O such as disk access or network calls, or uses\n synchronization primitives such as locks, you should override `.sync_auth_flow()`\n and/or `.async_auth_flow()` instead of `.auth_flow()` to provide specialized\n implementations that will be used by `Client` and `AsyncClient` respectively.\n \"\"\"\n\n requires_request_body = False\n requires_response_body = False\n\n def auth_flow(self, request: Request) -> typing.Generator[Request, Response, None]:\n \"\"\"\n Execute the authentication flow.\n\n To dispatch a request, `yield` it:\n\n ```\n yield request\n ```\n\n The client will `.send()` the response back into the flow generator. You can\n access it like so:\n\n ```\n response = yield request\n ```\n\n A `return` (or reaching the end of the generator) will result in the\n client returning the last response obtained from the server.\n\n You can dispatch as many requests as is necessary.\n \"\"\"\n yield request\n\n def sync_auth_flow(\n self, request: Request\n ) -> typing.Generator[Request, Response, None]:\n \"\"\"\n Execute the authentication flow synchronously.\n\n By default, this defers to `.auth_flow()`. You should override this method\n when the authentication scheme does I/O and/or uses concurrency primitives.\n \"\"\"\n if self.requires_request_body:\n request.read()\n\n flow = self.auth_flow(request)\n request = next(flow)\n\n while True:\n response = yield request\n if self.requires_response_body:\n response.read()\n\n try:\n request = flow.send(response)\n except StopIteration:\n break\n\n async def async_auth_flow(\n self, request: Request\n ) -> typing.AsyncGenerator[Request, Response]:\n \"\"\"\n Execute the authentication flow asynchronously.\n\n By default, this defers to `.auth_flow()`. You should override this method\n when the authentication scheme does I/O and/or uses concurrency primitives.\n \"\"\"\n if self.requires_request_body:\n await request.aread()\n\n flow = self.auth_flow(request)\n request = next(flow)\n\n while True:\n response = yield request\n if self.requires_response_body:\n await response.aread()\n\n try:\n request = flow.send(response)\n except StopIteration:\n break\n\n\nclass FunctionAuth(Auth):\n \"\"\"\n Allows the 'auth' argument to be passed as a simple callable function,\n that takes the request, and returns a new, modified request.\n \"\"\"\n\n def __init__(self, func: typing.Callable[[Request], Request]) -> None:\n self._func = func\n\n def auth_flow(self, request: Request) -> typing.Generator[Request, Response, None]:\n yield self._func(request)\n\n\nclass BasicAuth(Auth):\n \"\"\"\n Allows the 'auth' argument to be passed as a (username, password) pair,\n and uses HTTP Basic authentication.\n \"\"\"\n\n def __init__(self, username: str | bytes, password: str | bytes) -> None:\n self._auth_header = self._build_auth_header(username, password)\n\n def auth_flow(self, request: Request) -> typing.Generator[Request, Response, None]:\n request.headers[\"Authorization\"] = self._auth_header\n yield request\n\n def _build_auth_header(self, username: str | bytes, password: str | bytes) -> str:\n userpass = b\":\".join((to_bytes(username), to_bytes(password)))\n token = b64encode(userpass).decode()\n return f\"Basic {token}\"\n\n\nclass NetRCAuth(Auth):\n \"\"\"\n Use a 'netrc' file to lookup basic auth credentials based on the url host.\n \"\"\"\n\n def __init__(self, file: str | None = None) -> None:\n # Lazily import 'netrc'.\n # There's no need for us to load this module unless 'NetRCAuth' is being used.\n import netrc\n\n self._netrc_info = netrc.netrc(file)\n\n def auth_flow(self, request: Request) -> typing.Generator[Request, Response, None]:\n auth_info = self._netrc_info.authenticators(request.url.host)\n if auth_info is None or not auth_info[2]:\n # The netrc file did not have authentication credentials for this host.\n yield request\n else:\n # Build a basic auth header with credentials from the netrc file.\n request.headers[\"Authorization\"] = self._build_auth_header(\n username=auth_info[0], password=auth_info[2]\n )\n yield request\n\n def _build_auth_header(self, username: str | bytes, password: str | bytes) -> str:\n userpass = b\":\".join((to_bytes(username), to_bytes(password)))\n token = b64encode(userpass).decode()\n return f\"Basic {token}\"\n\n\nclass DigestAuth(Auth):\n _ALGORITHM_TO_HASH_FUNCTION: dict[str, typing.Callable[[bytes], _Hash]] = {\n \"MD5\": hashlib.md5,\n \"MD5-SESS\": hashlib.md5,\n \"SHA\": hashlib.sha1,\n \"SHA-SESS\": hashlib.sha1,\n \"SHA-256\": hashlib.sha256,\n \"SHA-256-SESS\": hashlib.sha256,\n \"SHA-512\": hashlib.sha512,\n \"SHA-512-SESS\": hashlib.sha512,\n }\n\n def __init__(self, username: str | bytes, password: str | bytes) -> None:\n self._username = to_bytes(username)\n self._password = to_bytes(password)\n self._last_challenge: _DigestAuthChallenge | None = None\n self._nonce_count = 1\n\n def auth_flow(self, request: Request) -> typing.Generator[Request, Response, None]:\n if self._last_challenge:\n request.headers[\"Authorization\"] = self._build_auth_header(\n request, self._last_challenge\n )\n\n response = yield request\n\n if response.status_code != 401 or \"www-authenticate\" not in response.headers:\n # If the response is not a 401 then we don't\n # need to build an authenticated request.\n return\n\n for auth_header in response.headers.get_list(\"www-authenticate\"):\n if auth_header.lower().startswith(\"digest \"):\n break\n else:\n # If the response does not include a 'WWW-Authenticate: Digest ...'\n # header, then we don't need to build an authenticated request.\n return\n\n self._last_challenge = self._parse_challenge(request, response, auth_header)\n self._nonce_count = 1\n\n request.headers[\"Authorization\"] = self._build_auth_header(\n request, self._last_challenge\n )\n if response.cookies:\n Cookies(response.cookies).set_cookie_header(request=request)\n yield request\n\n def _parse_challenge(\n self, request: Request, response: Response, auth_header: str\n ) -> _DigestAuthChallenge:\n \"\"\"\n Returns a challenge from a Digest WWW-Authenticate header.\n These take the form of:\n `Digest realm=\"realm@host.com\",qop=\"auth,auth-int\",nonce=\"abc\",opaque=\"xyz\"`\n \"\"\"\n scheme, _, fields = auth_header.partition(\" \")\n\n # This method should only ever have been called with a Digest auth header.\n assert scheme.lower() == \"digest\"\n\n header_dict: dict[str, str] = {}\n for field in parse_http_list(fields):\n key, value = field.strip().split(\"=\", 1)\n header_dict[key] = unquote(value)\n\n try:\n realm = header_dict[\"realm\"].encode()\n nonce = header_dict[\"nonce\"].encode()\n algorithm = header_dict.get(\"algorithm\", \"MD5\")\n opaque = header_dict[\"opaque\"].encode() if \"opaque\" in header_dict else None\n qop = header_dict[\"qop\"].encode() if \"qop\" in header_dict else None\n return _DigestAuthChallenge(\n realm=realm, nonce=nonce, algorithm=algorithm, opaque=opaque, qop=qop\n )\n except KeyError as exc:\n message = \"Malformed Digest WWW-Authenticate header\"\n raise ProtocolError(message, request=request) from exc\n\n def _build_auth_header(\n self, request: Request, challenge: _DigestAuthChallenge\n ) -> str:\n hash_func = self._ALGORITHM_TO_HASH_FUNCTION[challenge.algorithm.upper()]\n\n def digest(data: bytes) -> bytes:\n return hash_func(data).hexdigest().encode()\n\n A1 = b\":\".join((self._username, challenge.realm, self._password))\n\n path = request.url.raw_path\n A2 = b\":\".join((request.method.encode(), path))\n # TODO: implement auth-int\n HA2 = digest(A2)\n\n nc_value = b\"%08x\" % self._nonce_count\n cnonce = self._get_client_nonce(self._nonce_count, challenge.nonce)\n self._nonce_count += 1\n\n HA1 = digest(A1)\n if challenge.algorithm.lower().endswith(\"-sess\"):\n HA1 = digest(b\":\".join((HA1, challenge.nonce, cnonce)))\n\n qop = self._resolve_qop(challenge.qop, request=request)\n if qop is None:\n # Following RFC 2069\n digest_data = [HA1, challenge.nonce, HA2]\n else:\n # Following RFC 2617/7616\n digest_data = [HA1, challenge.nonce, nc_value, cnonce, qop, HA2]\n\n format_args = {\n \"username\": self._username,\n \"realm\": challenge.realm,\n \"nonce\": challenge.nonce,\n \"uri\": path,\n \"response\": digest(b\":\".join(digest_data)),\n \"algorithm\": challenge.algorithm.encode(),\n }\n if challenge.opaque:\n format_args[\"opaque\"] = challenge.opaque\n if qop:\n format_args[\"qop\"] = b\"auth\"\n format_args[\"nc\"] = nc_value\n format_args[\"cnonce\"] = cnonce\n\n return \"Digest \" + self._get_header_value(format_args)\n\n def _get_client_nonce(self, nonce_count: int, nonce: bytes) -> bytes:\n s = str(nonce_count).encode()\n s += nonce\n s += time.ctime().encode()\n s += os.urandom(8)\n\n return hashlib.sha1(s).hexdigest()[:16].encode()\n\n def _get_header_value(self, header_fields: dict[str, bytes]) -> str:\n NON_QUOTED_FIELDS = (\"algorithm\", \"qop\", \"nc\")\n QUOTED_TEMPLATE = '{}=\"{}\"'\n NON_QUOTED_TEMPLATE = \"{}={}\"\n\n header_value = \"\"\n for i, (field, value) in enumerate(header_fields.items()):\n if i > 0:\n header_value += \", \"\n template = (\n QUOTED_TEMPLATE\n if field not in NON_QUOTED_FIELDS\n else NON_QUOTED_TEMPLATE\n )\n header_value += template.format(field, to_str(value))\n\n return header_value\n\n def _resolve_qop(self, qop: bytes | None, request: Request) -> bytes | None:\n if qop is None:\n return None\n qops = re.split(b\", ?\", qop)\n if b\"auth\" in qops:\n return b\"auth\"\n\n if qops == [b\"auth-int\"]:\n raise NotImplementedError(\"Digest auth-int support is not yet implemented\")\n\n message = f'Unexpected qop value \"{qop!r}\" in digest auth'\n raise ProtocolError(message, request=request)\n\n\nclass _DigestAuthChallenge(typing.NamedTuple):\n realm: bytes\n nonce: bytes\n algorithm: str\n opaque: bytes | None\n qop: bytes | None\n"
},
{
"path": "httpx/_client.py",
"content": "from __future__ import annotations\n\nimport datetime\nimport enum\nimport logging\nimport time\nimport typing\nimport warnings\nfrom contextlib import asynccontextmanager, contextmanager\nfrom types import TracebackType\n\nfrom .__version__ import __version__\nfrom ._auth import Auth, BasicAuth, FunctionAuth\nfrom ._config import (\n DEFAULT_LIMITS,\n DEFAULT_MAX_REDIRECTS,\n DEFAULT_TIMEOUT_CONFIG,\n Limits,\n Proxy,\n Timeout,\n)\nfrom ._decoders import SUPPORTED_DECODERS\nfrom ._exceptions import (\n InvalidURL,\n RemoteProtocolError,\n TooManyRedirects,\n request_context,\n)\nfrom ._models import Cookies, Headers, Request, Response\nfrom ._status_codes import codes\nfrom ._transports.base import AsyncBaseTransport, BaseTransport\nfrom ._transports.default import AsyncHTTPTransport, HTTPTransport\nfrom ._types import (\n AsyncByteStream,\n AuthTypes,\n CertTypes,\n CookieTypes,\n HeaderTypes,\n ProxyTypes,\n QueryParamTypes,\n RequestContent,\n RequestData,\n RequestExtensions,\n RequestFiles,\n SyncByteStream,\n TimeoutTypes,\n)\nfrom ._urls import URL, QueryParams\nfrom ._utils import URLPattern, get_environment_proxies\n\nif typing.TYPE_CHECKING:\n import ssl # pragma: no cover\n\n__all__ = [\"USE_CLIENT_DEFAULT\", \"AsyncClient\", \"Client\"]\n\n# The type annotation for @classmethod and context managers here follows PEP 484\n# https://www.python.org/dev/peps/pep-0484/#annotating-instance-and-class-methods\nT = typing.TypeVar(\"T\", bound=\"Client\")\nU = typing.TypeVar(\"U\", bound=\"AsyncClient\")\n\n\ndef _is_https_redirect(url: URL, location: URL) -> bool:\n \"\"\"\n Return 'True' if 'location' is a HTTPS upgrade of 'url'\n \"\"\"\n if url.host != location.host:\n return False\n\n return (\n url.scheme == \"http\"\n and _port_or_default(url) == 80\n and location.scheme == \"https\"\n and _port_or_default(location) == 443\n )\n\n\ndef _port_or_default(url: URL) -> int | None:\n if url.port is not None:\n return url.port\n return {\"http\": 80, \"https\": 443}.get(url.scheme)\n\n\ndef _same_origin(url: URL, other: URL) -> bool:\n \"\"\"\n Return 'True' if the given URLs share the same origin.\n \"\"\"\n return (\n url.scheme == other.scheme\n and url.host == other.host\n and _port_or_default(url) == _port_or_default(other)\n )\n\n\nclass UseClientDefault:\n \"\"\"\n For some parameters such as `auth=...` and `timeout=...` we need to be able\n to indicate the default \"unset\" state, in a way that is distinctly different\n to using `None`.\n\n The default \"unset\" state indicates that whatever default is set on the\n client should be used. This is different to setting `None`, which\n explicitly disables the parameter, possibly overriding a client default.\n\n For example we use `timeout=USE_CLIENT_DEFAULT` in the `request()` signature.\n Omitting the `timeout` parameter will send a request using whatever default\n timeout has been configured on the client. Including `timeout=None` will\n ensure no timeout is used.\n\n Note that user code shouldn't need to use the `USE_CLIENT_DEFAULT` constant,\n but it is used internally when a parameter is not included.\n \"\"\"\n\n\nUSE_CLIENT_DEFAULT = UseClientDefault()\n\n\nlogger = logging.getLogger(\"httpx\")\n\nUSER_AGENT = f\"python-httpx/{__version__}\"\nACCEPT_ENCODING = \", \".join(\n [key for key in SUPPORTED_DECODERS.keys() if key != \"identity\"]\n)\n\n\nclass ClientState(enum.Enum):\n # UNOPENED:\n # The client has been instantiated, but has not been used to send a request,\n # or been opened by entering the context of a `with` block.\n UNOPENED = 1\n # OPENED:\n # The client has either sent a request, or is within a `with` block.\n OPENED = 2\n # CLOSED:\n # The client has either exited the `with` block, or `close()` has\n # been called explicitly.\n CLOSED = 3\n\n\nclass BoundSyncStream(SyncByteStream):\n \"\"\"\n A byte stream that is bound to a given response instance, and that\n ensures the `response.elapsed` is set once the response is closed.\n \"\"\"\n\n def __init__(\n self, stream: SyncByteStream, response: Response, start: float\n ) -> None:\n self._stream = stream\n self._response = response\n self._start = start\n\n def __iter__(self) -> typing.Iterator[bytes]:\n for chunk in self._stream:\n yield chunk\n\n def close(self) -> None:\n elapsed = time.perf_counter() - self._start\n self._response.elapsed = datetime.timedelta(seconds=elapsed)\n self._stream.close()\n\n\nclass BoundAsyncStream(AsyncByteStream):\n \"\"\"\n An async byte stream that is bound to a given response instance, and that\n ensures the `response.elapsed` is set once the response is closed.\n \"\"\"\n\n def __init__(\n self, stream: AsyncByteStream, response: Response, start: float\n ) -> None:\n self._stream = stream\n self._response = response\n self._start = start\n\n async def __aiter__(self) -> typing.AsyncIterator[bytes]:\n async for chunk in self._stream:\n yield chunk\n\n async def aclose(self) -> None:\n elapsed = time.perf_counter() - self._start\n self._response.elapsed = datetime.timedelta(seconds=elapsed)\n await self._stream.aclose()\n\n\nEventHook = typing.Callable[..., typing.Any]\n\n\nclass BaseClient:\n def __init__(\n self,\n *,\n auth: AuthTypes | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n follow_redirects: bool = False,\n max_redirects: int = DEFAULT_MAX_REDIRECTS,\n event_hooks: None | (typing.Mapping[str, list[EventHook]]) = None,\n base_url: URL | str = \"\",\n trust_env: bool = True,\n default_encoding: str | typing.Callable[[bytes], str] = \"utf-8\",\n ) -> None:\n event_hooks = {} if event_hooks is None else event_hooks\n\n self._base_url = self._enforce_trailing_slash(URL(base_url))\n\n self._auth = self._build_auth(auth)\n self._params = QueryParams(params)\n self.headers = Headers(headers)\n self._cookies = Cookies(cookies)\n self._timeout = Timeout(timeout)\n self.follow_redirects = follow_redirects\n self.max_redirects = max_redirects\n self._event_hooks = {\n \"request\": list(event_hooks.get(\"request\", [])),\n \"response\": list(event_hooks.get(\"response\", [])),\n }\n self._trust_env = trust_env\n self._default_encoding = default_encoding\n self._state = ClientState.UNOPENED\n\n @property\n def is_closed(self) -> bool:\n \"\"\"\n Check if the client being closed\n \"\"\"\n return self._state == ClientState.CLOSED\n\n @property\n def trust_env(self) -> bool:\n return self._trust_env\n\n def _enforce_trailing_slash(self, url: URL) -> URL:\n if url.raw_path.endswith(b\"/\"):\n return url\n return url.copy_with(raw_path=url.raw_path + b\"/\")\n\n def _get_proxy_map(\n self, proxy: ProxyTypes | None, allow_env_proxies: bool\n ) -> dict[str, Proxy | None]:\n if proxy is None:\n if allow_env_proxies:\n return {\n key: None if url is None else Proxy(url=url)\n for key, url in get_environment_proxies().items()\n }\n return {}\n else:\n proxy = Proxy(url=proxy) if isinstance(proxy, (str, URL)) else proxy\n return {\"all://\": proxy}\n\n @property\n def timeout(self) -> Timeout:\n return self._timeout\n\n @timeout.setter\n def timeout(self, timeout: TimeoutTypes) -> None:\n self._timeout = Timeout(timeout)\n\n @property\n def event_hooks(self) -> dict[str, list[EventHook]]:\n return self._event_hooks\n\n @event_hooks.setter\n def event_hooks(self, event_hooks: dict[str, list[EventHook]]) -> None:\n self._event_hooks = {\n \"request\": list(event_hooks.get(\"request\", [])),\n \"response\": list(event_hooks.get(\"response\", [])),\n }\n\n @property\n def auth(self) -> Auth | None:\n \"\"\"\n Authentication class used when none is passed at the request-level.\n\n See also [Authentication][0].\n\n [0]: /quickstart/#authentication\n \"\"\"\n return self._auth\n\n @auth.setter\n def auth(self, auth: AuthTypes) -> None:\n self._auth = self._build_auth(auth)\n\n @property\n def base_url(self) -> URL:\n \"\"\"\n Base URL to use when sending requests with relative URLs.\n \"\"\"\n return self._base_url\n\n @base_url.setter\n def base_url(self, url: URL | str) -> None:\n self._base_url = self._enforce_trailing_slash(URL(url))\n\n @property\n def headers(self) -> Headers:\n \"\"\"\n HTTP headers to include when sending requests.\n \"\"\"\n return self._headers\n\n @headers.setter\n def headers(self, headers: HeaderTypes) -> None:\n client_headers = Headers(\n {\n b\"Accept\": b\"*/*\",\n b\"Accept-Encoding\": ACCEPT_ENCODING.encode(\"ascii\"),\n b\"Connection\": b\"keep-alive\",\n b\"User-Agent\": USER_AGENT.encode(\"ascii\"),\n }\n )\n client_headers.update(headers)\n self._headers = client_headers\n\n @property\n def cookies(self) -> Cookies:\n \"\"\"\n Cookie values to include when sending requests.\n \"\"\"\n return self._cookies\n\n @cookies.setter\n def cookies(self, cookies: CookieTypes) -> None:\n self._cookies = Cookies(cookies)\n\n @property\n def params(self) -> QueryParams:\n \"\"\"\n Query parameters to include in the URL when sending requests.\n \"\"\"\n return self._params\n\n @params.setter\n def params(self, params: QueryParamTypes) -> None:\n self._params = QueryParams(params)\n\n def build_request(\n self,\n method: str,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Request:\n \"\"\"\n Build and return a request instance.\n\n * The `params`, `headers` and `cookies` arguments\n are merged with any values set on the client.\n * The `url` argument is merged with any `base_url` set on the client.\n\n See also: [Request instances][0]\n\n [0]: /advanced/clients/#request-instances\n \"\"\"\n url = self._merge_url(url)\n headers = self._merge_headers(headers)\n cookies = self._merge_cookies(cookies)\n params = self._merge_queryparams(params)\n extensions = {} if extensions is None else extensions\n if \"timeout\" not in extensions:\n timeout = (\n self.timeout\n if isinstance(timeout, UseClientDefault)\n else Timeout(timeout)\n )\n extensions = dict(**extensions, timeout=timeout.as_dict())\n return Request(\n method,\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n extensions=extensions,\n )\n\n def _merge_url(self, url: URL | str) -> URL:\n \"\"\"\n Merge a URL argument together with any 'base_url' on the client,\n to create the URL used for the outgoing request.\n \"\"\"\n merge_url = URL(url)\n if merge_url.is_relative_url:\n # To merge URLs we always append to the base URL. To get this\n # behaviour correct we always ensure the base URL ends in a '/'\n # separator, and strip any leading '/' from the merge URL.\n #\n # So, eg...\n #\n # >>> client = Client(base_url=\"https://www.example.com/subpath\")\n # >>> client.base_url\n # URL('https://www.example.com/subpath/')\n # >>> client.build_request(\"GET\", \"/path\").url\n # URL('https://www.example.com/subpath/path')\n merge_raw_path = self.base_url.raw_path + merge_url.raw_path.lstrip(b\"/\")\n return self.base_url.copy_with(raw_path=merge_raw_path)\n return merge_url\n\n def _merge_cookies(self, cookies: CookieTypes | None = None) -> CookieTypes | None:\n \"\"\"\n Merge a cookies argument together with any cookies on the client,\n to create the cookies used for the outgoing request.\n \"\"\"\n if cookies or self.cookies:\n merged_cookies = Cookies(self.cookies)\n merged_cookies.update(cookies)\n return merged_cookies\n return cookies\n\n def _merge_headers(self, headers: HeaderTypes | None = None) -> HeaderTypes | None:\n \"\"\"\n Merge a headers argument together with any headers on the client,\n to create the headers used for the outgoing request.\n \"\"\"\n merged_headers = Headers(self.headers)\n merged_headers.update(headers)\n return merged_headers\n\n def _merge_queryparams(\n self, params: QueryParamTypes | None = None\n ) -> QueryParamTypes | None:\n \"\"\"\n Merge a queryparams argument together with any queryparams on the client,\n to create the queryparams used for the outgoing request.\n \"\"\"\n if params or self.params:\n merged_queryparams = QueryParams(self.params)\n return merged_queryparams.merge(params)\n return params\n\n def _build_auth(self, auth: AuthTypes | None) -> Auth | None:\n if auth is None:\n return None\n elif isinstance(auth, tuple):\n return BasicAuth(username=auth[0], password=auth[1])\n elif isinstance(auth, Auth):\n return auth\n elif callable(auth):\n return FunctionAuth(func=auth)\n else:\n raise TypeError(f'Invalid \"auth\" argument: {auth!r}')\n\n def _build_request_auth(\n self,\n request: Request,\n auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,\n ) -> Auth:\n auth = (\n self._auth if isinstance(auth, UseClientDefault) else self._build_auth(auth)\n )\n\n if auth is not None:\n return auth\n\n username, password = request.url.username, request.url.password\n if username or password:\n return BasicAuth(username=username, password=password)\n\n return Auth()\n\n def _build_redirect_request(self, request: Request, response: Response) -> Request:\n \"\"\"\n Given a request and a redirect response, return a new request that\n should be used to effect the redirect.\n \"\"\"\n method = self._redirect_method(request, response)\n url = self._redirect_url(request, response)\n headers = self._redirect_headers(request, url, method)\n stream = self._redirect_stream(request, method)\n cookies = Cookies(self.cookies)\n return Request(\n method=method,\n url=url,\n headers=headers,\n cookies=cookies,\n stream=stream,\n extensions=request.extensions,\n )\n\n def _redirect_method(self, request: Request, response: Response) -> str:\n \"\"\"\n When being redirected we may want to change the method of the request\n based on certain specs or browser behavior.\n \"\"\"\n method = request.method\n\n # https://tools.ietf.org/html/rfc7231#section-6.4.4\n if response.status_code == codes.SEE_OTHER and method != \"HEAD\":\n method = \"GET\"\n\n # Do what the browsers do, despite standards...\n # Turn 302s into GETs.\n if response.status_code == codes.FOUND and method != \"HEAD\":\n method = \"GET\"\n\n # If a POST is responded to with a 301, turn it into a GET.\n # This bizarre behaviour is explained in 'requests' issue 1704.\n if response.status_code == codes.MOVED_PERMANENTLY and method == \"POST\":\n method = \"GET\"\n\n return method\n\n def _redirect_url(self, request: Request, response: Response) -> URL:\n \"\"\"\n Return the URL for the redirect to follow.\n \"\"\"\n location = response.headers[\"Location\"]\n\n try:\n url = URL(location)\n except InvalidURL as exc:\n raise RemoteProtocolError(\n f\"Invalid URL in location header: {exc}.\", request=request\n ) from None\n\n # Handle malformed 'Location' headers that are \"absolute\" form, have no host.\n # See: https://github.com/encode/httpx/issues/771\n if url.scheme and not url.host:\n url = url.copy_with(host=request.url.host)\n\n # Facilitate relative 'Location' headers, as allowed by RFC 7231.\n # (e.g. '/path/to/resource' instead of 'http://domain.tld/path/to/resource')\n if url.is_relative_url:\n url = request.url.join(url)\n\n # Attach previous fragment if needed (RFC 7231 7.1.2)\n if request.url.fragment and not url.fragment:\n url = url.copy_with(fragment=request.url.fragment)\n\n return url\n\n def _redirect_headers(self, request: Request, url: URL, method: str) -> Headers:\n \"\"\"\n Return the headers that should be used for the redirect request.\n \"\"\"\n headers = Headers(request.headers)\n\n if not _same_origin(url, request.url):\n if not _is_https_redirect(request.url, url):\n # Strip Authorization headers when responses are redirected\n # away from the origin. (Except for direct HTTP to HTTPS redirects.)\n headers.pop(\"Authorization\", None)\n\n # Update the Host header.\n headers[\"Host\"] = url.netloc.decode(\"ascii\")\n\n if method != request.method and method == \"GET\":\n # If we've switch to a 'GET' request, then strip any headers which\n # are only relevant to the request body.\n headers.pop(\"Content-Length\", None)\n headers.pop(\"Transfer-Encoding\", None)\n\n # We should use the client cookie store to determine any cookie header,\n # rather than whatever was on the original outgoing request.\n headers.pop(\"Cookie\", None)\n\n return headers\n\n def _redirect_stream(\n self, request: Request, method: str\n ) -> SyncByteStream | AsyncByteStream | None:\n \"\"\"\n Return the body that should be used for the redirect request.\n \"\"\"\n if method != request.method and method == \"GET\":\n return None\n\n return request.stream\n\n def _set_timeout(self, request: Request) -> None:\n if \"timeout\" not in request.extensions:\n timeout = (\n self.timeout\n if isinstance(self.timeout, UseClientDefault)\n else Timeout(self.timeout)\n )\n request.extensions = dict(**request.extensions, timeout=timeout.as_dict())\n\n\nclass Client(BaseClient):\n \"\"\"\n An HTTP client, with connection pooling, HTTP/2, redirects, cookie persistence, etc.\n\n It can be shared between threads.\n\n Usage:\n\n ```python\n >>> client = httpx.Client()\n >>> response = client.get('https://example.org')\n ```\n\n **Parameters:**\n\n * **auth** - *(optional)* An authentication class to use when sending\n requests.\n * **params** - *(optional)* Query parameters to include in request URLs, as\n a string, dictionary, or sequence of two-tuples.\n * **headers** - *(optional)* Dictionary of HTTP headers to include when\n sending requests.\n * **cookies** - *(optional)* Dictionary of Cookie items to include when\n sending requests.\n * **verify** - *(optional)* Either `True` to use an SSL context with the\n default CA bundle, `False` to disable verification, or an instance of\n `ssl.SSLContext` to use a custom context.\n * **http2** - *(optional)* A boolean indicating if HTTP/2 support should be\n enabled. Defaults to `False`.\n * **proxy** - *(optional)* A proxy URL where all the traffic should be routed.\n * **timeout** - *(optional)* The timeout configuration to use when sending\n requests.\n * **limits** - *(optional)* The limits configuration to use.\n * **max_redirects** - *(optional)* The maximum number of redirect responses\n that should be followed.\n * **base_url** - *(optional)* A URL to use as the base when building\n request URLs.\n * **transport** - *(optional)* A transport class to use for sending requests\n over the network.\n * **trust_env** - *(optional)* Enables or disables usage of environment\n variables for configuration.\n * **default_encoding** - *(optional)* The default encoding to use for decoding\n response text, if no charset information is included in a response Content-Type\n header. Set to a callable for automatic character set detection. Default: \"utf-8\".\n \"\"\"\n\n def __init__(\n self,\n *,\n auth: AuthTypes | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n verify: ssl.SSLContext | str | bool = True,\n cert: CertTypes | None = None,\n trust_env: bool = True,\n http1: bool = True,\n http2: bool = False,\n proxy: ProxyTypes | None = None,\n mounts: None | (typing.Mapping[str, BaseTransport | None]) = None,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n follow_redirects: bool = False,\n limits: Limits = DEFAULT_LIMITS,\n max_redirects: int = DEFAULT_MAX_REDIRECTS,\n event_hooks: None | (typing.Mapping[str, list[EventHook]]) = None,\n base_url: URL | str = \"\",\n transport: BaseTransport | None = None,\n default_encoding: str | typing.Callable[[bytes], str] = \"utf-8\",\n ) -> None:\n super().__init__(\n auth=auth,\n params=params,\n headers=headers,\n cookies=cookies,\n timeout=timeout,\n follow_redirects=follow_redirects,\n max_redirects=max_redirects,\n event_hooks=event_hooks,\n base_url=base_url,\n trust_env=trust_env,\n default_encoding=default_encoding,\n )\n\n if http2:\n try:\n import h2 # noqa\n except ImportError: # pragma: no cover\n raise ImportError(\n \"Using http2=True, but the 'h2' package is not installed. \"\n \"Make sure to install httpx using `pip install httpx[http2]`.\"\n ) from None\n\n allow_env_proxies = trust_env and transport is None\n proxy_map = self._get_proxy_map(proxy, allow_env_proxies)\n\n self._transport = self._init_transport(\n verify=verify,\n cert=cert,\n trust_env=trust_env,\n http1=http1,\n http2=http2,\n limits=limits,\n transport=transport,\n )\n self._mounts: dict[URLPattern, BaseTransport | None] = {\n URLPattern(key): None\n if proxy is None\n else self._init_proxy_transport(\n proxy,\n verify=verify,\n cert=cert,\n trust_env=trust_env,\n http1=http1,\n http2=http2,\n limits=limits,\n )\n for key, proxy in proxy_map.items()\n }\n if mounts is not None:\n self._mounts.update(\n {URLPattern(key): transport for key, transport in mounts.items()}\n )\n\n self._mounts = dict(sorted(self._mounts.items()))\n\n def _init_transport(\n self,\n verify: ssl.SSLContext | str | bool = True,\n cert: CertTypes | None = None,\n trust_env: bool = True,\n http1: bool = True,\n http2: bool = False,\n limits: Limits = DEFAULT_LIMITS,\n transport: BaseTransport | None = None,\n ) -> BaseTransport:\n if transport is not None:\n return transport\n\n return HTTPTransport(\n verify=verify,\n cert=cert,\n trust_env=trust_env,\n http1=http1,\n http2=http2,\n limits=limits,\n )\n\n def _init_proxy_transport(\n self,\n proxy: Proxy,\n verify: ssl.SSLContext | str | bool = True,\n cert: CertTypes | None = None,\n trust_env: bool = True,\n http1: bool = True,\n http2: bool = False,\n limits: Limits = DEFAULT_LIMITS,\n ) -> BaseTransport:\n return HTTPTransport(\n verify=verify,\n cert=cert,\n trust_env=trust_env,\n http1=http1,\n http2=http2,\n limits=limits,\n proxy=proxy,\n )\n\n def _transport_for_url(self, url: URL) -> BaseTransport:\n \"\"\"\n Returns the transport instance that should be used for a given URL.\n This will either be the standard connection pool, or a proxy.\n \"\"\"\n for pattern, transport in self._mounts.items():\n if pattern.matches(url):\n return self._transport if transport is None else transport\n\n return self._transport\n\n def request(\n self,\n method: str,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Build and send a request.\n\n Equivalent to:\n\n ```python\n request = client.build_request(...)\n response = client.send(request, ...)\n ```\n\n See `Client.build_request()`, `Client.send()` and\n [Merging of configuration][0] for how the various parameters\n are merged with client-level configuration.\n\n [0]: /advanced/clients/#merging-of-configuration\n \"\"\"\n if cookies is not None:\n message = (\n \"Setting per-request cookies=<...> is being deprecated, because \"\n \"the expected behaviour on cookie persistence is ambiguous. Set \"\n \"cookies directly on the client instance instead.\"\n )\n warnings.warn(message, DeprecationWarning, stacklevel=2)\n\n request = self.build_request(\n method=method,\n url=url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n timeout=timeout,\n extensions=extensions,\n )\n return self.send(request, auth=auth, follow_redirects=follow_redirects)\n\n @contextmanager\n def stream(\n self,\n method: str,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> typing.Iterator[Response]:\n \"\"\"\n Alternative to `httpx.request()` that streams the response body\n instead of loading it into memory at once.\n\n **Parameters**: See `httpx.request`.\n\n See also: [Streaming Responses][0]\n\n [0]: /quickstart#streaming-responses\n \"\"\"\n request = self.build_request(\n method=method,\n url=url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n timeout=timeout,\n extensions=extensions,\n )\n response = self.send(\n request=request,\n auth=auth,\n follow_redirects=follow_redirects,\n stream=True,\n )\n try:\n yield response\n finally:\n response.close()\n\n def send(\n self,\n request: Request,\n *,\n stream: bool = False,\n auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n ) -> Response:\n \"\"\"\n Send a request.\n\n The request is sent as-is, unmodified.\n\n Typically you'll want to build one with `Client.build_request()`\n so that any client-level configuration is merged into the request,\n but passing an explicit `httpx.Request()` is supported as well.\n\n See also: [Request instances][0]\n\n [0]: /advanced/clients/#request-instances\n \"\"\"\n if self._state == ClientState.CLOSED:\n raise RuntimeError(\"Cannot send a request, as the client has been closed.\")\n\n self._state = ClientState.OPENED\n follow_redirects = (\n self.follow_redirects\n if isinstance(follow_redirects, UseClientDefault)\n else follow_redirects\n )\n\n self._set_timeout(request)\n\n auth = self._build_request_auth(request, auth)\n\n response = self._send_handling_auth(\n request,\n auth=auth,\n follow_redirects=follow_redirects,\n history=[],\n )\n try:\n if not stream:\n response.read()\n\n return response\n\n except BaseException as exc:\n response.close()\n raise exc\n\n def _send_handling_auth(\n self,\n request: Request,\n auth: Auth,\n follow_redirects: bool,\n history: list[Response],\n ) -> Response:\n auth_flow = auth.sync_auth_flow(request)\n try:\n request = next(auth_flow)\n\n while True:\n response = self._send_handling_redirects(\n request,\n follow_redirects=follow_redirects,\n history=history,\n )\n try:\n try:\n next_request = auth_flow.send(response)\n except StopIteration:\n return response\n\n response.history = list(history)\n response.read()\n request = next_request\n history.append(response)\n\n except BaseException as exc:\n response.close()\n raise exc\n finally:\n auth_flow.close()\n\n def _send_handling_redirects(\n self,\n request: Request,\n follow_redirects: bool,\n history: list[Response],\n ) -> Response:\n while True:\n if len(history) > self.max_redirects:\n raise TooManyRedirects(\n \"Exceeded maximum allowed redirects.\", request=request\n )\n\n for hook in self._event_hooks[\"request\"]:\n hook(request)\n\n response = self._send_single_request(request)\n try:\n for hook in self._event_hooks[\"response\"]:\n hook(response)\n response.history = list(history)\n\n if not response.has_redirect_location:\n return response\n\n request = self._build_redirect_request(request, response)\n history = history + [response]\n\n if follow_redirects:\n response.read()\n else:\n response.next_request = request\n return response\n\n except BaseException as exc:\n response.close()\n raise exc\n\n def _send_single_request(self, request: Request) -> Response:\n \"\"\"\n Sends a single request, without handling any redirections.\n \"\"\"\n transport = self._transport_for_url(request.url)\n start = time.perf_counter()\n\n if not isinstance(request.stream, SyncByteStream):\n raise RuntimeError(\n \"Attempted to send an async request with a sync Client instance.\"\n )\n\n with request_context(request=request):\n response = transport.handle_request(request)\n\n assert isinstance(response.stream, SyncByteStream)\n\n response.request = request\n response.stream = BoundSyncStream(\n response.stream, response=response, start=start\n )\n self.cookies.extract_cookies(response)\n response.default_encoding = self._default_encoding\n\n logger.info(\n 'HTTP Request: %s %s \"%s %d %s\"',\n request.method,\n request.url,\n response.http_version,\n response.status_code,\n response.reason_phrase,\n )\n\n return response\n\n def get(\n self,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `GET` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return self.request(\n \"GET\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n def options(\n self,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send an `OPTIONS` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return self.request(\n \"OPTIONS\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n def head(\n self,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `HEAD` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return self.request(\n \"HEAD\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n def post(\n self,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `POST` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return self.request(\n \"POST\",\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n def put(\n self,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `PUT` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return self.request(\n \"PUT\",\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n def patch(\n self,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `PATCH` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return self.request(\n \"PATCH\",\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n def delete(\n self,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `DELETE` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return self.request(\n \"DELETE\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n def close(self) -> None:\n \"\"\"\n Close transport and proxies.\n \"\"\"\n if self._state != ClientState.CLOSED:\n self._state = ClientState.CLOSED\n\n self._transport.close()\n for transport in self._mounts.values():\n if transport is not None:\n transport.close()\n\n def __enter__(self: T) -> T:\n if self._state != ClientState.UNOPENED:\n msg = {\n ClientState.OPENED: \"Cannot open a client instance more than once.\",\n ClientState.CLOSED: (\n \"Cannot reopen a client instance, once it has been closed.\"\n ),\n }[self._state]\n raise RuntimeError(msg)\n\n self._state = ClientState.OPENED\n\n self._transport.__enter__()\n for transport in self._mounts.values():\n if transport is not None:\n transport.__enter__()\n return self\n\n def __exit__(\n self,\n exc_type: type[BaseException] | None = None,\n exc_value: BaseException | None = None,\n traceback: TracebackType | None = None,\n ) -> None:\n self._state = ClientState.CLOSED\n\n self._transport.__exit__(exc_type, exc_value, traceback)\n for transport in self._mounts.values():\n if transport is not None:\n transport.__exit__(exc_type, exc_value, traceback)\n\n\nclass AsyncClient(BaseClient):\n \"\"\"\n An asynchronous HTTP client, with connection pooling, HTTP/2, redirects,\n cookie persistence, etc.\n\n It can be shared between tasks.\n\n Usage:\n\n ```python\n >>> async with httpx.AsyncClient() as client:\n >>> response = await client.get('https://example.org')\n ```\n\n **Parameters:**\n\n * **auth** - *(optional)* An authentication class to use when sending\n requests.\n * **params** - *(optional)* Query parameters to include in request URLs, as\n a string, dictionary, or sequence of two-tuples.\n * **headers** - *(optional)* Dictionary of HTTP headers to include when\n sending requests.\n * **cookies** - *(optional)* Dictionary of Cookie items to include when\n sending requests.\n * **verify** - *(optional)* Either `True` to use an SSL context with the\n default CA bundle, `False` to disable verification, or an instance of\n `ssl.SSLContext` to use a custom context.\n * **http2** - *(optional)* A boolean indicating if HTTP/2 support should be\n enabled. Defaults to `False`.\n * **proxy** - *(optional)* A proxy URL where all the traffic should be routed.\n * **timeout** - *(optional)* The timeout configuration to use when sending\n requests.\n * **limits** - *(optional)* The limits configuration to use.\n * **max_redirects** - *(optional)* The maximum number of redirect responses\n that should be followed.\n * **base_url** - *(optional)* A URL to use as the base when building\n request URLs.\n * **transport** - *(optional)* A transport class to use for sending requests\n over the network.\n * **trust_env** - *(optional)* Enables or disables usage of environment\n variables for configuration.\n * **default_encoding** - *(optional)* The default encoding to use for decoding\n response text, if no charset information is included in a response Content-Type\n header. Set to a callable for automatic character set detection. Default: \"utf-8\".\n \"\"\"\n\n def __init__(\n self,\n *,\n auth: AuthTypes | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n verify: ssl.SSLContext | str | bool = True,\n cert: CertTypes | None = None,\n http1: bool = True,\n http2: bool = False,\n proxy: ProxyTypes | None = None,\n mounts: None | (typing.Mapping[str, AsyncBaseTransport | None]) = None,\n timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,\n follow_redirects: bool = False,\n limits: Limits = DEFAULT_LIMITS,\n max_redirects: int = DEFAULT_MAX_REDIRECTS,\n event_hooks: None | (typing.Mapping[str, list[EventHook]]) = None,\n base_url: URL | str = \"\",\n transport: AsyncBaseTransport | None = None,\n trust_env: bool = True,\n default_encoding: str | typing.Callable[[bytes], str] = \"utf-8\",\n ) -> None:\n super().__init__(\n auth=auth,\n params=params,\n headers=headers,\n cookies=cookies,\n timeout=timeout,\n follow_redirects=follow_redirects,\n max_redirects=max_redirects,\n event_hooks=event_hooks,\n base_url=base_url,\n trust_env=trust_env,\n default_encoding=default_encoding,\n )\n\n if http2:\n try:\n import h2 # noqa\n except ImportError: # pragma: no cover\n raise ImportError(\n \"Using http2=True, but the 'h2' package is not installed. \"\n \"Make sure to install httpx using `pip install httpx[http2]`.\"\n ) from None\n\n allow_env_proxies = trust_env and transport is None\n proxy_map = self._get_proxy_map(proxy, allow_env_proxies)\n\n self._transport = self._init_transport(\n verify=verify,\n cert=cert,\n trust_env=trust_env,\n http1=http1,\n http2=http2,\n limits=limits,\n transport=transport,\n )\n\n self._mounts: dict[URLPattern, AsyncBaseTransport | None] = {\n URLPattern(key): None\n if proxy is None\n else self._init_proxy_transport(\n proxy,\n verify=verify,\n cert=cert,\n trust_env=trust_env,\n http1=http1,\n http2=http2,\n limits=limits,\n )\n for key, proxy in proxy_map.items()\n }\n if mounts is not None:\n self._mounts.update(\n {URLPattern(key): transport for key, transport in mounts.items()}\n )\n self._mounts = dict(sorted(self._mounts.items()))\n\n def _init_transport(\n self,\n verify: ssl.SSLContext | str | bool = True,\n cert: CertTypes | None = None,\n trust_env: bool = True,\n http1: bool = True,\n http2: bool = False,\n limits: Limits = DEFAULT_LIMITS,\n transport: AsyncBaseTransport | None = None,\n ) -> AsyncBaseTransport:\n if transport is not None:\n return transport\n\n return AsyncHTTPTransport(\n verify=verify,\n cert=cert,\n trust_env=trust_env,\n http1=http1,\n http2=http2,\n limits=limits,\n )\n\n def _init_proxy_transport(\n self,\n proxy: Proxy,\n verify: ssl.SSLContext | str | bool = True,\n cert: CertTypes | None = None,\n trust_env: bool = True,\n http1: bool = True,\n http2: bool = False,\n limits: Limits = DEFAULT_LIMITS,\n ) -> AsyncBaseTransport:\n return AsyncHTTPTransport(\n verify=verify,\n cert=cert,\n trust_env=trust_env,\n http1=http1,\n http2=http2,\n limits=limits,\n proxy=proxy,\n )\n\n def _transport_for_url(self, url: URL) -> AsyncBaseTransport:\n \"\"\"\n Returns the transport instance that should be used for a given URL.\n This will either be the standard connection pool, or a proxy.\n \"\"\"\n for pattern, transport in self._mounts.items():\n if pattern.matches(url):\n return self._transport if transport is None else transport\n\n return self._transport\n\n async def request(\n self,\n method: str,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Build and send a request.\n\n Equivalent to:\n\n ```python\n request = client.build_request(...)\n response = await client.send(request, ...)\n ```\n\n See `AsyncClient.build_request()`, `AsyncClient.send()`\n and [Merging of configuration][0] for how the various parameters\n are merged with client-level configuration.\n\n [0]: /advanced/clients/#merging-of-configuration\n \"\"\"\n\n if cookies is not None: # pragma: no cover\n message = (\n \"Setting per-request cookies=<...> is being deprecated, because \"\n \"the expected behaviour on cookie persistence is ambiguous. Set \"\n \"cookies directly on the client instance instead.\"\n )\n warnings.warn(message, DeprecationWarning, stacklevel=2)\n\n request = self.build_request(\n method=method,\n url=url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n timeout=timeout,\n extensions=extensions,\n )\n return await self.send(request, auth=auth, follow_redirects=follow_redirects)\n\n @asynccontextmanager\n async def stream(\n self,\n method: str,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> typing.AsyncIterator[Response]:\n \"\"\"\n Alternative to `httpx.request()` that streams the response body\n instead of loading it into memory at once.\n\n **Parameters**: See `httpx.request`.\n\n See also: [Streaming Responses][0]\n\n [0]: /quickstart#streaming-responses\n \"\"\"\n request = self.build_request(\n method=method,\n url=url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n timeout=timeout,\n extensions=extensions,\n )\n response = await self.send(\n request=request,\n auth=auth,\n follow_redirects=follow_redirects,\n stream=True,\n )\n try:\n yield response\n finally:\n await response.aclose()\n\n async def send(\n self,\n request: Request,\n *,\n stream: bool = False,\n auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n ) -> Response:\n \"\"\"\n Send a request.\n\n The request is sent as-is, unmodified.\n\n Typically you'll want to build one with `AsyncClient.build_request()`\n so that any client-level configuration is merged into the request,\n but passing an explicit `httpx.Request()` is supported as well.\n\n See also: [Request instances][0]\n\n [0]: /advanced/clients/#request-instances\n \"\"\"\n if self._state == ClientState.CLOSED:\n raise RuntimeError(\"Cannot send a request, as the client has been closed.\")\n\n self._state = ClientState.OPENED\n follow_redirects = (\n self.follow_redirects\n if isinstance(follow_redirects, UseClientDefault)\n else follow_redirects\n )\n\n self._set_timeout(request)\n\n auth = self._build_request_auth(request, auth)\n\n response = await self._send_handling_auth(\n request,\n auth=auth,\n follow_redirects=follow_redirects,\n history=[],\n )\n try:\n if not stream:\n await response.aread()\n\n return response\n\n except BaseException as exc:\n await response.aclose()\n raise exc\n\n async def _send_handling_auth(\n self,\n request: Request,\n auth: Auth,\n follow_redirects: bool,\n history: list[Response],\n ) -> Response:\n auth_flow = auth.async_auth_flow(request)\n try:\n request = await auth_flow.__anext__()\n\n while True:\n response = await self._send_handling_redirects(\n request,\n follow_redirects=follow_redirects,\n history=history,\n )\n try:\n try:\n next_request = await auth_flow.asend(response)\n except StopAsyncIteration:\n return response\n\n response.history = list(history)\n await response.aread()\n request = next_request\n history.append(response)\n\n except BaseException as exc:\n await response.aclose()\n raise exc\n finally:\n await auth_flow.aclose()\n\n async def _send_handling_redirects(\n self,\n request: Request,\n follow_redirects: bool,\n history: list[Response],\n ) -> Response:\n while True:\n if len(history) > self.max_redirects:\n raise TooManyRedirects(\n \"Exceeded maximum allowed redirects.\", request=request\n )\n\n for hook in self._event_hooks[\"request\"]:\n await hook(request)\n\n response = await self._send_single_request(request)\n try:\n for hook in self._event_hooks[\"response\"]:\n await hook(response)\n\n response.history = list(history)\n\n if not response.has_redirect_location:\n return response\n\n request = self._build_redirect_request(request, response)\n history = history + [response]\n\n if follow_redirects:\n await response.aread()\n else:\n response.next_request = request\n return response\n\n except BaseException as exc:\n await response.aclose()\n raise exc\n\n async def _send_single_request(self, request: Request) -> Response:\n \"\"\"\n Sends a single request, without handling any redirections.\n \"\"\"\n transport = self._transport_for_url(request.url)\n start = time.perf_counter()\n\n if not isinstance(request.stream, AsyncByteStream):\n raise RuntimeError(\n \"Attempted to send a sync request with an AsyncClient instance.\"\n )\n\n with request_context(request=request):\n response = await transport.handle_async_request(request)\n\n assert isinstance(response.stream, AsyncByteStream)\n response.request = request\n response.stream = BoundAsyncStream(\n response.stream, response=response, start=start\n )\n self.cookies.extract_cookies(response)\n response.default_encoding = self._default_encoding\n\n logger.info(\n 'HTTP Request: %s %s \"%s %d %s\"',\n request.method,\n request.url,\n response.http_version,\n response.status_code,\n response.reason_phrase,\n )\n\n return response\n\n async def get(\n self,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `GET` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return await self.request(\n \"GET\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n async def options(\n self,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send an `OPTIONS` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return await self.request(\n \"OPTIONS\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n async def head(\n self,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `HEAD` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return await self.request(\n \"HEAD\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n async def post(\n self,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `POST` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return await self.request(\n \"POST\",\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n async def put(\n self,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `PUT` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return await self.request(\n \"PUT\",\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n async def patch(\n self,\n url: URL | str,\n *,\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: typing.Any | None = None,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `PATCH` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return await self.request(\n \"PATCH\",\n url,\n content=content,\n data=data,\n files=files,\n json=json,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n async def delete(\n self,\n url: URL | str,\n *,\n params: QueryParamTypes | None = None,\n headers: HeaderTypes | None = None,\n cookies: CookieTypes | None = None,\n auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,\n timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,\n extensions: RequestExtensions | None = None,\n ) -> Response:\n \"\"\"\n Send a `DELETE` request.\n\n **Parameters**: See `httpx.request`.\n \"\"\"\n return await self.request(\n \"DELETE\",\n url,\n params=params,\n headers=headers,\n cookies=cookies,\n auth=auth,\n follow_redirects=follow_redirects,\n timeout=timeout,\n extensions=extensions,\n )\n\n async def aclose(self) -> None:\n \"\"\"\n Close transport and proxies.\n \"\"\"\n if self._state != ClientState.CLOSED:\n self._state = ClientState.CLOSED\n\n await self._transport.aclose()\n for proxy in self._mounts.values():\n if proxy is not None:\n await proxy.aclose()\n\n async def __aenter__(self: U) -> U:\n if self._state != ClientState.UNOPENED:\n msg = {\n ClientState.OPENED: \"Cannot open a client instance more than once.\",\n ClientState.CLOSED: (\n \"Cannot reopen a client instance, once it has been closed.\"\n ),\n }[self._state]\n raise RuntimeError(msg)\n\n self._state = ClientState.OPENED\n\n await self._transport.__aenter__()\n for proxy in self._mounts.values():\n if proxy is not None:\n await proxy.__aenter__()\n return self\n\n async def __aexit__(\n self,\n exc_type: type[BaseException] | None = None,\n exc_value: BaseException | None = None,\n traceback: TracebackType | None = None,\n ) -> None:\n self._state = ClientState.CLOSED\n\n await self._transport.__aexit__(exc_type, exc_value, traceback)\n for proxy in self._mounts.values():\n if proxy is not None:\n await proxy.__aexit__(exc_type, exc_value, traceback)\n"
},
{
"path": "httpx/_config.py",
"content": "from __future__ import annotations\n\nimport os\nimport typing\n\nfrom ._models import Headers\nfrom ._types import CertTypes, HeaderTypes, TimeoutTypes\nfrom ._urls import URL\n\nif typing.TYPE_CHECKING:\n import ssl # pragma: no cover\n\n__all__ = [\"Limits\", \"Proxy\", \"Timeout\", \"create_ssl_context\"]\n\n\nclass UnsetType:\n pass # pragma: no cover\n\n\nUNSET = UnsetType()\n\n\ndef create_ssl_context(\n verify: ssl.SSLContext | str | bool = True,\n cert: CertTypes | None = None,\n trust_env: bool = True,\n) -> ssl.SSLContext:\n import ssl\n import warnings\n\n import certifi\n\n if verify is True:\n if trust_env and os.environ.get(\"SSL_CERT_FILE\"): # pragma: nocover\n ctx = ssl.create_default_context(cafile=os.environ[\"SSL_CERT_FILE\"])\n elif trust_env and os.environ.get(\"SSL_CERT_DIR\"): # pragma: nocover\n ctx = ssl.create_default_context(capath=os.environ[\"SSL_CERT_DIR\"])\n else:\n # Default case...\n ctx = ssl.create_default_context(cafile=certifi.where())\n elif verify is False:\n ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)\n ctx.check_hostname = False\n ctx.verify_mode = ssl.CERT_NONE\n elif isinstance(verify, str): # pragma: nocover\n message = (\n \"`verify=` is deprecated. \"\n \"Use `verify=ssl.create_default_context(cafile=...)` \"\n \"or `verify=ssl.create_default_context(capath=...)` instead.\"\n )\n warnings.warn(message, DeprecationWarning)\n if os.path.isdir(verify):\n return ssl.create_default_context(capath=verify)\n return ssl.create_default_context(cafile=verify)\n else:\n ctx = verify\n\n if cert: # pragma: nocover\n message = (\n \"`cert=...` is deprecated. Use `verify=` instead,\"\n \"with `.load_cert_chain()` to configure the certificate chain.\"\n )\n warnings.warn(message, DeprecationWarning)\n if isinstance(cert, str):\n ctx.load_cert_chain(cert)\n else:\n ctx.load_cert_chain(*cert)\n\n return ctx\n\n\nclass Timeout:\n \"\"\"\n Timeout configuration.\n\n **Usage**:\n\n Timeout(None) # No timeouts.\n Timeout(5.0) # 5s timeout on all operations.\n Timeout(None, connect=5.0) # 5s timeout on connect, no other timeouts.\n Timeout(5.0, connect=10.0) # 10s timeout on connect. 5s timeout elsewhere.\n Timeout(5.0, pool=None) # No timeout on acquiring connection from pool.\n # 5s timeout elsewhere.\n \"\"\"\n\n def __init__(\n self,\n timeout: TimeoutTypes | UnsetType = UNSET,\n *,\n connect: None | float | UnsetType = UNSET,\n read: None | float | UnsetType = UNSET,\n write: None | float | UnsetType = UNSET,\n pool: None | float | UnsetType = UNSET,\n ) -> None:\n if isinstance(timeout, Timeout):\n # Passed as a single explicit Timeout.\n assert connect is UNSET\n assert read is UNSET\n assert write is UNSET\n assert pool is UNSET\n self.connect = timeout.connect # type: typing.Optional[float]\n self.read = timeout.read # type: typing.Optional[float]\n self.write = timeout.write # type: typing.Optional[float]\n self.pool = timeout.pool # type: typing.Optional[float]\n elif isinstance(timeout, tuple):\n # Passed as a tuple.\n self.connect = timeout[0]\n self.read = timeout[1]\n self.write = None if len(timeout) < 3 else timeout[2]\n self.pool = None if len(timeout) < 4 else timeout[3]\n elif not (\n isinstance(connect, UnsetType)\n or isinstance(read, UnsetType)\n or isinstance(write, UnsetType)\n or isinstance(pool, UnsetType)\n ):\n self.connect = connect\n self.read = read\n self.write = write\n self.pool = pool\n else:\n if isinstance(timeout, UnsetType):\n raise ValueError(\n \"httpx.Timeout must either include a default, or set all \"\n \"four parameters explicitly.\"\n )\n self.connect = timeout if isinstance(connect, UnsetType) else connect\n self.read = timeout if isinstance(read, UnsetType) else read\n self.write = timeout if isinstance(write, UnsetType) else write\n self.pool = timeout if isinstance(pool, UnsetType) else pool\n\n def as_dict(self) -> dict[str, float | None]:\n return {\n \"connect\": self.connect,\n \"read\": self.read,\n \"write\": self.write,\n \"pool\": self.pool,\n }\n\n def __eq__(self, other: typing.Any) -> bool:\n return (\n isinstance(other, self.__class__)\n and self.connect == other.connect\n and self.read == other.read\n and self.write == other.write\n and self.pool == other.pool\n )\n\n def __repr__(self) -> str:\n class_name = self.__class__.__name__\n if len({self.connect, self.read, self.write, self.pool}) == 1:\n return f\"{class_name}(timeout={self.connect})\"\n return (\n f\"{class_name}(connect={self.connect}, \"\n f\"read={self.read}, write={self.write}, pool={self.pool})\"\n )\n\n\nclass Limits:\n \"\"\"\n Configuration for limits to various client behaviors.\n\n **Parameters:**\n\n * **max_connections** - The maximum number of concurrent connections that may be\n established.\n * **max_keepalive_connections** - Allow the connection pool to maintain\n keep-alive connections below this point. Should be less than or equal\n to `max_connections`.\n * **keepalive_expiry** - Time limit on idle keep-alive connections in seconds.\n \"\"\"\n\n def __init__(\n self,\n *,\n max_connections: int | None = None,\n max_keepalive_connections: int | None = None,\n keepalive_expiry: float | None = 5.0,\n ) -> None:\n self.max_connections = max_connections\n self.max_keepalive_connections = max_keepalive_connections\n self.keepalive_expiry = keepalive_expiry\n\n def __eq__(self, other: typing.Any) -> bool:\n return (\n isinstance(other, self.__class__)\n and self.max_connections == other.max_connections\n and self.max_keepalive_connections == other.max_keepalive_connections\n and self.keepalive_expiry == other.keepalive_expiry\n )\n\n def __repr__(self) -> str:\n class_name = self.__class__.__name__\n return (\n f\"{class_name}(max_connections={self.max_connections}, \"\n f\"max_keepalive_connections={self.max_keepalive_connections}, \"\n f\"keepalive_expiry={self.keepalive_expiry})\"\n )\n\n\nclass Proxy:\n def __init__(\n self,\n url: URL | str,\n *,\n ssl_context: ssl.SSLContext | None = None,\n auth: tuple[str, str] | None = None,\n headers: HeaderTypes | None = None,\n ) -> None:\n url = URL(url)\n headers = Headers(headers)\n\n if url.scheme not in (\"http\", \"https\", \"socks5\", \"socks5h\"):\n raise ValueError(f\"Unknown scheme for proxy URL {url!r}\")\n\n if url.username or url.password:\n # Remove any auth credentials from the URL.\n auth = (url.username, url.password)\n url = url.copy_with(username=None, password=None)\n\n self.url = url\n self.auth = auth\n self.headers = headers\n self.ssl_context = ssl_context\n\n @property\n def raw_auth(self) -> tuple[bytes, bytes] | None:\n # The proxy authentication as raw bytes.\n return (\n None\n if self.auth is None\n else (self.auth[0].encode(\"utf-8\"), self.auth[1].encode(\"utf-8\"))\n )\n\n def __repr__(self) -> str:\n # The authentication is represented with the password component masked.\n auth = (self.auth[0], \"********\") if self.auth else None\n\n # Build a nice concise representation.\n url_str = f\"{str(self.url)!r}\"\n auth_str = f\", auth={auth!r}\" if auth else \"\"\n headers_str = f\", headers={dict(self.headers)!r}\" if self.headers else \"\"\n return f\"Proxy({url_str}{auth_str}{headers_str})\"\n\n\nDEFAULT_TIMEOUT_CONFIG = Timeout(timeout=5.0)\nDEFAULT_LIMITS = Limits(max_connections=100, max_keepalive_connections=20)\nDEFAULT_MAX_REDIRECTS = 20\n"
},
{
"path": "httpx/_content.py",
"content": "from __future__ import annotations\n\nimport inspect\nimport warnings\nfrom json import dumps as json_dumps\nfrom typing import (\n Any,\n AsyncIterable,\n AsyncIterator,\n Iterable,\n Iterator,\n Mapping,\n)\nfrom urllib.parse import urlencode\n\nfrom ._exceptions import StreamClosed, StreamConsumed\nfrom ._multipart import MultipartStream\nfrom ._types import (\n AsyncByteStream,\n RequestContent,\n RequestData,\n RequestFiles,\n ResponseContent,\n SyncByteStream,\n)\nfrom ._utils import peek_filelike_length, primitive_value_to_str\n\n__all__ = [\"ByteStream\"]\n\n\nclass ByteStream(AsyncByteStream, SyncByteStream):\n def __init__(self, stream: bytes) -> None:\n self._stream = stream\n\n def __iter__(self) -> Iterator[bytes]:\n yield self._stream\n\n async def __aiter__(self) -> AsyncIterator[bytes]:\n yield self._stream\n\n\nclass IteratorByteStream(SyncByteStream):\n CHUNK_SIZE = 65_536\n\n def __init__(self, stream: Iterable[bytes]) -> None:\n self._stream = stream\n self._is_stream_consumed = False\n self._is_generator = inspect.isgenerator(stream)\n\n def __iter__(self) -> Iterator[bytes]:\n if self._is_stream_consumed and self._is_generator:\n raise StreamConsumed()\n\n self._is_stream_consumed = True\n if hasattr(self._stream, \"read\"):\n # File-like interfaces should use 'read' directly.\n chunk = self._stream.read(self.CHUNK_SIZE)\n while chunk:\n yield chunk\n chunk = self._stream.read(self.CHUNK_SIZE)\n else:\n # Otherwise iterate.\n for part in self._stream:\n yield part\n\n\nclass AsyncIteratorByteStream(AsyncByteStream):\n CHUNK_SIZE = 65_536\n\n def __init__(self, stream: AsyncIterable[bytes]) -> None:\n self._stream = stream\n self._is_stream_consumed = False\n self._is_generator = inspect.isasyncgen(stream)\n\n async def __aiter__(self) -> AsyncIterator[bytes]:\n if self._is_stream_consumed and self._is_generator:\n raise StreamConsumed()\n\n self._is_stream_consumed = True\n if hasattr(self._stream, \"aread\"):\n # File-like interfaces should use 'aread' directly.\n chunk = await self._stream.aread(self.CHUNK_SIZE)\n while chunk:\n yield chunk\n chunk = await self._stream.aread(self.CHUNK_SIZE)\n else:\n # Otherwise iterate.\n async for part in self._stream:\n yield part\n\n\nclass UnattachedStream(AsyncByteStream, SyncByteStream):\n \"\"\"\n If a request or response is serialized using pickle, then it is no longer\n attached to a stream for I/O purposes. Any stream operations should result\n in `httpx.StreamClosed`.\n \"\"\"\n\n def __iter__(self) -> Iterator[bytes]:\n raise StreamClosed()\n\n async def __aiter__(self) -> AsyncIterator[bytes]:\n raise StreamClosed()\n yield b\"\" # pragma: no cover\n\n\ndef encode_content(\n content: str | bytes | Iterable[bytes] | AsyncIterable[bytes],\n) -> tuple[dict[str, str], SyncByteStream | AsyncByteStream]:\n if isinstance(content, (bytes, str)):\n body = content.encode(\"utf-8\") if isinstance(content, str) else content\n content_length = len(body)\n headers = {\"Content-Length\": str(content_length)} if body else {}\n return headers, ByteStream(body)\n\n elif isinstance(content, Iterable) and not isinstance(content, dict):\n # `not isinstance(content, dict)` is a bit oddly specific, but it\n # catches a case that's easy for users to make in error, and would\n # otherwise pass through here, like any other bytes-iterable,\n # because `dict` happens to be iterable. See issue #2491.\n content_length_or_none = peek_filelike_length(content)\n\n if content_length_or_none is None:\n headers = {\"Transfer-Encoding\": \"chunked\"}\n else:\n headers = {\"Content-Length\": str(content_length_or_none)}\n return headers, IteratorByteStream(content) # type: ignore\n\n elif isinstance(content, AsyncIterable):\n headers = {\"Transfer-Encoding\": \"chunked\"}\n return headers, AsyncIteratorByteStream(content)\n\n raise TypeError(f\"Unexpected type for 'content', {type(content)!r}\")\n\n\ndef encode_urlencoded_data(\n data: RequestData,\n) -> tuple[dict[str, str], ByteStream]:\n plain_data = []\n for key, value in data.items():\n if isinstance(value, (list, tuple)):\n plain_data.extend([(key, primitive_value_to_str(item)) for item in value])\n else:\n plain_data.append((key, primitive_value_to_str(value)))\n body = urlencode(plain_data, doseq=True).encode(\"utf-8\")\n content_length = str(len(body))\n content_type = \"application/x-www-form-urlencoded\"\n headers = {\"Content-Length\": content_length, \"Content-Type\": content_type}\n return headers, ByteStream(body)\n\n\ndef encode_multipart_data(\n data: RequestData, files: RequestFiles, boundary: bytes | None\n) -> tuple[dict[str, str], MultipartStream]:\n multipart = MultipartStream(data=data, files=files, boundary=boundary)\n headers = multipart.get_headers()\n return headers, multipart\n\n\ndef encode_text(text: str) -> tuple[dict[str, str], ByteStream]:\n body = text.encode(\"utf-8\")\n content_length = str(len(body))\n content_type = \"text/plain; charset=utf-8\"\n headers = {\"Content-Length\": content_length, \"Content-Type\": content_type}\n return headers, ByteStream(body)\n\n\ndef encode_html(html: str) -> tuple[dict[str, str], ByteStream]:\n body = html.encode(\"utf-8\")\n content_length = str(len(body))\n content_type = \"text/html; charset=utf-8\"\n headers = {\"Content-Length\": content_length, \"Content-Type\": content_type}\n return headers, ByteStream(body)\n\n\ndef encode_json(json: Any) -> tuple[dict[str, str], ByteStream]:\n body = json_dumps(\n json, ensure_ascii=False, separators=(\",\", \":\"), allow_nan=False\n ).encode(\"utf-8\")\n content_length = str(len(body))\n content_type = \"application/json\"\n headers = {\"Content-Length\": content_length, \"Content-Type\": content_type}\n return headers, ByteStream(body)\n\n\ndef encode_request(\n content: RequestContent | None = None,\n data: RequestData | None = None,\n files: RequestFiles | None = None,\n json: Any | None = None,\n boundary: bytes | None = None,\n) -> tuple[dict[str, str], SyncByteStream | AsyncByteStream]:\n \"\"\"\n Handles encoding the given `content`, `data`, `files`, and `json`,\n returning a two-tuple of (, ).\n \"\"\"\n if data is not None and not isinstance(data, Mapping):\n # We prefer to separate `content=`\n # for raw request content, and `data=
![Failing PR commit status](\"https://raw.githubusercontent.com/encode/httpx/master/docs/img/gh-actions-fail.png\")
\n![Failing GitHub action lint job](\"https://raw.githubusercontent.com/encode/httpx/master/docs/img/gh-actions-fail-check.png\")
\n![Failing GitHub action test job](\"https://raw.githubusercontent.com/encode/httpx/master/docs/img/gh-actions-fail-test.png\")
\n![HTTPX](\"https://raw.githubusercontent.com/encode/httpx/master/docs/img/butterfly.png\")
\n![httpx --help](\"docs/img/httpx-help.png\")
\n![httpx http://httpbin.org/json](\"docs/img/httpx-request.png\")
\n![](\"https://upload.wikimedia.org/wikipedia/commons/thumb/2/27/Open_proxy_h2g2bob.svg/480px-Open_proxy_h2g2bob.svg.png\"/)
\n ![\"Test](\"https://github.com/encode/httpx/workflows/Test%20Suite/badge.svg\"){kind=icon}
\n![\"Package](\"https://badge.fury.io/py/httpx.svg\"){kind=icon}
\n![](\"/img/speakeasy.png\")
\n