### Send an HTTP GET Request with HTTPCore Source: https://github.com/encode/httpcore/blob/master/docs/index.md This example demonstrates how to send a simple GET request to a URL and print the response status, headers, and content. Ensure you have the httpcore library installed. ```python import httpcore response = httpcore.request("GET", "https://www.example.com/") print(response) # print(response.status) # 200 print(response.headers) # [(b'Accept-Ranges', b'bytes'), (b'Age', b'557328'), (b'Cache-Control', b'max-age=604800'), ...] print(response.content) # b'\n\n\nExample Domain\n\n\n ...' ``` -------------------------------- ### Install HTTPCore Source: https://github.com/encode/httpcore/blob/master/docs/index.md Install the package for HTTP/1.1 support. For HTTP/2, use `pip install httpcore[http2]`. For SOCKS proxy support, use `pip install httpcore[socks]`. ```shell pip install httpcore ``` -------------------------------- ### Using the Trace Extension for Event Monitoring Source: https://github.com/encode/httpcore/blob/master/docs/extensions.md This example demonstrates how to use the 'trace' extension to install a callback handler for monitoring internal httpcore events. The callback receives event names and associated information. ```python import httpcore def log(event_name, info): print(event_name, info) r = httpcore.request("GET", "https://www.example.com/", extensions={\"trace\": log}) # connection.connect_tcp.started {'host': 'www.example.com', 'port': 443, 'local_address': None, 'timeout': None} # connection.connect_tcp.complete {'return_value': } # connection.start_tls.started {'ssl_context': , 'server_hostname': b'www.example.com', 'timeout': None} # connection.start_tls.complete {'return_value': } # http11.send_request_headers.started {'request': } # http11.send_request_headers.complete {'return_value': None} # http11.send_request_body.started {'request': } # http11.send_request_body.complete {'return_value': None} # http11.receive_response_headers.started {'request': } # 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')])} # http11.receive_response_body.started {'request': } # http11.receive_response_body.complete {'return_value': None} # http11.response_closed.started {} ``` -------------------------------- ### Basic HTTP Proxy Usage Source: https://github.com/encode/httpcore/blob/master/docs/proxies.md Configure a connection pool to use an HTTP proxy for requests. This example demonstrates setting up a proxy and making a GET request. ```python import httpcore proxy = httpcore.Proxy("http://127.0.0.1:8080/") pool = httpcore.ConnectionPool(proxy=proxy) r = proxy.request("GET", "https://www.example.com/") print(r) # ``` -------------------------------- ### Install Asyncio Support Source: https://github.com/encode/httpcore/blob/master/docs/async.md Install HTTPCore with optional asyncio dependencies using pip. ```shell pip install 'httpcore[asyncio]' ``` -------------------------------- ### Install Trio Support Source: https://github.com/encode/httpcore/blob/master/docs/async.md Install HTTPCore with optional trio dependencies using pip. ```shell pip install 'httpcore[trio]' ``` -------------------------------- ### Async Request Examples Source: https://context7.com/encode/httpcore/llms.txt Demonstrates basic asynchronous request patterns, concurrent downloads using asyncio.gather, and handling streaming responses with httpcore. ```APIDOC ## Basic async request ```python import httpcore import asyncio async def main(): async with httpcore.AsyncConnectionPool() as http: response = await http.request("GET", "https://www.example.com/") print(response) # asyncio.run(main()) ``` ## Concurrent downloads with asyncio.gather ```python import httpcore import asyncio async def download(http, year): return await http.request("GET", f"https://en.wikipedia.org/wiki/{year}") async def main(): async with httpcore.AsyncConnectionPool(http2=True) as http: tasks = [download(http, year) for year in range(2000, 2020)] results = await asyncio.gather(*tasks) print(f"Fetched {len(results)} pages") for conn in http.connections: print(conn) # All requests on a single HTTP/2 connection asyncio.run(main()) ``` ## Async streaming response ```python import httpcore import asyncio async def main(): async with httpcore.AsyncConnectionPool() as http: async with http.stream("GET", "https://www.example.com/") as response: async for chunk in response.aiter_stream(): print(f"Received {len(chunk)} bytes") asyncio.run(main()) ``` ``` -------------------------------- ### Install httpcore with HTTP/2 support Source: https://github.com/encode/httpcore/blob/master/docs/http2.md Install the optional HTTP/2 dependencies for httpcore using pip. ```shell $ pip install 'httpcore[http2]' ``` -------------------------------- ### Request with Trace Extension Source: https://github.com/encode/httpcore/blob/master/docs/extensions.md The 'trace' extension allows a callback handler to be installed to monitor internal events within httpcore. This example shows how to set up a simple logging callback. ```APIDOC ## Request with Trace Extension ### Description This example demonstrates how to use the `trace` extension to monitor the internal flow of events within httpcore by providing a callback function. ### Method `httpcore.request` ### Endpoint `https://www.example.com/` ### Parameters #### Request Body None explicitly shown for this operation. #### Extensions - **trace** (Callable) - A callback function that receives event names and information dictionaries. ### Request Example ```python import httpcore def log(event_name, info): print(event_name, info) r = httpcore.request("GET", "https://www.example.com/", extensions={"trace": log}) ``` ### Response #### Success Response (200) - **extensions** (dict) - Contains response-specific extensions. - **http_version** (bytes) - The HTTP version used for the response. ``` -------------------------------- ### AnyIO Example Source: https://github.com/encode/httpcore/blob/master/docs/async.md This example shows how to perform concurrent HTTP requests using httpcore with the AnyIO library. AnyIO provides a unified API for asynchronous operations, working with either asyncio or Trio as backends. ```APIDOC ## AnyIO Example ### Description This example demonstrates making concurrent HTTP requests using `httpcore.AsyncConnectionPool` with the AnyIO library. AnyIO offers a backend-agnostic API for asynchronous programming, compatible with both `asyncio` and `trio`. ### Usage ```python import httpcore import anyio import time async def download(http, year): await http.request("GET", f"https://en.wikipedia.org/wiki/{year}") async def main(): async with httpcore.AsyncConnectionPool() as http: started = time.time() async with anyio.create_task_group() as task_group: for year in range(2000, 2020): task_group.start_soon(download, http, year) complete = time.time() for connection in http.connections: print(connection) print("Complete in %.3f seconds" % (complete - started)) anyio.run(main) ``` ``` -------------------------------- ### Install HTTP Core Source: https://github.com/encode/httpcore/blob/master/README.md Install the package with pip. Optional extras can be included for specific features like asyncio, trio, http2, or SOCKS proxy support. ```shell $ pip install httpcore ``` ```shell $ pip install httpcore['asyncio,trio,http2,socks'] ``` -------------------------------- ### Configuring Connect and Pool Timeouts Source: https://github.com/encode/httpcore/blob/master/docs/extensions.md This example shows how to configure both connection and connection pool timeouts using the 'timeout' extension in an httpcore request. ```python # Timeout if a connection takes more than 5 seconds to established, or if # we are blocked waiting on the connection pool for more than 10 seconds. r = httpcore.request( "GET", "https://www.example.com", extensions={\"timeout\": {\"connect\": 5.0, \"pool\": 10.0}} ) ``` -------------------------------- ### Trio Example Source: https://github.com/encode/httpcore/blob/master/docs/async.md This example illustrates concurrent HTTP requests using httpcore with the Trio library. It employs Trio's structured concurrency features, specifically `trio.open_nursery` and `nursery.start_soon`, for managing concurrent tasks. ```APIDOC ## Trio Example ### Description This example demonstrates making concurrent HTTP requests using `httpcore.AsyncConnectionPool` with the Trio library. It utilizes Trio's structured concurrency primitives like `trio.open_nursery` and `nursery.start_soon` to manage concurrent tasks. ### Usage ```python import httpcore import trio import time async def download(http, year): await http.request("GET", f"https://en.wikipedia.org/wiki/{year}") async def main(): async with httpcore.AsyncConnectionPool() as http: started = time.time() async with trio.open_nursery() as nursery: for year in range(2000, 2020): nursery.start_soon(download, http, year) complete = time.time() for connection in http.connections: print(connection) print("Complete in %.3f seconds" % (complete - started)) trio.run(main) ``` ``` -------------------------------- ### Example httpcore Debug Log Output Source: https://github.com/encode/httpcore/blob/master/docs/logging.md This is an example of the debug-level log output you might see when using httpcore. The exact format may vary between versions. ```text DEBUG [2023-01-09 14:44:00] httpcore.connection - connect_tcp.started host='www.example.com' port=443 local_address=None timeout=None DEBUG [2023-01-09 14:44:00] httpcore.connection - connect_tcp.complete return_value= DEBUG [2023-01-09 14:44:00] httpcore.connection - start_tls.started ssl_context= server_hostname='www.example.com' timeout=None DEBUG [2023-01-09 14:44:00] httpcore.connection - start_tls.complete return_value= DEBUG [2023-01-09 14:44:00] httpcore.http11 - send_request_headers.started request= DEBUG [2023-01-09 14:44:00] httpcore.http11 - send_request_headers.complete DEBUG [2023-01-09 14:44:00] httpcore.http11 - send_request_body.started request= DEBUG [2023-01-09 14:44:00] httpcore.http11 - send_request_body.complete DEBUG [2023-01-09 14:44:00] httpcore.http11 - receive_response_headers.started request= DEBUG [2023-01-09 14:44:00] httpcore.http11 - receive_response_headers.complete return_value=(b'HTTP/1.1', 200, b'OK', [(b'Age', b'572646'), (b'Cache-Control', b'max-age=604800'), (b'Content-Type', b'text/html; charset=UTF-8'), (b'Date', b'Mon, 09 Jan 2023 14:44:00 GMT'), (b'Etag', b'"3147526947+ident"'), (b'Expires', b'Mon, 16 Jan 2023 14:44:00 GMT'), (b'Last-Modified', b'Thu, 17 Oct 2019 07:18:26 GMT'), (b'Server', b'ECS (nyb/1D18)'), (b'Vary', b'Accept-Encoding'), (b'X-Cache', b'HIT'), (b'Content-Length', b'1256')]) DEBUG [2023-01-09 14:44:00] httpcore.http11 - receive_response_body.started request= DEBUG [2023-01-09 14:44:00] httpcore.http11 - receive_response_body.complete DEBUG [2023-01-09 14:44:00] httpcore.http11 - response_closed.started DEBUG [2023-01-09 14:44:00] httpcore.http11 - response_closed.complete DEBUG [2023-01-09 14:44:00] httpcore.connection - close.started DEBUG [2023-01-09 14:44:00] httpcore.connection - close.complete ``` -------------------------------- ### Compare HTTP/1.1 and HTTP/2 performance Source: https://github.com/encode/httpcore/blob/master/docs/http2.md Benchmark concurrent requests using a standard HTTP/1.1 connection pool versus an HTTP/2 enabled pool. This example demonstrates issuing multiple GET requests to Wikipedia and measuring the completion time. ```python import httpcore import concurrent.futures import time def download(http, year): http.request("GET", f"https://en.wikipedia.org/wiki/{year}") def main(): with httpcore.ConnectionPool() as http: started = time.time() with concurrent.futures.ThreadPoolExecutor(max_workers=10) as threads: for year in range(2000, 2020): threads.submit(download, http, year) complete = time.time() for connection in http.connections: print(connection) print("Complete in %.3f seconds" % (complete - started)) main() ``` ```python with httpcore.ConnectionPool(http2=True) as http: ... ``` -------------------------------- ### Send Basic HTTP/1.1 Request Directly with SyncBackend Source: https://github.com/encode/httpcore/blob/master/docs/network-backends.md This example shows how to use SyncBackend to directly connect, upgrade to SSL, send a raw HTTP/1.1 request, and read the response. It requires an SSL context and constructs the request as a bytestring. ```python import httpcore # Create an SSL context using 'certifi' for the certificates. ssl_context = httpcore.default_ssl_context() # A basic HTTP/1.1 request as a plain bytestring. request = b'\r\n'.join([ b'GET / HTTP/1.1', b'Host: www.example.com', b'Accept: */*', b'Connection: close', b'' ]) # Open a TCP stream and upgrade it to SSL. network_backend = httpcore.SyncBackend() network_stream = network_backend.connect_tcp("www.example.com", 443) network_stream = network_stream.start_tls(ssl_context, server_hostname="www.example.com") # Send the HTTP request. network_stream.write(request) # Read the HTTP response. while True: response = network_stream.read(max_bytes=4096) if response == b'': break print(response) # The output should look something like this: # # b'HTTP/1.1 200 OK\r\nAge: 600005\r\n [...] Content-Length: 1256\r\nConnection: close\r\n\r\n' # b'\n\n\n Example Domain [...] \n' ``` -------------------------------- ### Basic Async Request with httpcore Source: https://context7.com/encode/httpcore/llms.txt Demonstrates a simple asynchronous GET request using httpcore's AsyncConnectionPool. Ensure asyncio is imported and run. ```python import httpcore import asyncio async def main(): async with httpcore.AsyncConnectionPool() as http: response = await http.request("GET", "https://www.example.com/") print(response) # ``` ```python asyncio.run(main()) ``` -------------------------------- ### AsyncIO Example Source: https://github.com/encode/httpcore/blob/master/docs/async.md This example shows how to make concurrent HTTP requests using httpcore's AsyncConnectionPool with Python's built-in asyncio library. It utilizes `asyncio.gather` to run multiple request tasks simultaneously. ```APIDOC ## AsyncIO Example ### Description This example demonstrates making concurrent HTTP requests using `httpcore.AsyncConnectionPool` with Python's `asyncio` library. It leverages `asyncio.gather` to execute multiple request tasks concurrently. ### Usage ```python import asyncio import httpcore import time async def download(http, year): await http.request("GET", f"https://en.wikipedia.org/wiki/{year}") async def main(): async with httpcore.AsyncConnectionPool() as http: started = time.time() # Here we use `asyncio.gather()` in order to run several tasks concurrently... tasks = [download(http, year) for year in range(2000, 2020)] await asyncio.gather(*tasks) complete = time.time() for connection in http.connections: print(connection) print("Complete in %.3f seconds" % (complete - started)) asyncio.run(main()) ``` ``` -------------------------------- ### Instantiate and Use a Connection Pool Source: https://github.com/encode/httpcore/blob/master/docs/connection-pools.md Instantiate a connection pool and use its .request() method to send a GET request. The pool manages underlying network connections for efficiency. ```python import httpcore http = httpcore.ConnectionPool() r = http.request("GET", "https://www.example.com/") print(r) # ``` -------------------------------- ### Concurrent Requests with AnyIO Source: https://github.com/encode/httpcore/blob/master/docs/async.md Employ AnyIO's create_task_group for structured concurrency, compatible with both asyncio and Trio backends. Ensure AnyIO is installed. ```python import httpcore import anyio import time async def download(http, year): await http.request("GET", f"https://en.wikipedia.org/wiki/{year}") async def main(): async with httpcore.AsyncConnectionPool() as http: started = time.time() async with anyio.create_task_group() as task_group: for year in range(2000, 2020): task_group.start_soon(download, http, year) complete = time.time() for connection in http.connections: print(connection) print("Complete in %.3f seconds" % (complete - started)) anyio.run(main) ``` -------------------------------- ### SOCKS Proxy Support Source: https://github.com/encode/httpcore/blob/master/docs/proxies.md Configure httpcore to use a SOCKS5 proxy. Ensure the optional `socks` dependency is installed (`pip install 'httpcore[socks]'`). ```python import httpcore # Note that the SOCKS port is 1080. proxy = httpcore.Proxy(url="socks5://127.0.0.1:1080/") pool = httpcore.ConnectionPool(proxy=proxy) r = pool.request("GET", "https://www.example.com/") ``` -------------------------------- ### HTTPS Proxy with Custom SSL Context Source: https://github.com/encode/httpcore/blob/master/docs/proxies.md When using HTTPS proxies, you may need to configure the SSL context. This example shows how to create and pass a custom SSL context to the Proxy. ```python import ssl import httpcore proxy_ssl_context = ssl.create_default_context() proxy_ssl_context.check_hostname = False proxy = httpcore.Proxy( url='https://127.0.0.1:8080/', ssl_context=proxy_ssl_context ) pool = httpcore.ConnectionPool(proxy=proxy) ``` -------------------------------- ### Configure Logging for httpcore Source: https://github.com/encode/httpcore/blob/master/docs/logging.md Configure Python's logging to output DEBUG level information from httpcore. This setup directs logs to stdout. ```python import logging import httpcore logging.basicConfig( format="%(levelname)s [%(asctime)s] %(name)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S", level=logging.DEBUG ) httpcore.request('GET', 'https://www.example.com') ``` -------------------------------- ### Pin HTTP Core Version Source: https://github.com/encode/httpcore/blob/master/README.md It is recommended to pin your requirements to a specific major version or a version range for stability. This example shows how to pin to the latest 1.x version. ```shell pip install 'httpcore==1.*' ``` -------------------------------- ### SOCKS5 Proxy Configuration Source: https://context7.com/encode/httpcore/llms.txt Configures a SOCKS5 proxy for requests using httpcore.Proxy. Requires `pip install httpcore[socks]`. Supports authentication. ```python import httpcore # SOCKS5 proxy (requires: pip install httpcore[socks]) proxy = httpcore.Proxy( url="socks5://127.0.0.1:1080/", auth=("socksuser", "sockspass"), ) with httpcore.ConnectionPool(proxy=proxy) as http: response = http.request("GET", "https://www.example.com/") print(response) # ``` -------------------------------- ### Handle WebSocket Upgrade Requests with wsproto Source: https://github.com/encode/httpcore/blob/master/docs/extensions.md Use the wsproto package to manage a WebSocket session after an HTTP upgrade. This example demonstrates sending and receiving text messages and closing the connection. ```python import httpcore import wsproto import os import base64 url = "http://127.0.0.1:8000/" headers = { b"Connection": b"Upgrade", b"Upgrade": b"WebSocket", b"Sec-WebSocket-Key": base64.b64encode(os.urandom(16)), b"Sec-WebSocket-Version": b"13" } with httpcore.stream("GET", url, headers=headers) as response: if response.status != 101: raise Exception("Failed to upgrade to websockets", response) # Get the raw network stream. network_steam = response.extensions["network_stream"] # Write a WebSocket text frame to the stream. ws_connection = wsproto.Connection(wsproto.ConnectionType.CLIENT) message = wsproto.events.TextMessage("hello, world!") outgoing_data = ws_connection.send(message) network_steam.write(outgoing_data) # Wait for a response. incoming_data = network_steam.read(max_bytes=4096) ws_connection.receive_data(incoming_data) for event in ws_connection.events(): if isinstance(event, wsproto.events.TextMessage): print("Got data:", event.data) # Write a WebSocket close to the stream. message = wsproto.events.CloseConnection(code=1000) outgoing_data = ws_connection.send(message) network_steam.write(outgoing_data) ``` -------------------------------- ### Send One-Shot HTTP Request with httpcore.request() Source: https://context7.com/encode/httpcore/llms.txt Use for simple, single requests where connection reuse is not critical. Supports GET, POST, custom headers, and content. Can configure timeouts via extensions. ```python import httpcore # Basic GET request response = httpcore.request("GET", "https://www.example.com/") print(response) # print(response.status) # 200 print(response.headers) # [(b'Content-Type', b'text/html'), ...] print(response.content) # b'...' # POST with body and custom headers response = httpcore.request( "POST", "https://httpbin.org/post", headers={"Content-Type": "application/json", "User-Agent": "my-app/1.0"}, content=b'{"key": "value"}', ) print(response.status) # 200 # With timeout extensions response = httpcore.request( "GET", "https://www.example.com", extensions={"timeout": {"connect": 5.0, "read": 10.0, "pool": 10.0}}, ) ``` -------------------------------- ### Explicitly Select SyncBackend for HTTP Request Source: https://github.com/encode/httpcore/blob/master/docs/network-backends.md Demonstrates how to explicitly select and use the httpcore.SyncBackend with a ConnectionPool for making HTTP requests. This is useful for understanding the underlying architecture. ```python import httpcore network_backend = httpcore.SyncBackend() with httpcore.ConnectionPool(network_backend=network_backend) as http: response = http.request('GET', 'https://www.example.com') print(response) ``` -------------------------------- ### Httpcore.Proxy Configuration Source: https://context7.com/encode/httpcore/llms.txt Shows how to configure httpcore.Proxy for HTTP, HTTPS, and SOCKS5 proxies, including basic authentication and custom headers. ```APIDOC ## `httpcore.Proxy` — HTTP and SOCKS proxy support Configures proxy routing for a `ConnectionPool`. Supports HTTP forward/tunnel proxies (for `http://` and `https://` targets respectively), HTTPS proxies, and SOCKS5 proxies. Authentication can be passed as a tuple or via custom headers. ```python import httpcore import base64 # HTTP proxy (forwarding for http://, tunnelling for https://) proxy = httpcore.Proxy("http://127.0.0.1:8080/") with httpcore.ConnectionPool(proxy=proxy) as http: response = http.request("GET", "https://www.example.com/") print(response) # # Proxy with basic authentication proxy = httpcore.Proxy( url="http://127.0.0.1:8080/", auth=("myuser", "mypassword"), # Sends Proxy-Authorization header ) with httpcore.ConnectionPool(proxy=proxy) as http: response = http.request("GET", "https://httpbin.org/ip") # Proxy with custom headers (manual auth encoding) auth_token = base64.b64encode(b"myuser:mypassword") proxy = httpcore.Proxy( url="http://127.0.0.1:8080/", headers={\"Proxy-Authorization\": b"Basic " + auth_token}, ) # SOCKS5 proxy (requires: pip install httpcore[socks]) proxy = httpcore.Proxy( url="socks5://127.0.0.1:1080/", auth=("socksuser", "sockspass"), ) with httpcore.ConnectionPool(proxy=proxy) as http: response = http.request("GET", "https://www.example.com/") print(response) # # HTTPS proxy with custom SSL context import ssl proxy_ssl_ctx = ssl.create_default_context() proxy_ssl_ctx.check_hostname = False proxy = httpcore.Proxy(url="https://127.0.0.1:8080/", ssl_context=proxy_ssl_ctx) ``` ``` -------------------------------- ### Response Extensions Source: https://github.com/encode/httpcore/blob/master/docs/extensions.md Response objects in httpcore can contain extensions, providing additional information about the HTTP exchange. The 'http_version' extension is an example. ```APIDOC ## Response Extensions ### Description Response objects from httpcore can include an `extensions` dictionary. This section details how to access such extensions, using `http_version` as an example. ### Method `httpcore.request` (implicitly, when accessing response attributes) ### Endpoint `https://www.example.com` ### Parameters None directly applicable to accessing response extensions. ### Request Example ```python import httpcore r = httpcore.request("GET", "https://www.example.com") print(r.extensions["http_version"]) ``` ### Response #### Success Response (200) - **extensions** (dict) - A dictionary containing optional extension data. - **http_version** (bytes) - Indicates the HTTP version of the response (e.g., b"HTTP/1.1"). ``` -------------------------------- ### Handle CONNECT Requests with Network Stream Source: https://github.com/encode/httpcore/blob/master/docs/extensions.md Demonstrates using the 'network_stream' extension to handle CONNECT requests, including upgrading to an SSL stream and manually sending/receiving data. ```python # Formulate a CONNECT request... # # This will establish a connection to 127.0.0.1:8080, and then send the following... # # CONNECT http://www.example.com HTTP/1.1 url = "http://127.0.0.1:8080" extensions = {"target: "http://www.example.com"} with httpcore.stream("CONNECT", url, extensions=extensions) as response: network_stream = response.extensions["network_stream"] # Upgrade to an SSL stream... network_stream = network_stream.start_tls( ssl_context=httpcore.default_ssl_context(), hostname=b"www.example.com", ) # Manually send an HTTP request over the network stream, and read the response... # # For a more complete example see the httpcore `TunnelHTTPConnection` implementation. network_stream.write(b"GET / HTTP/1.1\r\nHost: example.com\r\n\r\n") data = network_stream.read() print(data) ``` -------------------------------- ### Instantiate ConnectionPool with HTTP/2 enabled Source: https://github.com/encode/httpcore/blob/master/docs/http2.md Create a connection pool instance with HTTP/2 support enabled by setting the `http2` parameter to `True`. ```python import httpcore pool = httpcore.ConnectionPool(http2=True) ``` -------------------------------- ### Concurrent Requests with Trio Source: https://github.com/encode/httpcore/blob/master/docs/async.md Utilize Trio's open_nursery to manage concurrent download tasks. Trio's structured concurrency ensures proper task management. ```python import httpcore import trio import time async def download(http, year): await http.request("GET", f"https://en.wikipedia.org/wiki/{year}") async def main(): async with httpcore.AsyncConnectionPool() as http: started = time.time() async with trio.open_nursery() as nursery: for year in range(2000, 2020): nursery.start_soon(download, http, year) complete = time.time() for connection in http.connections: print(connection) print("Complete in %.3f seconds" % (complete - started)) trio.run(main) ``` -------------------------------- ### httpcore.backends.mock.MockBackend Source: https://github.com/encode/httpcore/blob/master/docs/table-of-contents.md Mock network backend for testing (sync). ```APIDOC ## httpcore.backends.mock.MockBackend ### Description A mock network backend for synchronous testing purposes. ### Usage (Details not provided in source) ### Methods (Details not provided in source) ``` -------------------------------- ### Request with Timeout Extension Source: https://github.com/encode/httpcore/blob/master/docs/extensions.md The 'timeout' extension allows specifying timeout values for different stages of a request. This example shows how to set connect and pool timeouts. ```APIDOC ## Request with Timeout Extension ### Description This example demonstrates how to use the `timeout` extension to configure connection and pool timeouts for an HTTP request. ### Method `httpcore.request` ### Endpoint `https://www.example.com` ### Parameters #### Request Body None explicitly shown for this operation. #### Extensions - **timeout** (dict) - A dictionary of timeout values. - **connect** (Optional[float]) - Timeout for establishing a connection. - **pool** (Optional[float]) - Timeout for waiting on the connection pool. ### Request Example ```python import httpcore r = httpcore.request( "GET", "https://www.example.com", extensions={"timeout": {"connect": 5.0, "pool": 10.0}} ) ``` ### Response #### Success Response (200) - **extensions** (dict) - Contains response-specific extensions. - **http_version** (bytes) - The HTTP version used for the response. ``` -------------------------------- ### Create and Inspect HTTP Request Source: https://github.com/encode/httpcore/blob/master/docs/requests-responses-urls.md Demonstrates creating a basic HTTP request object and accessing its core properties like method, URL, headers, and stream. ```python >>> request = httpcore.Request("GET", "https://www.example.com/") >>> request.method b"GET" >>> request.url httpcore.URL(scheme=b"https", host=b"www.example.com", port=None, target=b"/") >>> request.headers [(b'Host', b'www.example.com')] >>> request.stream ``` -------------------------------- ### Get SSL Object Information Source: https://github.com/encode/httpcore/blob/master/docs/extensions.md Access the SSL object from the network stream to retrieve TLS version information. Ensure the connection is still open before attempting to access this. ```python with httpcore.stream("GET", "https://www.example.com") as response: network_stream = response.extensions["network_stream"] ssl_object = network_stream.get_extra_info("ssl_object") print("TLS version", ssl_object.version()) ``` -------------------------------- ### Basic Connection Pool Usage Source: https://github.com/encode/httpcore/blob/master/docs/connection-pools.md Demonstrates the instantiation and basic usage of a ConnectionPool to send requests. This highlights the core functionality of reusing connections for subsequent requests. ```APIDOC ## Basic Connection Pool Usage ### Description Instantiate a `httpcore.ConnectionPool` and use its `.request()` method to send HTTP requests. This approach benefits from connection reuse, leading to improved performance for multiple requests to the same host. ### Method `httpcore.ConnectionPool()` ### Endpoint N/A (This is an SDK instantiation) ### Parameters None for instantiation in this basic example. ### Request Example ```python import httpcore http = httpcore.ConnectionPool() r = http.request("GET", "https://www.example.com/") print(r) ``` ### Response #### Success Response (200) Represents the HTTP response object. #### Response Example ``` ``` ``` -------------------------------- ### httpcore.backends.sync.SyncBackend Source: https://github.com/encode/httpcore/blob/master/docs/table-of-contents.md Synchronous network backend implementation. ```APIDOC ## httpcore.backends.sync.SyncBackend ### Description Provides a synchronous implementation for network operations. ### Usage (Details not provided in source) ### Methods (Details not provided in source) ``` -------------------------------- ### Pluggable Network Backends Source: https://context7.com/encode/httpcore/llms.txt Utilize different network backends for custom I/O behavior, such as testing with a mock backend or integrating with async runtimes. The SyncBackend is the default. ```python import httpcore # Explicit sync backend (default behavior, made explicit) backend = httpcore.SyncBackend() with httpcore.ConnectionPool(network_backend=backend) as http: response = http.request("GET", "https://www.example.com/") ``` ```python # Mock backend for testing — no real network calls network_backend = httpcore.MockBackend([ b"HTTP/1.1 200 OK\r\n", b"Content-Type: text/plain\r\n", b"Content-Length: 13\r\n", b"\r\n", b"Hello, world!", ]) with httpcore.ConnectionPool(network_backend=network_backend) as http: response = http.request("GET", "https://example.com/") assert response.status == 200 assert response.content == b"Hello, world!" ``` -------------------------------- ### httpcore.request() Source: https://github.com/encode/httpcore/blob/master/docs/table-of-contents.md Initiates an HTTP request and returns the response. ```APIDOC ## httpcore.request() ### Description Initiates an HTTP request and returns the response. ### Method Not specified (likely a function call within a Python SDK) ### Endpoint N/A ### Parameters (Details not provided in source) ### Request Example (Not provided in source) ### Response (Details not provided in source) ``` -------------------------------- ### Managing Pool Lifespan with Context Manager Source: https://github.com/encode/httpcore/blob/master/docs/connection-pools.md Illustrates how to manage the lifecycle of a ConnectionPool using a context manager for explicit resource management. ```APIDOC ## Pool Lifespan with Context Manager ### Description Use the `httpcore.ConnectionPool` as a context manager (`with` statement) to ensure that network resources are properly closed when the block is exited, even if errors occur. ### Method `with httpcore.ConnectionPool() as http:` ### Endpoint N/A (This is an SDK usage pattern) ### Parameters None for the context manager usage itself. ### Request Example ```python import httpcore with httpcore.ConnectionPool() as http: response = http.request("GET", "https://www.example.com/") # ... further operations ... # Pool is automatically closed here ``` ### Response N/A (This example focuses on resource management) ``` -------------------------------- ### httpcore.backends.asyncio.AsyncioBackend Source: https://github.com/encode/httpcore/blob/master/docs/table-of-contents.md Asyncio-based network backend implementation. ```APIDOC ## httpcore.backends.asyncio.AsyncioBackend ### Description Provides an asynchronous network backend implementation utilizing Python's asyncio library. ### Usage (Details not provided in source) ### Methods (Details not provided in source) ``` -------------------------------- ### Mock HTTP/1.1 Response with MockBackend Source: https://github.com/encode/httpcore/blob/master/docs/network-backends.md Use MockBackend to simulate a simple HTTP/1.1 response. This is useful for testing client behavior without making real network calls. ```python import httpcore network_backend = httpcore.MockBackend([ b"HTTP/1.1 200 OK\r\n", b"Content-Type: plain/text\r\n", b"Content-Length: 13\r\n", b"\r\n", b"Hello, world!", ]) with httpcore.ConnectionPool(network_backend=network_backend) as http: response = http.request("GET", "https://example.com/") print(response.extensions['http_version']) print(response.status) print(response.content) ``` -------------------------------- ### Connection Pool Configuration Options Source: https://github.com/encode/httpcore/blob/master/docs/connection-pools.md Details the various configuration options available when creating a ConnectionPool instance, allowing for fine-tuned control over connection behavior. ```APIDOC ## Connection Pool Configuration ### Description Configure a `httpcore.ConnectionPool` instance with various options to customize its behavior regarding SSL, pooling limits, HTTP version support, and network settings. ### Method `httpcore.ConnectionPool(...options...) ### Endpoint N/A (This is an SDK instantiation) ### Parameters #### Initialization Parameters * `ssl_context` (SSLContext, optional): An SSL context for verifying connections. Defaults to `httpcore.default_ssl_context()`. * `max_connections` (int, optional): Maximum number of concurrent HTTP connections. Blocks if exceeded. * `max_keepalive_connections` (int, optional): Maximum number of idle HTTP connections to maintain. * `keepalive_expiry` (float, optional): Duration in seconds for idle connection expiry. * `http1` (bool, optional): Enable HTTP/1.1 support. Defaults to `True`. * `http2` (bool, optional): Enable HTTP/2 support. Defaults to `False`. * `retries` (int, optional): Maximum number of retries for establishing a connection. * `local_address` (str, optional): Local address for outgoing connections (e.g., "0.0.0.0" for IPv4, "::" for IPv6). * `uds` (str, optional): Path to a Unix Domain Socket to use instead of TCP. * `network_backend` (NetworkBackend, optional): Backend for network I/O. * `socket_options` (list, optional): Options to apply to TCP sockets upon establishment. ### Request Example ```python import httpcore http = httpcore.ConnectionPool( max_connections=10, keepalive_expiry=60, http2=True ) ``` ### Response N/A (Configuration is applied during instantiation) ``` -------------------------------- ### Mock HTTP/2 Response with MockBackend Source: https://github.com/encode/httpcore/blob/master/docs/network-backends.md Mocking an HTTP/2 response requires constructing frames in binary format. Instantiate MockBackend with `http2=True` to enable HTTP/2 behavior. ```python import hpack import hyperframe.frame import httpcore content = [ hyperframe.frame.SettingsFrame().serialize(), hyperframe.frame.HeadersFrame( stream_id=1, data=hpack.Encoder().encode( [ (b":status", b"200"), (b"content-type", b"plain/text"), ] ), flags=["END_HEADERS"], ).serialize(), hyperframe.frame.DataFrame( stream_id=1, data=b"Hello, world!", flags=["END_STREAM"] ).serialize(), ] # Note that we instantiate the mock backend with an `http2=True` argument. # This ensures that the mock network stream acts as if the `h2` ALPN flag has been set, # and causes the connection pool to interact with the connection using HTTP/2. network_backend = httpcore.MockBackend(content, http2=True) with httpcore.ConnectionPool(network_backend=network_backend) as http: response = http.request("GET", "https://example.com/") print(response.extensions['http_version']) print(response.status) print(response.content) ``` -------------------------------- ### httpcore.backends.mock.AsyncMockBackend Source: https://github.com/encode/httpcore/blob/master/docs/table-of-contents.md Mock network backend for testing (async). ```APIDOC ## httpcore.backends.mock.AsyncMockBackend ### Description A mock network backend for asynchronous testing purposes. ### Usage (Details not provided in source) ### Methods (Details not provided in source) ``` -------------------------------- ### httpcore.backends.base.NetworkBackend Source: https://github.com/encode/httpcore/blob/master/docs/table-of-contents.md Base interface for synchronous network backends. ```APIDOC ## httpcore.backends.base.NetworkBackend ### Description Defines the interface for synchronous network backends. ### Usage (Details not provided in source) ### Methods (Details not provided in source) ``` -------------------------------- ### Concurrent Downloads with asyncio.gather Source: https://context7.com/encode/httpcore/llms.txt Shows how to perform multiple asynchronous downloads concurrently using asyncio.gather and httpcore.AsyncConnectionPool with HTTP/2 enabled. All requests are made on a single HTTP/2 connection. ```python import httpcore import asyncio async def download(http, year): return await http.request("GET", f"https://en.wikipedia.org/wiki/{year}") async def main(): async with httpcore.AsyncConnectionPool(http2=True) as http: tasks = [download(http, year) for year in range(2000, 2020)] results = await asyncio.gather(*tasks) print(f"Fetched {len(results)} pages") for conn in http.connections: print(conn) # All requests on a single HTTP/2 connection ``` ```python asyncio.run(main()) ``` -------------------------------- ### Making a Request with Timeout Extension Source: https://github.com/encode/httpcore/blob/master/docs/extensions.md Demonstrates how to include the 'timeout' extension in an httpcore request to specify connection timeout values. ```python r = httpcore.request( "GET", "https://www.example.com", extensions={\"timeout\": {\"connect\": 5.0}} ) ``` -------------------------------- ### Download Large Files with httpcore Streaming Source: https://github.com/encode/httpcore/blob/master/docs/quickstart.md Demonstrates downloading a large file by streaming the response content and writing it to a local file chunk by chunk. ```python import httpcore with httpcore.stream('GET', 'https://speed.hetzner.de/100MB.bin') as response: with open("download.bin", "wb") as output_file: for chunk in response.iter_stream(): output_file.write(chunk) ``` -------------------------------- ### Proxy Authentication with Username and Password Source: https://github.com/encode/httpcore/blob/master/docs/proxies.md Include proxy authentication credentials directly in the Proxy configuration. A `Proxy-Authorization` header will be automatically added to the initial proxy connection. ```python import httpcore # A `Proxy-Authorization` header will be included on the initial proxy connection. proxy = httpcore.Proxy( url="http://127.0.0.1:8080/", auth=("", "") ) pool = httpcore.ConnectionPool(proxy=proxy) ``` -------------------------------- ### httpcore.backends.auto.AutoBackend Source: https://github.com/encode/httpcore/blob/master/docs/table-of-contents.md Automatically selects the appropriate network backend. ```APIDOC ## httpcore.backends.auto.AutoBackend ### Description Automatically detects and selects the most suitable network backend based on the environment. ### Usage (Details not provided in source) ### Methods (Details not provided in source) ``` -------------------------------- ### Custom Network Backend for Recording Responses Source: https://github.com/encode/httpcore/blob/master/docs/network-backends.md Implement a custom network backend by subclassing `httpcore.NetworkBackend` and `httpcore.NetworkStream` to record network traffic to a file. This allows for detailed inspection of raw request/response data. ```python import httpcore class RecordingNetworkStream(httpcore.NetworkStream): def __init__(self, record_file, stream): self.record_file = record_file self.stream = stream def read(self, max_bytes, timeout=None): data = self.stream.read(max_bytes, timeout=timeout) self.record_file.write(data) return data def write(self, buffer, timeout=None): self.stream.write(buffer, timeout=timeout) def close(self) -> None: self.stream.close() def start_tls( self, ssl_context, server_hostname=None, timeout=None, ): self.stream = self.stream.start_tls( ssl_context, server_hostname=server_hostname, timeout=timeout ) return self def get_extra_info(self, info): return self.stream.get_extra_info(info) class RecordingNetworkBackend(httpcore.NetworkBackend): """ A custom network backend that records network responses. """ def __init__(self, record_file): self.record_file = record_file self.backend = httpcore.SyncBackend() def connect_tcp( self, host, port, timeout=None, local_address=None, socket_options=None, ): # Note that we're only using a single record file here, # so even if multiple connections are opened the network # traffic will all write to the same file. # An alternative implementation might automatically use # a new file for each opened connection. stream = self.backend.connect_tcp( host, port, timeout=timeout, local_address=local_address, socket_options=socket_options ) return RecordingNetworkStream(self.record_file, stream) # Once you make the request, the raw HTTP/1.1 response will be available # in the 'network-recording' file. # # Try switching to `http2=True` to see the difference when recording HTTP/2 binary network traffic, # or add `headers={'Accept-Encoding': 'gzip'}` to see HTTP content compression. with open("network-recording", "wb") as record_file: network_backend = RecordingNetworkBackend(record_file) with httpcore.ConnectionPool(network_backend=network_backend) as http: response = http.request("GET", "https://www.example.com/") print(response) ``` -------------------------------- ### Observe Connection Pooling Performance Benefits Source: https://github.com/encode/httpcore/blob/master/docs/connection-pools.md Demonstrates the performance improvement of connection pooling by making multiple requests to the same host. Subsequent requests are faster due to connection reuse. ```python import httpcore import time http = httpcore.ConnectionPool() for counter in range(5): started = time.time() response = http.request("GET", "https://www.example.com/") complete = time.time() print(response, "in %.3f seconds" % (complete - started)) ``` -------------------------------- ### httpcore.backends.trio.TrioBackend Source: https://github.com/encode/httpcore/blob/master/docs/table-of-contents.md Trio-based network backend implementation. ```APIDOC ## httpcore.backends.trio.TrioBackend ### Description Provides an asynchronous network backend implementation utilizing the Trio library. ### Usage (Details not provided in source) ### Methods (Details not provided in source) ``` -------------------------------- ### Manage Async Pool Lifespan with Context Manager Source: https://github.com/encode/httpcore/blob/master/docs/async.md Instantiate and use httpcore.AsyncConnectionPool with an async context manager for recommended pool management. ```python async with httpcore.AsyncConnectionPool() as http: ... ``` -------------------------------- ### httpcore.UnsupportedProtocol Source: https://github.com/encode/httpcore/blob/master/docs/table-of-contents.md Exception raised for unsupported protocols. ```APIDOC ## httpcore.UnsupportedProtocol ### Description Exception raised when an attempt is made to use a protocol that is not supported. ### Usage (Details not provided in source) ``` -------------------------------- ### Proxy Authentication with Custom Headers Source: https://github.com/encode/httpcore/blob/master/docs/proxies.md Manually construct and include a `Proxy-Authorization` header for proxy authentication. This allows for custom authorization schemes. ```python import httpcore import base64 # Construct and include a `Proxy-Authorization` header. auth = base64.b64encode(b":") proxy = httpcore.Proxy( url="http://127.0.0.1:8080/", headers={"Proxy-Authorization": b"Basic " + auth} ) pool = httpcore.ConnectionPool(proxy=proxy) ```