impit 0.2.1__cp313-cp313-musllinux_1_2_x86_64.whl → 0.9.0__cp313-cp313-musllinux_1_2_x86_64.whl

impit/__init__.py

@@ -1,9 +1,39 @@
+from importlib import metadata
 from typing import Literal
 
+from .cookies import Cookies
 from .impit import (
     AsyncClient,
     Client,
+    CloseError,
+    ConnectError,
+    ConnectTimeout,
+    CookieConflict,
+    DecodingError,
+    HTTPError,
+    HTTPStatusError,
+    InvalidURL,
+    LocalProtocolError,
+    NetworkError,
+    PoolTimeout,
+    ProtocolError,
+    ProxyError,
+    ReadError,
+    ReadTimeout,
+    RemoteProtocolError,
+    RequestError,
+    RequestNotRead,
     Response,
+    ResponseNotRead,
+    StreamClosed,
+    StreamConsumed,
+    StreamError,
+    TimeoutException,
+    TooManyRedirects,
+    TransportError,
+    UnsupportedProtocol,
+    WriteError,
+    WriteTimeout,
     delete,
     get,
     head,
@@ -11,14 +41,46 @@ from .impit import (
     patch,
     post,
     put,
+    stream,
     trace,
 )
 
+__version__ = metadata.version('impit')
+
 __all__ = [
     'AsyncClient',
     'Browser',
     'Client',
+    'CloseError',
+    'ConnectError',
+    'ConnectTimeout',
+    'CookieConflict',
+    'Cookies',
+    'DecodingError',
+    'HTTPError',
+    'HTTPStatusError',
+    'InvalidURL',
+    'LocalProtocolError',
+    'NetworkError',
+    'PoolTimeout',
+    'ProtocolError',
+    'ProxyError',
+    'ReadError',
+    'ReadTimeout',
+    'RemoteProtocolError',
+    'RequestError',
+    'RequestNotRead',
     'Response',
+    'ResponseNotRead',
+    'StreamClosed',
+    'StreamConsumed',
+    'StreamError',
+    'TimeoutException',
+    'TooManyRedirects',
+    'TransportError',
+    'UnsupportedProtocol',
+    'WriteError',
+    'WriteTimeout',
     'delete',
     'get',
     'head',
@@ -26,6 +88,7 @@ __all__ = [
     'patch',
     'post',
     'put',
+    'stream',
     'trace',
 ]
 

impit/cookies.py

@@ -0,0 +1,177 @@
+"""Copyright © 2019, [Encode OSS Ltd](https://www.encode.io/).
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+# ruff: noqa: SIM102, E501
+
+## The Cookies class below is a modification of the `httpx.Cookies` class, licensed under the BSD 3-Clause "New" License.
+
+from __future__ import annotations
+
+import typing
+from http.cookiejar import Cookie, CookieJar
+
+from .impit import CookieConflict
+
+CookieTypes = typing.Union['Cookies', CookieJar, dict[str, str], list[tuple[str, str]]]
+
+
+class Cookies(typing.MutableMapping[str, str]):
+    """HTTP Cookies, as a mutable mapping."""
+
+    def __init__(self, cookies: CookieTypes | None = None) -> None:
+        if cookies is None or isinstance(cookies, dict):
+            self.jar = CookieJar()
+            if isinstance(cookies, dict):
+                for key, value in cookies.items():
+                    self.set(key, value)
+        elif isinstance(cookies, list):
+            self.jar = CookieJar()
+            for key, value in cookies:
+                self.set(key, value)
+        elif isinstance(cookies, Cookies):
+            self.jar = CookieJar()
+            for cookie in cookies.jar:
+                self.jar.set_cookie(cookie)
+        else:
+            self.jar = cookies
+
+    def set(self, name: str, value: str, domain: str = '', path: str = '/') -> None:
+        """Set a cookie value by name. May optionally include domain and path."""
+        kwargs = {
+            'version': 0,
+            'name': name,
+            'value': value,
+            'port': None,
+            'port_specified': False,
+            'domain': domain,
+            'domain_specified': bool(domain),
+            'domain_initial_dot': domain.startswith('.'),
+            'path': path,
+            'path_specified': bool(path),
+            'secure': False,
+            'expires': None,
+            'discard': True,
+            'comment': None,
+            'comment_url': None,
+            'rest': {'HttpOnly': None},
+            'rfc2109': False,
+        }
+        cookie = Cookie(**kwargs)  # type: ignore[arg-type]
+        self.jar.set_cookie(cookie)
+
+    def get(  # type: ignore[override]
+        self,
+        name: str,
+        default: str | None = None,
+        domain: str | None = None,
+        path: str | None = None,
+    ) -> str | None:
+        """Get a cookie by name.
+
+        May optionally include domain and path in order to specify exactly which cookie to retrieve.
+        """
+        value = None
+        for cookie in self.jar:
+            if cookie.name == name:
+                if domain is None or cookie.domain == domain:
+                    if path is None or cookie.path == path:
+                        if value is not None:
+                            message = f'Multiple cookies exist with name={name}'
+                            raise CookieConflict(message)
+                        value = cookie.value
+
+        if value is None:
+            return default
+        return value
+
+    def delete(
+        self,
+        name: str,
+        domain: str | None = None,
+        path: str | None = None,
+    ) -> None:
+        """Delete a cookie by name.
+
+        May optionally include domain and path in order to specify exactly which cookie to delete.
+        """
+        if domain is not None and path is not None:
+            return self.jar.clear(domain, path, name)
+
+        remove = [
+            cookie
+            for cookie in self.jar
+            if cookie.name == name
+            and (domain is None or cookie.domain == domain)
+            and (path is None or cookie.path == path)
+        ]
+
+        for cookie in remove:
+            self.jar.clear(cookie.domain, cookie.path, cookie.name)
+        return None
+
+    def clear(self, domain: str | None = None, path: str | None = None) -> None:
+        """Delete all cookies.
+
+        Optionally include a domain and path in order to only delete a subset of all the cookies.
+        """
+        args = []
+        if domain is not None:
+            args.append(domain)
+        if path is not None:
+            assert domain is not None  # noqa: S101
+            args.append(path)
+        self.jar.clear(*args)
+
+    def update(self, cookies: CookieTypes | None = None) -> None:  # type: ignore[override]
+        """Update the cookie jar with new cookies. Accepts various types."""
+        cookies = Cookies(cookies)
+        for cookie in cookies.jar:
+            self.jar.set_cookie(cookie)
+
+    def __setitem__(self, name: str, value: str) -> None:
+        """Set a cookie by name."""
+        return self.set(name, value)
+
+    def __getitem__(self, name: str) -> str:
+        """Get a cookie by name."""
+        value = self.get(name)
+        if value is None:
+            raise KeyError(name)
+        return value
+
+    def __delitem__(self, name: str) -> None:
+        """Delete a cookie by name."""
+        return self.delete(name)
+
+    def __len__(self) -> int:
+        """Return the number of cookies in the jar."""
+        return len(self.jar)
+
+    def __iter__(self) -> typing.Iterator[str]:
+        """Return an iterator over the names of the cookies in the jar."""
+        return (cookie.name for cookie in self.jar)
+
+    def __bool__(self) -> bool:
+        """Return True if there are any cookies in the jar."""
+        for _ in self.jar:
+            return True
+        return False
+
+    def __repr__(self) -> str:
+        """Return a string representation of the Cookies object."""
+        cookies_repr = ', '.join(
+            [f'<Cookie {cookie.name}={cookie.value} for {cookie.domain} />' for cookie in self.jar]
+        )
+
+        return f'<Cookies[{cookies_repr}]>'

impit/impit.pyi

@@ -1,44 +1,449 @@
 from __future__ import annotations
+from http.cookiejar import CookieJar
+from .cookies import Cookies
 
-from typing import Literal
+from typing import Literal, Any
+from collections.abc import Iterator, AsyncIterator
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
 
 
 Browser = Literal['chrome', 'firefox']
 
 
+class HTTPError(Exception):
+    """Represents an HTTP-related error."""
+
+
+class RequestError(HTTPError):
+    """Represents an error during the request process."""
+
+
+class TransportError(RequestError):
+    """Represents a transport-layer error."""
+
+
+class TimeoutException(TransportError):
+    """Represents a timeout error."""
+
+
+class ConnectTimeout(TimeoutException):
+    """Represents a connection timeout error."""
+
+
+class ReadTimeout(TimeoutException):
+    """Represents a read timeout error."""
+
+
+class WriteTimeout(TimeoutException):
+    """Represents a write timeout error."""
+
+
+class PoolTimeout(TimeoutException):
+    """Represents a connection pool timeout error."""
+
+
+class NetworkError(TransportError):
+    """Represents a network-related error."""
+
+
+class ConnectError(NetworkError):
+    """Represents a connection error."""
+
+
+class ReadError(NetworkError):
+    """Represents a read error."""
+
+
+class WriteError(NetworkError):
+    """Represents a write error."""
+
+
+class CloseError(NetworkError):
+    """Represents an error when closing a connection."""
+
+
+class ProtocolError(TransportError):
+    """Represents a protocol-related error."""
+
+
+class LocalProtocolError(ProtocolError):
+    """Represents a local protocol error."""
+
+
+class RemoteProtocolError(ProtocolError):
+    """Represents a remote protocol error."""
+
+
+class ProxyError(TransportError):
+    """Represents a proxy-related error."""
+
+
+class UnsupportedProtocol(TransportError):
+    """Represents an unsupported protocol error."""
+
+
+class DecodingError(RequestError):
+    """Represents an error during response decoding."""
+
+
+class TooManyRedirects(RequestError):
+    """Represents an error due to excessive redirects."""
+
+
+class HTTPStatusError(HTTPError):
+    """Represents an error related to HTTP status codes."""
+
+
+class InvalidURL(Exception):
+    """Represents an error due to an invalid URL."""
+
+
+class CookieConflict(Exception):
+    """Represents a cookie conflict error."""
+
+
+class StreamError(Exception):
+    """Represents a stream-related error."""
+
+
+class StreamConsumed(StreamError):
+    """Represents an error when a stream is already consumed."""
+
+
+class ResponseNotRead(StreamError):
+    """Represents an error when a response is not read."""
+
+
+class RequestNotRead(StreamError):
+    """Represents an error when a request is not read."""
+
+
+class StreamClosed(StreamError):
+    """Represents an error when a stream is closed."""
+
 class Response:
-    """Response object returned by impit requests."""
+    """Response object returned by impit clients (:class:`Client` or :class:`AsyncClient` instances).
+
+    When constructed manually (e.g. for testing purposes), the following parameters can be provided:
+
+    Args:
+        status_code: HTTP status code of the response (e.g., 200, 404)
+        content: Response body as bytes (or None for empty body)
+        headers: Response headers as a dictionary (or None for empty headers)
+        default_encoding: Default encoding for the response text. Used only if `content-type` header is not present or does not specify a charset.
+        url: Final URL of the response.
+    """
 
     status_code: int
-    """HTTP status code (e.g., 200, 404)"""
+    """HTTP status code of the response (e.g., 200, 404).
+
+    .. tip::
+
+        If the status code indicates an error (4xx or 5xx), you can raise an `HTTPStatusError` exception using the :meth:`raise_for_status` method.
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.status_code) # 200
+    """
 
     reason_phrase: str
-    """HTTP reason phrase (e.g., 'OK', 'Not Found')"""
+    """HTTP reason phrase for the response (e.g., 'OK', 'Not Found'). This maps the numerical :attr:`status_code` to a human-readable string.
+
+     .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.reason_phrase) # 'OK'
+    """
 
     http_version: str
-    """HTTP version (e.g., 'HTTP/1.1', 'HTTP/2')"""
+    """HTTP version (e.g., 'HTTP/1.1', 'HTTP/2') negotiated for the response during the TLS handshake.
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.http_version) # 'HTTP/2'
+    """
 
     headers: dict[str, str]
-    """Response headers as a dictionary"""
+    """Response headers as a Python dictionary.
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.headers) # {'content-type': 'text/html; charset=utf-8', ... }
+    """
 
     text: str
-    """Response body as text. Decoded from `content` using `encoding`."""
+    """Response body as text. Decoded from :attr:`content` using :attr:`encoding`.
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.text) # '<!DOCTYPE html>...'
+    """
 
     encoding: str
-    """Response content encoding"""
+    """Response content encoding. Determined from `content-type` header or by bytestream prescan. Falls back to 'utf-8' if not found.
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.encoding) # 'utf-8'
+
+    This can be used to decode the `Response` body manually. By default, :attr:`text` uses this encoding to decode :attr:`content`.
+    """
 
     is_redirect: bool
-    """Whether the response is a redirect"""
+    """`True` if the response is a redirect (has a 3xx status code), `False` otherwise.
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.is_redirect) # False
+    """
 
     url: str
-    """Final URL"""
+    """The final URL of the response. This may differ from the requested URL if redirects were followed (see the `follow_redirects` parameter in :class:`Client` and :class:`AsyncClient`).
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.url) # 'https://crawlee.dev'
+    """
 
     content: bytes
-    """Response body as bytes"""
+    """Contains the response body as bytes. If the response was created with `stream=True`, this will be empty until the content is read using :meth:`read` or :meth:`iter_bytes`.
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.content) # b'<!DOCTYPE html>...'
+    """
+
+    is_closed: bool
+    """
+    True if the response has been closed using the :meth:`close` method, `False` otherwise.
+
+    Closing a response releases any underlying resources (e.g., network connections).
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev")
+        print(response.is_closed) # False
+        response.close()
+        print(response.is_closed) # True
+    """
+
+    is_stream_consumed: bool
+    """Whether the response stream has been consumed or closed.
+
+    If this is `True`, calling :meth:`read` or :meth:`iter_bytes` will raise a :class:`StreamConsumed` or :class:`StreamClosed` error.
+
+    The read response body is still available in the :attr:`content` attribute.
+
+    .. code-block:: python
+
+        response = await client.get("https://crawlee.dev", stream=True)
+        print(response.is_stream_consumed) # False
+        for chunk in response.iter_bytes():
+            pass
+        print(response.is_stream_consumed) # True
+        # calling response.read() or response.iter_bytes() again will raise StreamConsumed error
+        # read the content of the response using response.content
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        *,
+        content: bytes | None = None,
+        headers: dict[str, str] | None = None,
+        default_encoding: str | None = None,
+        url: str | None = None,
+    ) -> None:
+        """Initialize a Response object.
+
+        Args:
+            status_code: HTTP status code
+            content: Response body as bytes
+            headers: Response headers as a dictionary
+            default_encoding: Default encoding for the response text. Used only if `content-type` header is not present or does not specify a charset.
+            url: Final URL of the response
+        """
+
+    def read(self) -> bytes:
+        """Read the response content as bytes. Synchronous version of :meth:`aread`.
+
+        Useful for consuming the entire response body in one go (not chunked).
+
+        .. code-block:: python
+
+            with Client() as client:
+                with client.stream("GET", "https://example.com/largefile") as response:
+                    content = response.read()
+                    process(content)  # Process the entire content at once
+        """
+    def iter_bytes(self) -> Iterator[bytes]:
+        """Iterate over the response content in chunks. Synchronous version of :meth:`aiter_bytes`.
+
+        Useful for streaming large responses without loading the entire content into memory.
+        .. code-block:: python
+
+            with Client() as client:
+                with client.stream("GET", "https://example.com/largefile") as response:
+                    for chunk in response.iter_bytes():
+                        process(chunk)  # Process each chunk as it is received
+        """
+
+    async def aread(self) -> bytes:
+        """Asynchronously read the response content as bytes. Asynchronous version of :meth:`read`.
+
+        Useful for consuming the entire response body in one go (not chunked).
+
+        .. code-block:: python
+
+            async with AsyncClient() as client:
+                async with client.stream("GET", "https://example.com/largefile") as response:
+                    content = await response.aread()
+                    process(content)  # Process the entire content at once
+        """
+
+    def aiter_bytes(self) -> AsyncIterator[bytes]:
+        """Asynchronously iterate over the response content in chunks. Asynchronous version of :meth:`iter_bytes`.
+
+        Useful for streaming large responses without loading the entire content into memory.
+
+        .. code-block:: python
+
+            async with AsyncClient() as client:
+                async with client.stream("GET", "https://example.com/largefile") as response:
+                    async for chunk in response.aiter_bytes():
+                        process(chunk)  # Process each chunk as it is received
+        """
+
+    def json(self) -> Any:
+        """Parse the response content as JSON.
+
+        .. note::
+            This method will raise a `DecodingError` if the response content is not valid JSON.
+
+        .. code-block:: python
+
+            response = await client.get("https://api.example.com/data")
+            data = response.json()
+            print(data)  # Parsed JSON data as a Python object (dict, list, etc.)
+        """
+
+    def close(self) -> None:
+        """Close the response and release resources.
+
+        .. warning::
+            You should not need to call this method directly.
+
+            Use the `with` statement to ensure proper resource management when working with synchronous clients.
+
+            .. code-block:: python
 
+                with impit.stream('GET', get_httpbin_url('/')) as response:
+                    assert response.status_code == 200
+
+                assert response.is_closed is True
+        """
+
+    async def aclose(self) -> None:
+        """Asynchronously close the response and release resources.
+
+        .. note::
+            This method is for internal use only.
+
+            Use the `async with` statement to ensure proper resource management when working with asynchronous clients.
+
+            .. code-block:: python
+
+                async with impit.stream('GET', get_httpbin_url('/')) as response:
+                    assert response.status_code == 200
+
+                assert response.is_closed is True
+        """
 
 class Client:
-    """Synchronous HTTP client with browser impersonation capabilities."""
+    """Synchronous HTTP client with browser impersonation capabilities.
+
+        .. note::
+            You can reuse the :class:`Client` instance to make multiple requests.
+
+            All requests made by the same client will share the same configuration, resources (e.g., cookie jar and connection pool), and other settings.
+
+        Args:
+            browser: Browser to impersonate (`"chrome"` or `"firefox"`).
+
+                If this is `None` (default), no impersonation is performed.
+            http3:
+
+                If set to `True`, Impit will try to connect to the target servers using HTTP/3 protocol (if supported by the server).
+
+                .. note::
+                    The HTTP/3 support is experimental and may not work with all servers. The impersonation capabilities are limited when using HTTP/3.
+
+            proxy:
+
+                The proxy URL to use for all the requests made by this client.
+
+                This can be an HTTP, HTTPS, or SOCKS proxy.
+            timeout:
+                Default request timeout in seconds.
+
+                This value can be overridden for individual requests.
+            verify:
+                If set to `False`, impit will not verify SSL certificates.
+
+                This can be used to ignore TLS errors (e.g., self-signed certificates).
+
+                True by default.
+            default_encoding:
+                Default encoding for response.text field (e.g., "utf-8", "cp1252").
+
+                Overrides `content-type` headers and bytestream prescan.
+            follow_redirects:
+
+                If set to `True` the client will automatically follow HTTP redirects (3xx responses).
+
+                `False` by default.
+            max_redirects:
+
+                Maximum number of redirects to follow if the `follow_redirects` option is enabled.
+
+                Default is 20.
+            cookie_jar:
+
+                Cookie jar to store cookies in.
+
+                This is a `http.cookiejar.CookieJar` instance.
+
+                By default, :class:`Client` doesn't store cookies between requests.
+            cookies: httpx-compatible cookies object.
+
+                These are the cookies to include in all requests (to the matching servers) made by this client.
+            headers: Default HTTP headers to include in requests.
+
+                These headers will be included in all requests made by this client.
+
+                Default is an empty dictionary.
+            local_address:
+
+                Local address to bind the client to.
+
+                Useful for testing purposes or when you want to bind the client to a specific network interface.
+                Can be an IP address in the format `xxx.xxx.xxx.xxx` (for IPv4) or `ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff` (for IPv6).
+        """
+
+    def __enter__(self) -> Client:
+        """Enter the runtime context related to this object."""
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: object | None) -> None:
+        """Exit the runtime context related to this object."""
+
 
     def __init__(
         self,
@@ -50,6 +455,10 @@ class Client:
         default_encoding: str | None = None,
         follow_redirects: bool | None = None,
         max_redirects: int | None = None,
+        cookie_jar: CookieJar | None = None,
+        cookies: Cookies | None = None,
+        headers: dict[str, str] | None = None,
+        local_address: str | None = None,
     ) -> None:
         """Initialize a synchronous HTTP client.
 
@@ -63,6 +472,11 @@ class Client:
                 header and bytestream prescan.
             follow_redirects: Whether to follow redirects (default: False)
             max_redirects: Maximum number of redirects to follow (default: 20)
+            cookie_jar: Cookie jar to store cookies in.
+            cookies: httpx-compatible cookies object.
+            headers: Default HTTP headers to include in requests.
+            local_address: Local address to bind the client to. Useful for testing purposes or when you want to bind the client to a specific network interface.
+                Can be an IP address in the format "xxx.xxx.xxx.xxx" (for IPv4) or "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" (for IPv6).
         """
 
     def get(
@@ -235,9 +649,44 @@ class Client:
         headers: dict[str, str] | None = None,
         timeout: float | None = None,
         force_http3: bool | None = None,
+        stream: bool = False,
     ) -> Response:
         """Make an HTTP request with the specified method.
 
+        Args:
+            method: HTTP method (e.g., "get", "post")
+            url: URL to request
+            content: Raw content to send
+            data: Form data to send in request body
+            headers: HTTP headers
+            timeout: Request timeout in seconds (overrides default timeout)
+            force_http3: Force HTTP/3 protocol
+            stream: Whether to return a streaming response (default: False)
+        """
+
+    def stream(
+        self,
+        method: str,
+        url: str,
+        content: bytes | bytearray | list[int] | None = None,
+        data: dict[str, str] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+        force_http3: bool | None = None,
+    ) -> AbstractContextManager[Response]:
+        """Make a streaming request with the specified method.
+
+        This method returns a context manager that yields a streaming :class:`Response` object.
+
+        See the following example for usage:
+
+        .. code-block:: python
+
+            with Client() as client:
+                with client.stream("GET", "https://example.com/largefile") as response:
+                    for chunk in response.iter_bytes():
+                        process(chunk)  # Process each chunk as it is received
+
         Args:
             method: HTTP method (e.g., "get", "post")
             url: URL to request
@@ -250,7 +699,81 @@ class Client:
 
 
 class AsyncClient:
-    """Asynchronous HTTP client with browser impersonation capabilities."""
+    """Asynchronous HTTP client with browser impersonation capabilities.
+
+        .. note::
+            You can reuse the :class:`Client` instance to make multiple requests.
+
+            All requests made by the same client will share the same configuration, resources (e.g., cookie jar and connection pool), and other settings.
+
+        Args:
+            browser: Browser to impersonate (`"chrome"` or `"firefox"`).
+
+                If this is `None` (default), no impersonation is performed.
+            http3:
+
+                If set to `True`, Impit will try to connect to the target servers using HTTP/3 protocol (if supported by the server).
+
+                .. note::
+                    The HTTP/3 support is experimental and may not work with all servers. The impersonation capabilities are limited when using HTTP/3.
+
+            proxy:
+
+                The proxy URL to use for all the requests made by this client.
+
+                This can be an HTTP, HTTPS, or SOCKS proxy.
+            timeout:
+                Default request timeout in seconds.
+
+                This value can be overridden for individual requests.
+            verify:
+                If set to `False`, impit will not verify SSL certificates.
+
+                This can be used to ignore TLS errors (e.g., self-signed certificates).
+
+                True by default.
+            default_encoding:
+                Default encoding for response.text field (e.g., "utf-8", "cp1252").
+
+                Overrides `content-type` headers and bytestream prescan.
+            follow_redirects:
+
+                If set to `True` the client will automatically follow HTTP redirects (3xx responses).
+
+                `False` by default.
+            max_redirects:
+
+                Maximum number of redirects to follow if the `follow_redirects` option is enabled.
+
+                Default is 20.
+            cookie_jar:
+
+                Cookie jar to store cookies in.
+
+                This is a `http.cookiejar.CookieJar` instance.
+
+                By default, :class:`Client` doesn't store cookies between requests.
+            cookies: httpx-compatible cookies object.
+
+                These are the cookies to include in all requests (to the matching servers) made by this client.
+            headers: Default HTTP headers to include in requests.
+
+                These headers will be included in all requests made by this client.
+
+                Default is an empty dictionary.
+            local_address:
+
+                Local address to bind the client to.
+
+                Useful for testing purposes or when you want to bind the client to a specific network interface.
+                Can be an IP address in the format `xxx.xxx.xxx.xxx` (for IPv4) or `ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff` (for IPv6).
+        """
+
+    async def __aenter__(self) -> AsyncClient:
+        """Enter the runtime context related to this object."""
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: object | None) -> None:
+        """Exit the runtime context related to this object."""
 
     def __init__(
         self,
@@ -262,6 +785,10 @@ class AsyncClient:
         default_encoding: str | None = None,
         follow_redirects: bool | None = None,
         max_redirects: int | None = None,
+        cookie_jar: CookieJar | None = None,
+        cookies: Cookies | None = None,
+        headers: dict[str, str] | None = None,
+        local_address: str | None = None,
     ) -> None:
         """Initialize an asynchronous HTTP client.
 
@@ -275,6 +802,11 @@ class AsyncClient:
                 header and bytestream prescan.
             follow_redirects: Whether to follow redirects (default: False)
             max_redirects: Maximum number of redirects to follow (default: 20)
+            cookie_jar: Cookie jar to store cookies in.
+            cookies: httpx-compatible cookies object.
+            headers: Default HTTP headers to include in requests.
+            local_address: Local address to bind the client to. Useful for testing purposes or when you want to bind the client to a specific network interface.
+                Can be an IP address in the format "xxx.xxx.xxx.xxx" (for IPv4) or "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" (for IPv6).
         """
 
     async def get(
@@ -315,6 +847,7 @@ class AsyncClient:
             headers: HTTP headers
             timeout: Request timeout in seconds (overrides default timeout)
             force_http3: Force HTTP/3 protocol
+
         """
 
     async def put(
@@ -446,9 +979,44 @@ class AsyncClient:
         headers: dict[str, str] | None = None,
         timeout: float | None = None,
         force_http3: bool | None = None,
+        stream: bool = False,
     ) -> Response:
         """Make an asynchronous HTTP request with the specified method.
 
+        Args:
+            method: HTTP method (e.g., "get", "post")
+            url: URL to request
+            content: Raw content to send
+            data: Form data to send in request body
+            headers: HTTP headers
+            timeout: Request timeout in seconds (overrides default timeout)
+            force_http3: Force HTTP/3 protocol
+            stream: Whether to return a streaming response (default: False)
+        """
+
+    def stream(
+        self,
+        method: str,
+        url: str,
+        content: bytes | bytearray | list[int] | None = None,
+        data: dict[str, str] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+        force_http3: bool | None = None,
+    ) -> AbstractAsyncContextManager[Response]:
+        """Make an asynchronous streaming request with the specified method.
+
+        This method returns a AsyncContextManager that yields a streaming :class:`Response` object.
+
+        See the following example for usage:
+
+        .. code-block:: python
+
+            with Client() as client:
+                with client.stream("GET", "https://example.com/largefile") as response:
+                    for chunk in response.iter_bytes():
+                        process(chunk)  # Process each chunk as it is received
+
         Args:
             method: HTTP method (e.g., "get", "post")
             url: URL to request
@@ -460,6 +1028,40 @@ class AsyncClient:
         """
 
 
+def stream(
+    method: str,
+    url: str,
+    content: bytes | bytearray | list[int] | None = None,
+    data: dict[str, str] | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: float | None = None,
+    force_http3: bool | None = None,
+    follow_redirects: bool | None = None,
+    max_redirects: int | None = None,
+    cookie_jar: CookieJar | None = None,
+    cookies: Cookies | None = None,
+    proxy: str | None = None,
+) -> AbstractContextManager[Response]:
+    """Make a streaming request without creating a client instance.
+
+    Args:
+        method: HTTP method (e.g., "get", "post")
+        url: URL to request
+        content: Raw content to send
+        data: Form data to send in request body
+        headers: HTTP headers
+        timeout: Request timeout in seconds
+        force_http3: Force HTTP/3 protocol
+        follow_redirects: Whether to follow redirects (default: False)
+        max_redirects: Maximum number of redirects to follow (default: 20)
+        cookie_jar: Cookie jar to store cookies in.
+        cookies: httpx-compatible cookies object.
+        proxy: Proxy URL to use to make the request.
+
+    Returns:
+        Response object
+    """
+
 def get(
     url: str,
     content: bytes | bytearray | list[int] | None = None,
@@ -467,6 +1069,11 @@ def get(
     headers: dict[str, str] | None = None,
     timeout: float | None = None,
     force_http3: bool | None = None,
+    follow_redirects: bool | None = None,
+    max_redirects: int | None = None,
+    cookie_jar: CookieJar | None = None,
+    cookies: Cookies | None = None,
+    proxy: str | None = None,
 ) -> Response:
     """Make a GET request without creating a client instance.
 
@@ -477,6 +1084,11 @@ def get(
         headers: HTTP headers
         timeout: Request timeout in seconds
         force_http3: Force HTTP/3 protocol
+        follow_redirects: Whether to follow redirects (default: False)
+        max_redirects: Maximum number of redirects to follow (default: 20)
+        cookie_jar: Cookie jar to store cookies in.
+        cookies: httpx-compatible cookies object.
+        proxy: Proxy URL to use to make the request.
 
     Returns:
         Response object
@@ -490,6 +1102,11 @@ def post(
     headers: dict[str, str] | None = None,
     timeout: float | None = None,
     force_http3: bool | None = None,
+    follow_redirects: bool | None = None,
+    max_redirects: int | None = None,
+    cookie_jar: CookieJar | None = None,
+    cookies: Cookies | None = None,
+    proxy: str | None = None,
 ) -> Response:
     """Make a POST request without creating a client instance.
 
@@ -500,6 +1117,11 @@ def post(
         headers: HTTP headers
         timeout: Request timeout in seconds
         force_http3: Force HTTP/3 protocol
+        follow_redirects: Whether to follow redirects (default: False)
+        max_redirects: Maximum number of redirects to follow (default: 20)
+        cookie_jar: Cookie jar to store cookies in.
+        cookies: httpx-compatible cookies object.
+        proxy: Proxy URL to use to make the request.
 
     Returns:
         Response object
@@ -513,6 +1135,11 @@ def put(
     headers: dict[str, str] | None = None,
     timeout: float | None = None,
     force_http3: bool | None = None,
+    follow_redirects: bool | None = None,
+    max_redirects: int | None = None,
+    cookie_jar: CookieJar | None = None,
+    cookies: Cookies | None = None,
+    proxy: str | None = None,
 ) -> Response:
     """Make a PUT request without creating a client instance.
 
@@ -523,6 +1150,11 @@ def put(
         headers: HTTP headers
         timeout: Request timeout in seconds
         force_http3: Force HTTP/3 protocol
+        follow_redirects: Whether to follow redirects (default: False)
+        max_redirects: Maximum number of redirects to follow (default: 20)
+        cookie_jar: Cookie jar to store cookies in.
+        cookies: httpx-compatible cookies object.
+        proxy: Proxy URL to use to make the request.
 
     Returns:
         Response object
@@ -536,6 +1168,11 @@ def patch(
     headers: dict[str, str] | None = None,
     timeout: float | None = None,
     force_http3: bool | None = None,
+    follow_redirects: bool | None = None,
+    max_redirects: int | None = None,
+    cookie_jar: CookieJar | None = None,
+    cookies: Cookies | None = None,
+    proxy: str | None = None,
 ) -> Response:
     """Make a PATCH request without creating a client instance.
 
@@ -546,6 +1183,11 @@ def patch(
         headers: HTTP headers
         timeout: Request timeout in seconds
         force_http3: Force HTTP/3 protocol
+        follow_redirects: Whether to follow redirects (default: False)
+        max_redirects: Maximum number of redirects to follow (default: 20)
+        cookie_jar: Cookie jar to store cookies in.
+        cookies: httpx-compatible cookies object.
+        proxy: Proxy URL to use to make the request.
 
     Returns:
         Response object
@@ -559,6 +1201,11 @@ def delete(
     headers: dict[str, str] | None = None,
     timeout: float | None = None,
     force_http3: bool | None = None,
+    follow_redirects: bool | None = None,
+    max_redirects: int | None = None,
+    cookie_jar: CookieJar | None = None,
+    cookies: Cookies | None = None,
+    proxy: str | None = None,
 ) -> Response:
     """Make a DELETE request without creating a client instance.
 
@@ -569,6 +1216,11 @@ def delete(
         headers: HTTP headers
         timeout: Request timeout in seconds
         force_http3: Force HTTP/3 protocol
+        follow_redirects: Whether to follow redirects (default: False)
+        max_redirects: Maximum number of redirects to follow (default: 20)
+        cookie_jar: Cookie jar to store cookies in.
+        cookies: httpx-compatible cookies object.
+        proxy: Proxy URL to use to make the request.
 
     Returns:
         Response object
@@ -582,6 +1234,11 @@ def head(
     headers: dict[str, str] | None = None,
     timeout: float | None = None,
     force_http3: bool | None = None,
+    follow_redirects: bool | None = None,
+    max_redirects: int | None = None,
+    cookie_jar: CookieJar | None = None,
+    cookies: Cookies | None = None,
+    proxy: str | None = None,
 ) -> Response:
     """Make a HEAD request without creating a client instance.
 
@@ -592,6 +1249,11 @@ def head(
         headers: HTTP headers
         timeout: Request timeout in seconds
         force_http3: Force HTTP/3 protocol
+        follow_redirects: Whether to follow redirects (default: False)
+        max_redirects: Maximum number of redirects to follow (default: 20)
+        cookie_jar: Cookie jar to store cookies in.
+        cookies: httpx-compatible cookies object.
+        proxy: Proxy URL to use to make the request.
 
     Returns:
         Response object
@@ -605,6 +1267,11 @@ def options(
     headers: dict[str, str] | None = None,
     timeout: float | None = None,
     force_http3: bool | None = None,
+    follow_redirects: bool | None = None,
+    max_redirects: int | None = None,
+    cookie_jar: CookieJar | None = None,
+    cookies: Cookies | None = None,
+    proxy: str | None = None,
 ) -> Response:
     """Make an OPTIONS request without creating a client instance.
 
@@ -615,6 +1282,11 @@ def options(
         headers: HTTP headers
         timeout: Request timeout in seconds (overrides default timeout)
         force_http3: Force HTTP/3 protocol
+        follow_redirects: Whether to follow redirects (default: False)
+        max_redirects: Maximum number of redirects to follow (default: 20)
+        cookie_jar: Cookie jar to store cookies in.
+        cookies: httpx-compatible cookies object.
+        proxy: Proxy URL to use to make the request.
     """
 
 
@@ -625,6 +1297,11 @@ def trace(
     headers: dict[str, str] | None = None,
     timeout: float | None = None,
     force_http3: bool | None = None,
+    follow_redirects: bool | None = None,
+    max_redirects: int | None = None,
+    cookie_jar: CookieJar | None = None,
+    cookies: Cookies | None = None,
+    proxy: str | None = None,
 ) -> Response:
     """Make a TRACE request without creating a client instance.
 
@@ -635,4 +1312,9 @@ def trace(
         headers: HTTP headers
         timeout: Request timeout in seconds (overrides default timeout)
         force_http3: Force HTTP/3 protocol
+        follow_redirects: Whether to follow redirects (default: False)
+        max_redirects: Maximum number of redirects to follow (default: 20)
+        cookie_jar: Cookie jar to store cookies in.
+        cookies: httpx-compatible cookies object.
+        proxy: Proxy URL to use to make the request.
     """

{impit-0.2.1.dist-info → impit-0.9.0.dist-info}/METADATA

@@ -1,30 +1,35 @@
 Metadata-Version: 2.4
 Name: impit
-Version: 0.2.1
+Version: 0.9.0
 Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Summary: A library for making HTTP requests through browser impersonation
 Keywords: apify,http,requests,browser,impersonation
 Author: Jindřich Bär
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-Project-URL: Homepage, https://apify.github.io/impit/
+Project-URL: Homepage, https://apify.github.io/impit/python
 Project-URL: Apify homepage, https://apify.com
-Project-URL: Changelog, https://github.com/apify/impit/blob/master/CHANGELOG.md
-Project-URL: Documentation, https://apify.github.io/impit/
+Project-URL: Changelog, https://github.com/apify/impit/blob/master/impit-python/CHANGELOG.md
+Project-URL: Documentation, https://apify.github.io/impit/python
 Project-URL: Issue tracker, https://github.com/apify/impit/issues
 Project-URL: Repository, https://github.com/apify/impit
 
 # `impit` for Python
 
+> This documents the `impit` Python package, which provides bindings for the `impit` library.
+>
+> See documentation for the JavaScript/TypeScript version of `impit` [here](https://apify.github.io/impit/js/).
+
 `impit` is a Python package that provides bindings for the [`impit`](https://github.com/apify/impit) library.
 
 It allows you to switch the TLS fingerprints and the HTTP headers of your requests, while still using the same API as `httpx` or `requests`.

impit-0.9.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+impit-0.9.0.dist-info/METADATA,sha256=rUem-pBLg6yAp-5ARgqksLUOut5yrVmou21VKAv3Qy0,2833
+impit-0.9.0.dist-info/WHEEL,sha256=k_XiDtlLA7dbYGdvJSsIA4CTI9KZm58eaZX7iYUYBGQ,108
+impit.libs/libgcc_s-98a1ef30.so.1,sha256=XOVRhHznCIpbSdhFoozhla-OfRqBtXftKPQ4cSMKjrs,433441
+impit/__init__.py,sha256=uZsD0XMFOt7QwVUgNcnVQkDF85y9n5slxoxR0wim7ug,1664
+impit/cookies.py,sha256=bfNPkMk2Y0bG-RqqMMJxIfvCMZp_fDclYAnSlsCwkIg,7009
+impit/impit.cpython-313-x86_64-linux-musl.so,sha256=UlbcfPotbcezKVMCglRUniWlPDVXd8go_hfY75MGhBU,14832353
+impit/impit.pyi,sha256=IxLCuSkx3mHQcwcSS65lveoM5QYvMeJcU-Mhhdelyng,45730
+impit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+impit-0.9.0.dist-info/RECORD,,

{impit-0.2.1.dist-info → impit-0.9.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.8.3)
+Generator: maturin (1.10.0)
 Root-Is-Purelib: false
 Tag: cp313-cp313-musllinux_1_2_x86_64

impit-0.2.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-impit-0.2.1.dist-info/METADATA,sha256=FhD2ueaHS0b6c14Vi2Z_IGwTpgKz7aJrggdmg98VBoQ,2562
-impit-0.2.1.dist-info/WHEEL,sha256=FhhfBGxpw7lUS1vCU0xMKSc8xZ-17phLfvnaRtwemzY,107
-impit.libs/libgcc_s-1e52349c.so.1,sha256=Ani0u_W_tB8ESsFePO4D2mn2lrgWLhyFdw6RETxBTYM,437537
-impit/__init__.py,sha256=112MOaJD7xu13dnU1b1GHQO41EI61pQE6LdTeojqWqg,400
-impit/impit.pyi,sha256=wPx29TNIyK9xTazeb-KPnXeYrNc0wMZnqSXzYCPPfRc,19775
-impit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-impit/impit.cpython-313-x86_64-linux-musl.so,sha256=NpYA1D-bxIVeNNZ5ruehi1S9Fb_mrUckvjxXMkrYnH0,14520689
-impit-0.2.1.dist-info/RECORD,,