uhttp-client 2.2.1__tar.gz → 2.3.1__tar.gz

uhttp_client-2.3.1/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Install package
+        run: pip install .
+
+      - name: Install test dependencies
+        run: pip install uhttp-server
+
+      - name: Run unit tests
+        run: python -m unittest discover -v tests/
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

uhttp_client-2.3.1/.github/workflows/tests.yml

@@ -0,0 +1,87 @@
+name: Tests
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main, v2]
+  pull_request:
+    branches: [main, v2]
+
+jobs:
+  test-ubuntu:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 1
+      matrix:
+        python-version: ["3.10", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: pip install .
+
+      - name: Install test dependencies
+        run: pip install uhttp-server
+
+      - name: Run unit tests
+        run: python -m unittest discover -v tests/
+
+  test-windows:
+    runs-on: windows-latest
+    strategy:
+      max-parallel: 1
+      matrix:
+        python-version: ["3.10", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: pip install .
+
+      - name: Install test dependencies
+        run: pip install uhttp-server
+
+      - name: Run unit tests
+        run: python -m unittest discover -v tests/
+
+  micropython:
+    if: github.event_name == 'push'
+    needs: [test-ubuntu, test-windows]
+    runs-on: [self-hosted, Linux]
+    # One device, two maintained branches - queue instead of colliding, and
+    # never cancel: interrupting mpytool mid-operation wedges the REPL.
+    concurrency:
+      group: micropython-${{ matrix.device }}
+      cancel-in-progress: false
+    strategy:
+      fail-fast: false
+      matrix:
+        device: [ESP32]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install packages
+        run: |
+          $HOME/actions-runner/.venv/bin/pip install -e .
+          $HOME/actions-runner/.venv/bin/pip install 'mpytool>=2.4.0'
+
+      - name: MicroPython tests (${{ matrix.device }})
+        run: |
+          export PATH="$HOME/actions-runner/.venv/bin:$PATH"
+          export MPY_TEST_PORT="$(cat $HOME/actions-runner/.config/mpytool/${{ matrix.device }})"
+          export MPY_WIFI_SSID="$(jq -r .ssid $HOME/actions-runner/.config/uhttp/wifi.json)"
+          export MPY_WIFI_PASSWORD="$(jq -r .password $HOME/actions-runner/.config/uhttp/wifi.json)"
+          python -m unittest tests.test_mpy_integration -v

uhttp_client-2.3.1/.gitignore

@@ -0,0 +1,10 @@
+*.egg-info
+__pycache__
+*.pyc
+.*
+!.gitignore
+!.github
+!.mpyproject
+*.pem
+*.md
+!README*.md

{uhttp_client-2.2.1/uhttp_client.egg-info → uhttp_client-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uhttp-client
-Version: 2.2.1
+Version: 2.3.1
 Summary: Micro HTTP client for Python and MicroPython
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License: MIT
@@ -21,13 +21,17 @@ Dynamic: license-file
 ## Features
 
 - MicroPython and CPython compatible
-- Select-based async (no async/await, no threading)
+- Fully non-blocking: TCP connect, SSL handshake, and HTTP I/O via select
 - Keep-alive connections with automatic reuse
 - Fluent API: `response = client.get('/path').wait()`
 - URL parsing with automatic SSL detection
 - Base path support for API versioning
 - JSON support (auto-encode request, lazy decode response)
 - Binary data support
+- Chunked transfer encoding (and `Content-Length`) response decoding
+- Streaming event mode (`event_mode=True`) mirroring uhttp-server: `EVENT_*` +
+  `accept_body*()` — stream to memory, file, or NDJSON records
+- Read-until-close responses (`stream=True`) for MJPEG / SSE
 - Cookies persistence
 - HTTP Basic and Digest authentication
 - SSL/TLS support for HTTPS
@@ -160,7 +164,7 @@ client.close()
 
 ## Async (non-blocking) mode
 
-Default mode is async. Use with external select loop:
+Everything is non-blocking by default — TCP connect, SSL handshake, and HTTP I/O all happen through `select()`. This is critical for embedded devices on slow networks (4G modems, ESP32 PPP) where each phase can take seconds.
 
 ```python
 import select
@@ -168,10 +172,10 @@ import uhttp.client
 
 client = uhttp.client.HttpClient('http://httpbin.org')
 
-# Start request (non-blocking)
+# Start request (non-blocking, including connect)
 client.get('/delay/2')
 
-# Manual select loop
+# Manual select loop - handles connect, send, and receive
 while True:
     r, w, _ = select.select(
         client.read_sockets,
@@ -187,8 +191,25 @@ while True:
 client.close()
 ```
 
+### State machine
+
+After `client.get('/path')`, the client progresses through states automatically via `process_events()`:
+
+| State | Description | select watches |
+|---|---|---|
+| `STATE_CONNECTING` | TCP connect in progress | write |
+| `STATE_SSL_HANDSHAKE` | SSL handshake in progress | read or write |
+| `STATE_SENDING` | Sending request data | write |
+| `STATE_RECEIVING_HEADERS` | Waiting for response headers | read |
+| `STATE_RECEIVING_BODY` | Receiving response body | read |
+| `STATE_COMPLETE` | Response ready | — |
+
+The `state` property exposes the current state. The `is_connected` property returns `True` only after connect and handshake are complete.
+
 ### Parallel requests
 
+All clients share one select loop. Connect, handshake, and data transfer happen concurrently:
+
 ```python
 import select
 import uhttp.client
@@ -199,11 +220,11 @@ clients = [
     uhttp.client.HttpClient('http://httpbin.org'),
 ]
 
-# Start all requests
+# Start all requests (non-blocking connects begin immediately)
 for i, client in enumerate(clients):
     client.get('/delay/1', query={'n': i})
 
-# Wait for all
+# Single select loop handles all clients
 results = {}
 while len(results) < len(clients):
     read_socks = []
@@ -226,6 +247,8 @@ for client in clients:
 
 ### Combined with HttpServer
 
+Server and client in the same select loop — true single-threaded concurrency:
+
 ```python
 import select
 import uhttp.server
@@ -252,6 +275,178 @@ while True:
         incoming.respond(data=response.data)
 ```
 
+### HTTPS with non-blocking handshake
+
+SSL handshake is also non-blocking. The client tracks whether `do_handshake()` needs to read or write, and exposes the socket only in the correct direction to prevent `select()` from spinning:
+
+```python
+import select
+import ssl
+import uhttp.client
+
+ctx = ssl.create_default_context()
+client = uhttp.client.HttpClient(
+    'api.example.com', port=443, ssl_context=ctx)
+
+# Connect + SSL handshake + request all happen via select
+client.get('/data')
+
+while True:
+    r, w, _ = select.select(
+        client.read_sockets,
+        client.write_sockets,
+        [], 10.0
+    )
+    response = client.process_events(r, w)
+    if response:
+        print(response.json())
+        break
+
+client.close()
+```
+
+### Multiple HTTPS clients in parallel
+
+```python
+import select
+import uhttp.client
+
+urls = [
+    'https://api1.example.com/data',
+    'https://api2.example.com/data',
+    'https://api3.example.com/data',
+]
+
+clients = [uhttp.client.HttpClient(url) for url in urls]
+for c in clients:
+    c.get('/')  # All start non-blocking connects + SSL handshakes
+
+responses = [None] * len(clients)
+while not all(responses):
+    read_socks = []
+    write_socks = []
+    for c in clients:
+        read_socks.extend(c.read_sockets)
+        write_socks.extend(c.write_sockets)
+
+    r, w, _ = select.select(read_socks, write_socks, [], 10.0)
+
+    for i, c in enumerate(clients):
+        if responses[i] is None:
+            resp = c.process_events(r, w)
+            if resp:
+                responses[i] = resp
+
+for c in clients:
+    c.close()
+```
+
+
+## Streaming & Event Mode
+
+For large or open-ended responses (downloads, NDJSON, MJPEG, SSE) the client
+offers an **event mode** that mirrors uhttp-server's `HttpConnection` API.
+With `event_mode=True`, `wait()` / `process_events()` return `EVENT_*`
+constants instead of an `HttpResponse`, and you choose how the body is
+delivered after the headers arrive.
+
+### Events
+
+| Event | Meaning |
+|---|---|
+| `EVENT_RESPONSE` | Complete response (headers + body) in one step — small/buffered |
+| `EVENT_HEADERS` | Headers ready → call an `accept_body*()` variant |
+| `EVENT_DATA` | One decoded chunk/record ready → `read_buffer()` / `read_record()` |
+| `EVENT_COMPLETE` | Body fully received |
+| `EVENT_ERROR` | Connection or decode error → message in `client.error` (no exception) |
+
+Names and numeric values match uhttp-server, so the same select loop can drive
+both a server and a client.
+
+### Body delivery (choose after `EVENT_HEADERS`)
+
+- `accept_body()` — buffer the whole body → `EVENT_COMPLETE`; read it as a full
+  `HttpResponse` via `client.response` (so `.json()` / `.data` are reused)
+- `accept_body_streaming()` — `EVENT_DATA` per chunk; `read_buffer()` → bytes
+- `accept_body_to_file(path)` — stream the body to disk (low RAM, no `EVENT_DATA`)
+- `accept_ndjson()` — `EVENT_DATA` per record; `read_record()` → decoded object
+
+The *event* tells you the phase; the *decoder* (which `accept_*()` you call)
+tells you the shape of what you read — so new formats add an `accept_*()`, not a
+new event type.
+
+### NDJSON streaming
+
+```python
+import select
+from uhttp.client import (
+    HttpClient, EVENT_HEADERS, EVENT_DATA, EVENT_COMPLETE, EVENT_ERROR)
+
+client = HttpClient('http://api.example.com', event_mode=True)
+client.get('/events.ndjson', stream=True)   # stream until close if unframed
+
+while True:
+    r, w, _ = select.select(client.read_sockets, client.write_sockets, [], 30)
+    event = client.process_events(r, w)
+
+    if event == EVENT_HEADERS:
+        client.accept_ndjson()
+    elif event == EVENT_DATA:
+        record = client.read_record()        # already a decoded object
+        handle(record)
+    elif event == EVENT_COMPLETE:
+        break
+    elif event == EVENT_ERROR:
+        print(client.error)
+        break
+
+client.close()
+```
+
+A line that fails to JSON-decode is reported as `EVENT_ERROR` (with the message
+in `client.error`) only **after** the good records before it have been
+delivered. The client never closes the connection on its own — you decide.
+
+### Download to file (low RAM)
+
+```python
+client = HttpClient('http://example.com', event_mode=True)
+client.get('/firmware.bin')
+
+while True:
+    r, w, _ = select.select(client.read_sockets, client.write_sockets, [], 10)
+    event = client.process_events(r, w)
+    if event == EVENT_HEADERS:
+        client.accept_body_to_file('/sd/firmware.bin')
+    elif event == EVENT_COMPLETE:
+        print('written', client.bytes_received, 'bytes')
+        break
+    elif event == EVENT_ERROR:
+        print(client.error)
+        break
+
+client.close()
+```
+
+### Read until close (MJPEG / SSE)
+
+`stream=True` selects a close-delimited body reader when the response has
+neither `Content-Length` nor chunked encoding — the body is read until the
+server closes the connection. (Such a connection cannot be kept alive.)
+
+```python
+client = HttpClient('http://cam.local', event_mode=True)
+client.get('/stream.mjpeg', stream=True)
+# ... EVENT_HEADERS → accept_body_streaming() → EVENT_DATA loop ...
+```
+
+### Blocking mode still works
+
+Small responses don't need any of this — in event mode they arrive as a single
+`EVENT_RESPONSE` with the full body in `client.response`. And with the default
+`event_mode=False`, `wait()` returns an `HttpResponse` exactly as before;
+chunked decoding works transparently there too.
+
 
 ## API
 
@@ -280,7 +475,7 @@ uhttp.client.parse_url('example.com')
 
 ### Class `HttpClient`
 
-**`uhttp.client.HttpClient(url_or_host, port=None, ssl_context=None, auth=None, connect_timeout=10, timeout=30, max_response_length=1MB)`**
+**`uhttp.client.HttpClient(url_or_host, port=None, ssl_context=None, auth=None, connect_timeout=10, timeout=30, max_response_length=1MB, event_mode=False)`**
 
 Can be initialized with URL or host/port:
 
@@ -304,23 +499,37 @@ Parameters:
 - `auth` - Optional (username, password) tuple for HTTP authentication
 - `connect_timeout` - Connection timeout in seconds (default: 10)
 - `timeout` - Response timeout in seconds (default: 30)
-- `max_response_length` - Maximum response size (default: 1MB)
+- `max_response_length` - Maximum buffered body size (default: 1MB)
+- `event_mode` - If `True`, `wait()`/`process_events()` return `EVENT_*`
+  constants instead of `HttpResponse` (see [Streaming & Event Mode](#streaming--event-mode))
 
 #### Properties
 
 - `host` - Server hostname
 - `port` - Server port
 - `base_path` - Base path from URL (prepended to all request paths)
-- `is_connected` - True if socket is connected
-- `state` - Current state (STATE_IDLE, STATE_SENDING, etc.)
+- `is_connected` - True if TCP (and SSL) connection is fully established
+- `state` - Current state (STATE_IDLE, STATE_CONNECTING, STATE_SSL_HANDSHAKE, STATE_SENDING, etc.)
 - `auth` - Authentication credentials tuple (username, password) or None
 - `cookies` - Cookies dict (persistent across requests)
 - `read_sockets` - Sockets to monitor for reading (for select)
 - `write_sockets` - Sockets to monitor for writing (for select)
 
+Event-mode properties (available once headers are received):
+
+- `event` - Last `EVENT_*` constant returned
+- `error` - Error message when the last event was `EVENT_ERROR`
+- `status` - Response status code (int)
+- `status_message` - Response status message (str)
+- `headers` - Response headers dict (keys lowercase)
+- `content_type` - Response Content-Type
+- `content_length` - Response Content-Length, or `None` if unknown
+- `bytes_received` - Decoded body bytes received so far
+- `response` - Completed `HttpResponse` (after `EVENT_RESPONSE` or buffered `EVENT_COMPLETE`)
+
 #### Methods
 
-**`request(method, path, headers=None, data=None, query=None, json=None, auth=None, timeout=None)`**
+**`request(method, path, headers=None, data=None, query=None, json=None, auth=None, timeout=None, expect_continue=False, stream=False)`**
 
 Start HTTP request (async). Returns `self` for chaining.
 
@@ -332,6 +541,8 @@ Start HTTP request (async). Returns `self` for chaining.
 - `json` - Shortcut for data with JSON encoding
 - `auth` - Optional (username, password) tuple, overrides client's default auth
 - `timeout` - Optional timeout in seconds, overrides client's default timeout
+- `expect_continue` - Send `Expect: 100-continue` header and wait for server confirmation before sending body (default: False)
+- `stream` - Read a response without `Content-Length`/chunked framing until the server closes the connection (MJPEG, SSE); default: False
 
 **`get(path, **kwargs)`** - Send GET request
 
@@ -347,18 +558,45 @@ Start HTTP request (async). Returns `self` for chaining.
 
 **`wait(timeout=None)`**
 
-Wait for response (blocking). Returns `HttpResponse` when complete.
+Wait for response (blocking).
 
+- Classic mode: returns `HttpResponse` when complete; raises `HttpTimeoutError`
+  if the request timeout expires; returns `None` if the wait timeout expires
+  (connection stays open, can call again).
+- Event mode: returns the next `EVENT_*` constant, or `None` when the wait
+  timeout expires with nothing new.
 - `timeout` - Max time to spend in wait() call. If `None`, uses request timeout.
-- Returns `None` if wait timeout expires (connection stays open, can call again).
-- Raises `HttpTimeoutError` if request timeout expires (connection closed).
 
 **`process_events(read_sockets, write_sockets)`**
 
-Process select events. Returns `HttpResponse` when complete, `None` otherwise.
+Process select events from an external select loop.
+
+- Classic mode: returns `HttpResponse` when complete (`None` otherwise); raises
+  on errors.
+- Event mode: returns an `EVENT_*` constant (`None` when nothing new yet);
+  connection/decode errors surface as `EVENT_ERROR` with the message in
+  `client.error`.
 
-- First processes any ready data, then checks request timeout.
-- Raises `HttpTimeoutError` if request timeout has expired and no complete response.
+#### Event-mode body methods
+
+Call one of these after `EVENT_HEADERS` to choose how the body is delivered
+(see [Streaming & Event Mode](#streaming--event-mode)):
+
+**`accept_body()`** - Buffer the whole body, then emit `EVENT_COMPLETE`; read
+via the `response` property.
+
+**`accept_body_streaming()`** - Emit `EVENT_DATA` per decoded chunk; read bytes
+via `read_buffer()`.
+
+**`accept_body_to_file(path)`** - Stream the decoded body to a file, then emit
+`EVENT_COMPLETE`.
+
+**`accept_ndjson()`** - Decode newline-delimited JSON; emit `EVENT_DATA` per
+record; read decoded objects via `read_record()`.
+
+**`read_buffer()`** - Return decoded body bytes buffered so far, or `None`.
+
+**`read_record()`** - Return the next decoded NDJSON record, or `None`.
 
 **`close()`**
 
@@ -431,6 +669,34 @@ Supported digest features:
 - Nonce counting for multiple requests
 
 
+## Expect: 100-continue
+
+For large uploads, use `expect_continue=True` to wait for server confirmation before sending the body. This saves bandwidth when the server rejects the request (e.g., 413 Too Large, 401 Unauthorized):
+
+```python
+import uhttp.client
+
+client = uhttp.client.HttpClient('https://api.example.com')
+
+# Large file upload with expect_continue
+large_data = b'x' * 10_000_000  # 10 MB
+response = client.post('/upload', data=large_data, expect_continue=True).wait()
+
+if response.status == 413:
+    print("Server rejected - body was NOT sent (bandwidth saved)")
+else:
+    print(f"Upload complete: {response.status}")
+
+client.close()
+```
+
+How it works:
+1. Client sends headers with `Expect: 100-continue`
+2. Waits for server response
+3. If server sends `100 Continue` → sends body → waits for final response
+4. If server sends other status (413, 401, etc.) → returns that response (body not sent)
+
+
 ## Cookies
 
 Cookies are automatically:
@@ -475,11 +741,26 @@ client.close()
 
 ## Timeouts
 
-Two types of timeouts:
+Three types of timeouts:
+
+### Connect timeout
+
+Time allowed for TCP connect + SSL handshake. Set via `connect_timeout` parameter (default: 10s).
+When expired during connect/handshake phase, raises `HttpTimeoutError`.
+
+```python
+import uhttp.client
+
+# Short connect timeout for fast-fail on unreachable hosts
+client = uhttp.client.HttpClient('https://example.com', connect_timeout=3)
+
+# Long connect timeout for slow 4G/satellite links
+client = uhttp.client.HttpClient('https://example.com', connect_timeout=30)
+```
 
 ### Request timeout
 
-Total time allowed for the request. Set via `timeout` parameter on client or per-request.
+Total time allowed for the entire request (including connect). Set via `timeout` parameter on client or per-request.
 When expired, raises `HttpTimeoutError` and closes connection.
 
 ```python
@@ -492,6 +773,8 @@ client = uhttp.client.HttpClient('https://example.com', timeout=30)
 response = client.get('/slow', timeout=60).wait()
 ```
 
+Both `connect_timeout` and `timeout` are checked during connect/handshake phases — whichever expires first triggers `HttpTimeoutError`.
+
 ### Wait timeout
 
 Time to spend in `wait()` call. When expired, returns `None` but keeps connection open.
@@ -550,6 +833,7 @@ See [examples/](../examples/) directory:
 - `client_basic.py` - Basic blocking examples
 - `client_https.py` - HTTPS examples
 - `client_async.py` - Async select loop examples
+- `client_stream.py` - Event-mode streaming (download-to-file, chunks, NDJSON)
 - `client_with_server.py` - Combined server + client examples
 
 Run examples from project root:
@@ -661,6 +945,36 @@ client = uhttp.client.HttpClient('http://[::1]:8080')
 
 For running tests from meta-repo, see [uhttp README](https://github.com/pavelrevak/uhttp#testing).
 
+### MicroPython integration tests
+
+Tests run on real ESP32 hardware via [mpytool](https://github.com/pavelrevak/mpytool).
+
+**Configuration:**
+
+1. WiFi credentials in `~/.config/uhttp/wifi.json`:
+   ```json
+   {"ssid": "MyWiFi", "password": "secret"}
+   ```
+
+2. Serial port via environment variable or mpytool config:
+   ```bash
+   # Environment variable
+   export MPY_TEST_PORT=/dev/ttyUSB0
+
+   # Or mpytool config
+   echo "/dev/ttyUSB0" > ~/.config/mpytool/ESP32
+   ```
+
+**Run tests:**
+
+```bash
+MPY_TEST_PORT=/dev/ttyUSB0 ../.venv/bin/python -m unittest tests.test_mpy_integration -v
+```
+
+**Note:** MicroPython requires explicit `ssl_context` for HTTPS connections.
+
 ### CI
 
-Tests run automatically on push/PR via GitHub Actions (Ubuntu + Windows, Python 3.10 + 3.14).
+Tests run automatically on push/PR via GitHub Actions:
+- Unit tests: Ubuntu + Windows, Python 3.10 + 3.14
+- MicroPython tests: Self-hosted runner with ESP32