cancellable-http-client 1.0__py3-none-any.whl

cancellable_http_client-1.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: cancellable-http-client
+Version: 1.0
+Summary: A tiny, dependency-free HTTP client for Python with cancellable in-flight requests and hard wall-clock timeout.
+Author: Sakilabo Corporation Ltd.
+License-Expression: UPL-1.0
+Project-URL: Homepage, https://github.com/sakilabo/cancellable-http-client
+Project-URL: Issues, https://github.com/sakilabo/cancellable-http-client/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+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 :: Internet :: WWW/HTTP
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cancellable_http_client
+
+A tiny, dependency-free HTTP client for Python with **cancellable in-flight requests** and **hard wall-clock timeout**.
+
+- Standard library only — no `requests`, no `httpx`, no `urllib3`.
+- Single file, ~300 lines.
+- Synchronous API that plays well with `threading`-based workers.
+- Safe `close()` from any thread, at any time, including mid-transfer.
+- Hard wall-clock `timeout` that bounds the entire request.
+
+## Why it exists
+
+Python has no clean way to interrupt a thread that is blocked on a socket read. `concurrent.futures.Future.cancel()` does nothing once the task has started, and `requests` / `urllib.urlopen()` give you no handle to abort an in-flight request.
+
+The one primitive that *does* work is closing the underlying socket: any pending `recv()` immediately unblocks with an error. This module wraps that trick behind a tiny, boring API so you don't have to reinvent it — or worry about the lifecycle edge cases — every time you need it.
+
+If your codebase is built around `asyncio`, you don't need this; use `httpx` and `task.cancel()` instead. This module targets the very real case where you have existing threaded code and you want one HTTP call in the middle of it to be cancellable, without rewriting everything to be async.
+
+## Usage
+
+```python
+import time
+import cancellable_http_client as client
+
+req = client.Request("https://example.com/")
+req.start()           # the actual TCP connection happens here
+start = time.monotonic()
+while not req.done:
+    if time.monotonic() - start > 5:
+        print("taking too long, aborting...")
+        req.close()   # interrupts the request if it's still in-flight
+    req.wait(0.1)     # wait a bit before checking again
+if req.error:
+    print(f"failed: {req.error}")
+elif req.response and req.response.status == 200:
+    print(req.response.body)
+req.close()           # safe to call any time, even mid-flight
+```
+
+You can also use it as a context manager:
+
+```python
+with client.Request("https://example.com/") as req:
+    req.start()
+    req.wait(timeout=5)
+    ...
+# close() is called automatically on exit
+```
+
+### Sharing a thread pool
+
+By default each `Request` spawns its own daemon thread. To reuse a pool instead, assign an `Executor` to the module-level attribute:
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+client.executor = ThreadPoolExecutor(max_workers=8)
+```
+
+## API
+
+### `Request(url, method="GET", headers=None, body=b"", socket_timeout=30, timeout=None)`
+
+Construct a request. No network I/O happens here — connection failures are reported via `error` after `start()`.
+
+- **`socket_timeout`** — per-socket-operation timeout in seconds, passed to `http.client.HTTPConnection`.
+- **`timeout`** — wall-clock limit in seconds for the entire request. Triggers `close()` automatically if the request is not done in time. `None` disables.
+- **`start()`** — kick off the request. Non-blocking.
+- **`wait(timeout=None) -> bool`** — block until the request finishes. Returns `True` on completion, `False` on timeout.
+- **`close()`** — abort the request and release resources. Safe to call any time, from any thread, any number of times.
+- **`done`** *(property)* — `True` once the request has finished (success, failure, or close).
+- **`response`** — a `Response` object on success, otherwise `None`.
+- **`error`** — the exception raised during the request, or `None`.
+
+### `Response`
+
+A read-only, socket-free container exposing the same attributes as `http.client.HTTPResponse`:
+
+- `status`, `reason`, `version`
+- `headers` (an `http.client.HTTPMessage`)
+- `body` (`bytes`, eagerly read)
+- `getheader(name, default=None)`, `getheaders()`
+
+## Robust timeout
+
+Most Python HTTP clients set a *per-socket-operation* timeout (`socket.settimeout`). This leaves several gaps:
+
+- **Slow drip** — a server that sends one byte every 29 seconds never triggers a 30-second socket timeout, yet the total transfer can take arbitrarily long.
+- **DNS resolution** — `socket.getaddrinfo()` is a blocking C library call with no timeout parameter. Python cannot interrupt it.
+- **Total elapsed time** — there is no built-in way to cap the wall-clock time of an entire request across connection, TLS handshake, sending, and receiving.
+
+`cancellable_http_client` addresses this with two separate knobs:
+
+| Parameter | Scope | Default |
+|---|---|---|
+| `socket_timeout` | Per socket operation (connect, send, recv) | 30 s |
+| `timeout` | Wall-clock limit on the entire request | None (no limit) |
+
+When `timeout` fires it calls `close()`, which immediately unblocks any pending socket operation by closing the underlying connection. This gives you a hard upper bound on how long `wait()` will block — something that `socket_timeout` alone cannot guarantee.
+
+## Comparison with existing libraries
+
+| | cancellable_http_client | httpx | requests |
+|---|---|---|---|
+| Cancel an in-flight request from another thread | ✅ | ⚠️ async, [unreliable](https://github.com/encode/httpx/issues/1461) | ⚠️ hacky |
+| Hard wall-clock timeout on entire request | ✅ | ⚠️ per-operation | ⚠️ per-operation |
+| Synchronous API | ✅ | ✅ (also async) | ✅ |
+| No third-party dependencies | ✅ | ❌ | ❌ |
+| Line count | ~300 | thousands | thousands |
+| Fits a threading-based worker | ✅ | ❌ | ⚠️ |
+| Redirects, cookies, User-Agent | ⚠️ manual | ✅ | ✅ |
+
+`httpx` is a good choice if you are already in an `asyncio` world, though `task.cancel()` on in-flight requests [can leave the connection pool in a broken state](https://github.com/encode/httpx/issues/1461). `requests` does not offer a reliable way to interrupt an in-flight call; `Session.close()` does not forcibly close active sockets ([psf/requests#5633](https://github.com/psf/requests/issues/5633)).
+
+## Limitations
+
+This library is a thin wrapper around `http.client` and does not provide the high-level conveniences found in `requests` or `httpx`:
+
+- No automatic redirect following
+- No cookie management
+- No default User-Agent header
+- No HTTP/2 support
+
+These are all `http.client` limitations, not restrictions added by this library. You can still handle them manually via the `headers` parameter.
+
+## Tests
+
+```
+python -m unittest discover -s tests -v
+```
+
+No third-party test dependencies. Tests use local throwaway servers (normal, slow, blackhole, mid-body disconnect) to exercise cancellation, timeout, and error paths without touching the network.
+
+## License
+
+Copyright 2026 Sakilabo Corporation Ltd.
+Licensed under the Universal Permissive License v 1.0
+([UPL-1.0](https://oss.oracle.com/licenses/upl/)).
+
+---
+
+## References (for the eventual public release)
+
+Background reading and related work collected during the design of this module. Useful as citations in the README or a launch blog post.
+
+### Prior art / closest existing work
+
+- **["TIL: Stopping Requests Mid Flight" — haykot.dev](https://haykot.dev/blog/til-stopping-requests-mid-flight/)**
+  A blog post describing the "close the socket from another thread" trick as a personal discovery. The same underlying idea as this module, but kept as a snippet rather than packaged as a library.
+  
+- **[httpcore on PyPI](https://pypi.org/project/httpcore/)**
+  the low-level HTTP engine behind `httpx`. Supports cancellation via async task cancellation; relies on `asyncio` or `trio`.
+  
+- **[HTTPX](https://www.python-httpx.org/)**
+  modern high-level HTTP client; cancellation is done via `task.cancel()` in an async context.
+  
+- **[asyncio-cancel-token](https://asyncio-cancel-token.readthedocs.io/en/latest/cancel_token.html)**
+  a cancellation-token utility for `asyncio`-based code.
+
+### The underlying Python pain points
+
+- **[Graceful exit from ThreadPoolExecutor when blocked on IO — discuss.python.org](https://discuss.python.org/t/graceful-exit-from-threadpoolexecutor-when-blocked-on-io-problem-and-possible-enhancement/80380)**
+  Ongoing discussion acknowledging that Python has no clean way to cancel a worker that is blocked on I/O. This module is effectively a targeted workaround for the HTTP-specific case.
+  
+- **[`threading` — Python docs](https://docs.python.org/3/library/threading.html)**
+  `Thread` has no `cancel()` / `interrupt()`; cooperation via `Event` is the only sanctioned approach.
+  
+- **[`Session.close()` does not close underlying sockets — psf/requests#5633](https://github.com/psf/requests/issues/5633)**
+  Illustrates why "just use `requests` and close the session" is not a reliable answer.
+  
+- **[Unclosed socket in urllib when ftp request times out after connect — cpython#140691](https://github.com/python/cpython/issues/140691)**
+  A related stdlib lifecycle bug — background for why we deliberately take full control of the connection object.
+
+### Related stdlib primitives this module builds on
+
+- **[`http.client` — Python docs](https://docs.python.org/3/library/http.client.html)**
+  the low-level HTTP protocol implementation we wrap.
+- **[`threading.Event` — Python docs](https://docs.python.org/3/library/threading.html#event-objects)**
+  used internally to signal completion.

cancellable_http_client-1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+cancellable_http_client.py,sha256=WD9k57UPewmxcff-N1EsfttOdXZbr2kbsvKxKsK9Gt0,10100
+cancellable_http_client-1.0.dist-info/licenses/LICENSE,sha256=x5gxhbq1vPgZSPLb-MfxI0hriq_JXCGEaXFkQSVNLaA,1831
+cancellable_http_client-1.0.dist-info/METADATA,sha256=Yzikypm9eCewb2OhOoGvBS5vzivwRYszpUXbGIHB1-I,10283
+cancellable_http_client-1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cancellable_http_client-1.0.dist-info/top_level.txt,sha256=i2x1SMr759WwB4gwhwLXWqnjgjpgOCh4yWWvU8mHypc,24
+cancellable_http_client-1.0.dist-info/RECORD,,

cancellable_http_client-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cancellable_http_client-1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+Copyright 2026 Sakilabo Corporation Ltd.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any person obtaining a copy of this software, associated documentation and/or data (collectively the "Software"), free of charge and under any and all copyright rights in the Software, and any and all patent rights owned or freely licensable by each licensor hereunder covering either (i) the unmodified Software as contributed to or provided by such licensor, or (ii) the Larger Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if one is included with the Software (each a "Larger Work" to which the Software is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create derivative works of, display, perform, and distribute the Software and make, use, sell, offer for sale, import, export, have made, and have sold the Software and the Larger Work(s), and to sublicense the foregoing rights on either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at a minimum a reference to the UPL must be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

cancellable_http_client-1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cancellable_http_client

cancellable_http_client.py

@@ -0,0 +1,289 @@
+# Copyright 2026 Sakilabo Corporation Ltd.
+# SPDX-License-Identifier: UPL-1.0
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# https://oss.oracle.com/licenses/upl/
+
+"""Cancellable HTTP client.
+
+A tiny standard-library-only HTTP client whose in-flight request can be
+aborted at any time by closing the underlying socket.
+
+Usage
+-----
+    import time
+    import cancellable_http_client as client
+
+    req = client.Request("https://example.com/")
+    req.start()           # the actual TCP connection happens here
+    start = time.monotonic()
+    while not req.done:
+        if time.monotonic() - start > 5:
+            print("taking too long, aborting...")
+            req.close()   # this will interrupt the request if it's still in-flight
+        req.wait(0.1)     # wait a bit before checking again (when done, wait() returns immediately)
+    if req.error:
+        print(f"failed: {req.error}")
+    elif req.response and req.response.status == 200:
+        print(req.response.body)
+    req.close()           # safe to call any time, even mid-flight
+
+The ``timeout`` parameter triggers ``close()`` automatically after the
+given number of seconds, providing a hard wall-clock limit on the entire
+request — unlike ``socket_timeout``, which only limits individual socket
+operations and cannot bound the total elapsed time.
+
+By default each Request spawns its own daemon thread. To share a pool,
+assign a concurrent.futures.Executor to ``cancellable_http_client.executor``.
+"""
+
+from __future__ import annotations
+
+import http.client
+import logging
+import threading
+import urllib.parse
+
+from concurrent.futures import Executor
+from typing import Callable
+
+_logger = logging.getLogger(__name__)
+
+
+# If the user assigns an Executor here, requests are dispatched to it
+# instead of spawning a fresh daemon thread per call.
+executor: Executor | None = None
+
+
+class Response:
+    """A read-only HTTPResponse-compatible object.
+
+    Exposes the same attributes as ``http.client.HTTPResponse``
+    (``status``, ``reason``, ``version``, ``headers``, ``body``) but holds
+    its body in memory, so it can be inspected freely after the underlying
+    socket has been closed.
+    """
+
+    def __init__(self, resp: http.client.HTTPResponse) -> None:
+        self.status: int = resp.status
+        self.reason: str = resp.reason
+        self.version: int = resp.version
+        self.headers: http.client.HTTPMessage = resp.msg
+        self.body: bytes = resp.read()
+
+    def getheader(self, name: str, default: str | None = None) -> str | None:
+        return self.headers.get(name, default)
+
+    def getheaders(self) -> list[tuple[str, str]]:
+        return list(self.headers.items())
+
+    def __repr__(self) -> str:
+        return f"<Response status={self.status} reason={self.reason!r}>"
+
+
+class Request:
+    """A single cancellable HTTP request.
+
+    Parameters
+    ----------
+    url     : Target URL (scheme://host[:port]/path?query).
+    method  : HTTP method.
+    headers : Request headers.
+    body    : Request body bytes.
+    socket_timeout : Socket timeout in seconds (per socket operation).
+    timeout : Total request timeout in seconds. If the request does not
+        complete within this time after ``start()``, it is automatically
+        closed. ``None`` means no limit.
+
+    Attributes
+    ----------
+    done     : True once the request has finished (success, failure, or close).
+    response : Response object on success, otherwise None.
+    error    : Exception raised during the request, or None on success.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        body: bytes = b"",
+        socket_timeout: float = 30,
+        timeout: float | None = None,
+    ) -> None:
+        self.response: Response | None = None
+        self.error: Exception | None = None
+
+        self._event = threading.Event()
+        self._lock = threading.Lock()
+        self._closed: bool = False
+        self._started: bool = False
+        self._conn: http.client.HTTPConnection | None = None
+        self._callbacks: list[Callable[["Request"], None]] = []
+        self._timeout: float | None = timeout
+        self._timer: threading.Timer | None = None
+
+        self._url: str = url
+        parsed = urllib.parse.urlparse(url)
+        self._method: str = method
+        self._headers: dict[str, str] = headers or {}
+        self._req_body: bytes = body
+        self._path: str = parsed.path or "/"
+        if parsed.query:
+            self._path = f"{self._path}?{parsed.query}"
+
+        try:
+            if parsed.scheme == "https":
+                self._conn = http.client.HTTPSConnection(
+                    parsed.hostname or "", parsed.port, timeout=socket_timeout
+                )
+            else:
+                self._conn = http.client.HTTPConnection(
+                    parsed.hostname or "", parsed.port, timeout=socket_timeout
+                )
+        except Exception as e:
+            self.error = e
+            self._event.set()
+
+    def __enter__(self) -> "Request":
+        return self
+
+    def __exit__(self, *_exc) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        if self.response is not None:
+            state = f"status={self.response.status}"
+        elif self.error is not None:
+            state = f"error={self.error!r}"
+        elif self._closed:
+            state = "closed"
+        elif self._started:
+            state = "running"
+        else:
+            state = "pending"
+        return f"<Request {self._method} {self._url} {state}>"
+
+    @property
+    def done(self) -> bool:
+        """True once the request has finished (success, failure, or close).
+
+        When ``done`` is True, all finalize callbacks have already run.
+        """
+        return self._event.is_set()
+
+    def start(self) -> None:
+        """Start the request.
+
+        Calling start() more than once, or after close(), is a no-op.
+        If scheduling the worker fails, ``error`` is set and the request
+        finishes immediately.
+        """
+        with self._lock:
+            if self._started or self._closed:
+                return
+            self._started = True
+
+        if self._timeout is not None:
+            self._timer = threading.Timer(self._timeout, self.close)
+            self._timer.daemon = True
+            self._timer.start()
+
+        try:
+            if executor is not None:
+                executor.submit(self._run)
+            else:
+                threading.Thread(
+                    target=self._run, daemon=True, name="cancellable_http_client"
+                ).start()
+        except Exception as e:
+            self.error = e
+            with self._lock:
+                conn, self._conn = self._conn, None
+            self._finalize(conn)
+
+    def add_finalize_callback(self, fn: Callable[["Request"], None]) -> None:
+        """Register ``fn`` to be invoked just before the request finishes.
+
+        Unlike ``concurrent.futures.Future.add_done_callback``, the callback
+        runs *before* ``done`` becomes True and before ``wait()`` returns.
+        This means an observer that sees ``done == True`` is guaranteed
+        that every registered callback has already completed — useful for
+        callbacks that populate fields the observer wants to read.
+
+        The callback receives this Request as its only argument and runs
+        on the worker thread that completes the request. Registering a
+        callback on a Request that has already finished is a no-op.
+
+        Exceptions raised by the callback are logged and swallowed.
+        """
+        with self._lock:
+            self._callbacks.append(fn)
+
+    def wait(self, timeout: float | None = None) -> bool:
+        """Block until done. Returns True if completed, False on timeout.
+
+        Raises RuntimeError if called before ``start()`` on a request that
+        has not already finished (e.g. due to an initialisation failure).
+        """
+        if not self._started and not self.done:
+            raise RuntimeError("Request has not been started")
+        return self._event.wait(timeout)
+
+    def close(self) -> None:
+        """Discard everything and finish.
+
+        Safe to call at any time, including from another thread while the
+        request is in flight. After close(), ``done`` is True and any
+        ``wait()`` call returns immediately.
+        """
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            conn, self._conn = self._conn, None
+        self._finalize(conn)
+
+    def _run(self) -> None:
+        try:
+            conn = self._conn
+            if conn is None:
+                raise RuntimeError("connection is not available")
+            conn.request(
+                self._method, self._path, body=self._req_body, headers=self._headers
+            )
+            # If close() was called while conn.request() was in progress,
+            # the socket may not have been cleaned up — bail out here.
+            with self._lock:
+                closed = self._closed
+            if closed:
+                conn.close()
+                return
+            resp = Response(conn.getresponse())
+            with self._lock:
+                if not self._closed:
+                    self.response = resp
+        except Exception as e:
+            # interruption by close() also lands here
+            with self._lock:
+                closed = self._closed
+            if not closed:
+                self.error = e
+        finally:
+            self._conn = None
+            self._finalize(conn)
+
+    def _finalize(self, conn: http.client.HTTPConnection | None) -> None:
+        if conn is not None:
+            try:
+                conn.close()
+            except Exception:
+                pass
+        with self._lock:
+            callbacks, self._callbacks = self._callbacks, []
+        for fn in callbacks:
+            try:
+                fn(self)
+            except Exception:
+                _logger.exception("finalize callback raised")
+        self._event.set()