diff --git a/README.md b/README.md index c9ba3023..d1ae1b1e 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,27 @@ $ pip install httpcore[http2] Here's an example of making an HTTP GET request using `httpcore`... +```python +with httpcore.SyncConnectionPool() as http: + http_version, status_code, reason_phrase, headers, stream = http.request( + method=b'GET', + url=(b'https', b'example.org', 443, b'/'), + headers=[(b'host', b'example.org'), (b'user-agent', 'httpcore')] + ) + + try: + body = b''.join([chunk for chunk in stream]) + finally: + stream.close() + + print(status_code, body) +``` + +Or, using async... + ```python async with httpcore.AsyncConnectionPool() as http: - http_version, status_code, reason_phrase, headers, stream = await http.request( + http_version, status_code, reason_phrase, headers, stream = await http.arequest( method=b'GET', url=(b'https', b'example.org', 443, b'/'), headers=[(b'host', b'example.org'), (b'user-agent', 'httpcore')] diff --git a/docs/api.md b/docs/api.md index dfda0013..3bbde423 100644 --- a/docs/api.md +++ b/docs/api.md @@ -7,7 +7,7 @@ interface which transport classes need to implement. ::: httpcore.AsyncHTTPTransport :docstring: - :members: request aclose + :members: arequest aclose ::: httpcore.AsyncByteStream :docstring: diff --git a/docs/index.md b/docs/index.md index 5d81f52d..d1ae1b1e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -41,11 +41,29 @@ $ pip install httpcore[http2] Here's an example of making an HTTP GET request using `httpcore`... +```python +with httpcore.SyncConnectionPool() as http: + http_version, status_code, reason_phrase, headers, stream = http.request( + method=b'GET', + url=(b'https', b'example.org', 443, b'/'), + headers=[(b'host', b'example.org'), (b'user-agent', 'httpcore')] + ) + + try: + body = b''.join([chunk for chunk in stream]) + finally: + stream.close() + + print(status_code, body) +``` + +Or, using async... + ```python async with httpcore.AsyncConnectionPool() as http: - http_version, status_code, reason_phrase, headers, stream = await http.request( + http_version, status_code, reason_phrase, headers, stream = await http.arequest( method=b'GET', - url=(b'https', b'example.org', 433, b'/'), + url=(b'https', b'example.org', 443, b'/'), headers=[(b'host', b'example.org'), (b'user-agent', 'httpcore')] ) diff --git a/httpcore/_async/base.py b/httpcore/_async/base.py index 410700be..9b0fc463 100644 --- a/httpcore/_async/base.py +++ b/httpcore/_async/base.py @@ -61,7 +61,7 @@ class AsyncHTTPTransport: the `request` method, and optionally the `close` method. """ - async def request( + async def arequest( self, method: bytes, url: URL, diff --git a/httpcore/_async/connection.py b/httpcore/_async/connection.py index 9f50dc5f..35fe2a26 100644 --- a/httpcore/_async/connection.py +++ b/httpcore/_async/connection.py @@ -66,7 +66,7 @@ def request_lock(self) -> AsyncLock: self._request_lock = self.backend.create_lock() return self._request_lock - async def request( + async def arequest( self, method: bytes, url: URL, @@ -92,9 +92,9 @@ async def request( assert self.connection is not None logger.trace( - "connection.request method=%r url=%r headers=%r", method, url, headers + "connection.arequest method=%r url=%r headers=%r", method, url, headers ) - return await self.connection.request(method, url, headers, stream, timeout) + return await self.connection.arequest(method, url, headers, stream, timeout) async def _open_socket(self, timeout: TimeoutDict = None) -> AsyncSocketStream: scheme, hostname, port = self.origin diff --git a/httpcore/_async/connection_pool.py b/httpcore/_async/connection_pool.py index 60a73cf6..c62812aa 100644 --- a/httpcore/_async/connection_pool.py +++ b/httpcore/_async/connection_pool.py @@ -38,7 +38,7 @@ def __init__( callback: Callable, ) -> None: """ - A wrapper around the response stream that we return from `.request()`. + A wrapper around the response stream that we return from `.arequest()`. Ensures that when `stream.aclose()` is called, the connection pool is notified via a callback. @@ -147,7 +147,7 @@ def _connection_acquiry_lock(self) -> AsyncLock: self._internal_connection_acquiry_lock = self._backend.create_lock() return self._internal_connection_acquiry_lock - async def request( + async def arequest( self, method: bytes, url: URL, @@ -189,7 +189,7 @@ async def request( logger.trace("reuse connection=%r", connection) try: - response = await connection.request( + response = await connection.arequest( method, url, headers=headers, stream=stream, timeout=timeout ) except NewConnectionRequired: diff --git a/httpcore/_async/http11.py b/httpcore/_async/http11.py index 0930bd39..d0c4bf54 100644 --- a/httpcore/_async/http11.py +++ b/httpcore/_async/http11.py @@ -47,7 +47,7 @@ def mark_as_ready(self) -> None: if self.state == ConnectionState.IDLE: self.state = ConnectionState.READY - async def request( + async def arequest( self, method: bytes, url: URL, diff --git a/httpcore/_async/http2.py b/httpcore/_async/http2.py index eafc43d2..1346f533 100644 --- a/httpcore/_async/http2.py +++ b/httpcore/_async/http2.py @@ -93,7 +93,7 @@ def mark_as_ready(self) -> None: if self.state == ConnectionState.IDLE: self.state = ConnectionState.READY - async def request( + async def arequest( self, method: bytes, url: URL, @@ -123,9 +123,9 @@ async def request( h2_stream = AsyncHTTP2Stream(stream_id=stream_id, connection=self) self.streams[stream_id] = h2_stream self.events[stream_id] = [] - return await h2_stream.request(method, url, headers, stream, timeout) + return await h2_stream.arequest(method, url, headers, stream, timeout) except Exception: # noqa: PIE786 - await self.max_streams_semaphore.release() + self.max_streams_semaphore.release() raise async def send_connection_init(self, timeout: TimeoutDict) -> None: @@ -277,7 +277,7 @@ def __init__(self, stream_id: int, connection: AsyncHTTP2Connection) -> None: self.stream_id = stream_id self.connection = connection - async def request( + async def arequest( self, method: bytes, url: URL, diff --git a/httpcore/_async/http_proxy.py b/httpcore/_async/http_proxy.py index fe6ec0b5..dc3fc9d6 100644 --- a/httpcore/_async/http_proxy.py +++ b/httpcore/_async/http_proxy.py @@ -79,7 +79,7 @@ def __init__( max_keepalive=max_keepalive, ) - async def request( + async def arequest( self, method: bytes, url: URL, @@ -158,7 +158,7 @@ async def _forward_request( reason_phrase, headers, stream, - ) = await connection.request( + ) = await connection.arequest( method, url, headers=headers, stream=stream, timeout=timeout ) @@ -207,7 +207,7 @@ async def _tunnel_request( proxy_reason_phrase, _, proxy_stream, - ) = await proxy_connection.request( + ) = await proxy_connection.arequest( b"CONNECT", connect_url, headers=connect_headers, timeout=timeout ) logger.trace( @@ -249,8 +249,12 @@ async def _tunnel_request( reason_phrase, headers, stream, - ) = await connection.request( - method, url, headers=headers, stream=stream, timeout=timeout + ) = await connection.arequest( + method, + url, + headers=headers, + stream=stream, + timeout=timeout, ) wrapped_stream = ResponseByteStream( diff --git a/httpcore/_sync/http_proxy.py b/httpcore/_sync/http_proxy.py index d09872bc..71805140 100644 --- a/httpcore/_sync/http_proxy.py +++ b/httpcore/_sync/http_proxy.py @@ -250,7 +250,11 @@ def _tunnel_request( headers, stream, ) = connection.request( - method, url, headers=headers, stream=stream, timeout=timeout + method, + url, + headers=headers, + stream=stream, + timeout=timeout, ) wrapped_stream = ResponseByteStream( diff --git a/tests/async_tests/test_interfaces.py b/tests/async_tests/test_interfaces.py index 18a6a254..a6f0f687 100644 --- a/tests/async_tests/test_interfaces.py +++ b/tests/async_tests/test_interfaces.py @@ -30,7 +30,7 @@ async def test_http_request(backend: str) -> None: method = b"GET" url = (b"http", b"example.org", 80, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -47,7 +47,7 @@ async def test_https_request(backend: str) -> None: method = b"GET" url = (b"https", b"example.org", 443, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -65,7 +65,7 @@ async def test_request_unsupported_protocol(backend: str) -> None: url = (b"ftp", b"example.org", 443, b"/") headers = [(b"host", b"example.org")] with pytest.raises(httpcore.UnsupportedProtocol): - await http.request(method, url, headers) + await http.arequest(method, url, headers) @pytest.mark.anyio @@ -74,7 +74,7 @@ async def test_http2_request(backend: str) -> None: method = b"GET" url = (b"https", b"example.org", 443, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -91,7 +91,7 @@ async def test_closing_http_request(backend: str) -> None: method = b"GET" url = (b"http", b"example.org", 80, b"/") headers = [(b"host", b"example.org"), (b"connection", b"close")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -108,7 +108,7 @@ async def test_http_request_reuse_connection(backend: str) -> None: method = b"GET" url = (b"http", b"example.org", 80, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -121,7 +121,7 @@ async def test_http_request_reuse_connection(backend: str) -> None: method = b"GET" url = (b"http", b"example.org", 80, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -138,7 +138,7 @@ async def test_https_request_reuse_connection(backend: str) -> None: method = b"GET" url = (b"https", b"example.org", 443, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -151,7 +151,7 @@ async def test_https_request_reuse_connection(backend: str) -> None: method = b"GET" url = (b"https", b"example.org", 443, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -168,7 +168,7 @@ async def test_http_request_cannot_reuse_dropped_connection(backend: str) -> Non method = b"GET" url = (b"http", b"example.org", 80, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -185,7 +185,7 @@ async def test_http_request_cannot_reuse_dropped_connection(backend: str) -> Non method = b"GET" url = (b"http", b"example.org", 80, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -209,7 +209,7 @@ async def test_http_proxy(proxy_server: URL, proxy_mode: str, backend: str) -> N max_connections=max_connections, backend=backend, ) as http: - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -230,7 +230,7 @@ async def test_http_request_local_address(backend: str) -> None: method = b"GET" url = (b"http", b"example.org", 80, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) @@ -259,7 +259,7 @@ async def test_proxy_https_requests( max_connections=max_connections, http2=http2, ) as http: - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) _ = await read_body(stream) @@ -313,8 +313,8 @@ async def test_connection_pool_get_connection_info( url = (b"https", b"example.org", 443, b"/") headers = [(b"host", b"example.org")] - _, _, _, _, stream_1 = await http.request(method, url, headers) - _, _, _, _, stream_2 = await http.request(method, url, headers) + _, _, _, _, stream_1 = await http.arequest(method, url, headers) + _, _, _, _, stream_2 = await http.arequest(method, url, headers) try: stats = await http.get_connection_info() @@ -344,7 +344,7 @@ async def test_http_request_unix_domain_socket( method = b"GET" url = (b"http", b"localhost", None, b"/") headers = [(b"host", b"localhost")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) assert http_version == b"HTTP/1.1" @@ -369,7 +369,7 @@ async def test_max_keepalive_connections_handled_correctly( connections_streams = [] for _ in range(connections_number): - _, _, _, _, stream = await http.request(method, url, headers) + _, _, _, _, stream = await http.arequest(method, url, headers) connections_streams.append(stream) try: @@ -388,7 +388,7 @@ async def test_explicit_backend_name() -> None: method = b"GET" url = (b"http", b"example.org", 80, b"/") headers = [(b"host", b"example.org")] - http_version, status_code, reason, headers, stream = await http.request( + http_version, status_code, reason, headers, stream = await http.arequest( method, url, headers ) await read_body(stream) diff --git a/unasync.py b/unasync.py index 6e9d17c0..ebf38a13 100755 --- a/unasync.py +++ b/unasync.py @@ -12,6 +12,7 @@ ('async with', 'with'), ('async for', 'for'), ('await ', ''), + ('arequest', 'request'), ('aclose', 'close'), ('aclose_func', 'close_func'), ('aiterator', 'iterator'),