Metadata-Version: 2.4
Name: chumicro-requests-experimental
Version: 0.19.0
Summary: Non-blocking HTTP/1.1 client for CircuitPython, MicroPython, and CPython.
Project-URL: Homepage, https://github.com/ChuMicro/ChuMicro
Project-URL: Documentation, https://chumicro.github.io/ChuMicro/requests/experimental/
Project-URL: Source, https://github.com/ChuMicro/ChuMicro/tree/main/libraries/requests
Project-URL: Issues, https://github.com/ChuMicro/ChuMicro/issues
Project-URL: Bundle, https://github.com/ChuMicro/ChuMicro-Bundle-Experimental
Author: ChuMicro
License-Expression: MIT
License-File: LICENSE
Keywords: circuitpython,embedded,esp32,http,microcontroller,micropython,rp2040
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.11
Requires-Dist: chumicro-sockets-experimental
Requires-Dist: chumicro-timing-experimental
Provides-Extra: test
Requires-Dist: chumicro-config-experimental; extra == 'test'
Requires-Dist: chumicro-pytest-device-experimental; extra == 'test'
Requires-Dist: chumicro-test-harness-experimental; extra == 'test'
Requires-Dist: chumicro-wifi-experimental; extra == 'test'
Requires-Dist: chumicro-workspace-experimental; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# chumicro-requests

<img src="https://raw.githubusercontent.com/ChuMicro/ChuMicro/main/support/docs/chumicro_tip.png"
align="left" width="64" style="margin-right: 16px; margin-bottom: 8px;">

**A non-blocking HTTP/1.1 client — your LED keeps blinking through a TLS handshake.**

A `requests`-flavored surface that advances one chunk per runner tick — connect, send, recv, parse — so your control loop never stalls waiting for a peer.  Plain HTTP, HTTPS (live-verified on real boards), POST / PUT / PATCH / DELETE, JSON helper, redirect handling, `Transfer-Encoding: chunked` decode, and `stream=True` for bodies bigger than RAM — read a firmware image into a 512-byte buffer, chunk by chunk.

<br clear="left">

> Part of the [ChuMicro](https://github.com/ChuMicro/ChuMicro) family — small, focused Python libraries for microcontrollers and laptops. [Browse all libraries.](https://github.com/ChuMicro/ChuMicro/tree/main/libraries)

## Install

```bash
# CircuitPython (after `circup bundle-add ChuMicro/ChuMicro-Bundle-Experimental`)
circup install chumicro_requests

# MicroPython
mpremote mip install github:ChuMicro/ChuMicro-Bundle-Experimental/chumicro_requests

# CPython
pip install chumicro-requests-experimental
```

For bundle setup, pre-compiled `.mpy` bundles, the experimental channel, and details on PyPI naming, see the [chumicro INSTALL guide](https://github.com/ChuMicro/ChuMicro/blob/main/INSTALL.md).

## Quick example

```python
from chumicro_requests import HttpClient
from chumicro_sockets.sockets_factory import connector_factory
from chumicro_timing import ticks_ms

client = HttpClient(transport_factory=connector_factory())
handle = client.get("http://api.example.com/now", timeout_ms=5000)

while not handle.done:
    if client.check(ticks_ms()):
        client.handle(ticks_ms())

response = handle.result          # raises HttpError on failure
print(response.status_code)       # 200
print(response.headers["content-type"])
print(response.body)              # raw response bytes
print(response.text)              # decoded str (charset sniffed from Content-Type)
print(response.json())            # parsed JSON when Content-Type is application/json
```

## What's included

| Symbol | Purpose |
|---|---|
| `HttpClient` | Runner-shaped HTTP/1.1 client; `check(now_ms)` / `handle(now_ms)`; per-verb methods plus generic `request(...)`; `stream=True` for incremental bodies; `cancel()` aborts in flight. |
| `RequestHandle` | Per-request handle: `.done`, `.result`, `.error`; `.read_body_into(buffer)` drains a streamed body. |
| `Response` | Status code, reason, headers, raw body, URL; `.text`, `.json()`, `.encoding`; `.streamed` on streamed exchanges. |
| `chumicro_requests.generators` | Opt-in submodule: `yield from`-shaped `fetch` / `get` / `post` / ... one-shots and `stream` + `BodyReader` for chunked body reads under `Runner.add_generator`. |
| `CaseInsensitiveDict` | Header dict with case-insensitive lookups. |
| `WhenOversized` | Policy enum for responses past `max_body_bytes`. |
| `chumicro_sockets.sockets_factory.connector_factory(...)` | Shared module: convenience connection-factory wired to chumicro-sockets. |
| `parse_url(url)` | URL → `(scheme, host, port, path)`. |
| `parse_charset(content_type)` | Extract charset from a Content-Type header value. |
| `encode_request(...)` | Build raw HTTP request bytes. |
| `ResponseParser` | Streaming response state machine. |
| `HttpError` + subclasses | `HttpBusyError`, `HttpTimeoutError`, `HttpProtocolError`, `HttpURLError`, `HttpOversizedError`. |
| `chumicro_requests.testing.FakeHttpClient` | Host-only fake for downstream test suites. |

## Where this fits

Depends on [`chumicro-sockets`](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/sockets) for TCP / TLS and [`chumicro-timing`](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/timing) for ticks.  Used directly in app code.

## Platform support

Works on CPython, MicroPython, and CircuitPython.  Pure Python — no native extensions.

## Examples

| Example | What it shows |
|---|---|
| `periodic_get.py` | Periodic GET on a real CP/MP board.  Brings wifi up, hits a configured URL every N seconds, prints status + body length, drives an LED-blink counter to verify the request never blocks the loop.  Reads wifi + target URL from `runtime_config.msgpack` (chumicro-workspace) with a constants fallback.  Cross-runtime (CP + MP). |

## Wiring wifi credentials for examples and functional tests

The hardware-prefixed examples + real-network suites in `functional_tests/test_real_*.py` need wifi credentials.  See [`docs/wiring-wifi-credentials.md`](https://github.com/ChuMicro/ChuMicro/blob/main/docs/wiring-wifi-credentials.md) for the workspace-based and raw single-file paths.  The library itself never reads TOML — it takes a `transport_factory` and goes; config wiring is application-layer.

## Contributing

Working on `chumicro-requests` itself?  Clone the [mono-repo](https://github.com/ChuMicro/ChuMicro) if you haven't already — the rest of the workflow assumes you're inside that workspace.

```bash
pip install -e .[test]
pytest tests/                  # host-side tests
pytest functional_tests/       # on-device tests (needs a board registered in devices.yml)
```

Register a board before running functional tests: `chumicro-workspace add-device <id> --address <port>`.

## Docs

📖 **[Stable docs](https://chumicro.github.io/ChuMicro/requests/stable/)** · **[Experimental docs](https://chumicro.github.io/ChuMicro/requests/experimental/)**

## Find this library

- **PyPI:** [chumicro-requests](https://pypi.org/project/chumicro-requests/)
- **Bundle:** [ChuMicro-Bundle](https://github.com/ChuMicro/ChuMicro-Bundle/tree/main/chumicro_requests) (CircuitPython & MicroPython)
- **Experimental bundle:** [ChuMicro-Bundle-Experimental](https://github.com/ChuMicro/ChuMicro-Bundle-Experimental/tree/main/chumicro_requests)
- **Source:** [libraries/requests](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/requests)

## License

[MIT](https://github.com/ChuMicro/ChuMicro/blob/main/LICENSE)
