Metadata-Version: 2.4
Name: curlyshed
Version: 0.1.0
Summary: Python on libcurl: HTTP client (sync and asyncio), WebSocket, a requests compatibility layer
Keywords: curl,libcurl,http,requests,websocket,asyncio
Author: Stefan Tatschner
Author-email: Stefan Tatschner <stefan.tatschner@mailbox.org>
License-Expression: EUPL-1.2
License-File: LICENSES/EUPL-1.2.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Dist: pycurl>=7.48.0
Requires-Python: >=3.14
Project-URL: Homepage, https://codeberg.org/rumpelsepp/curlyshed
Project-URL: Documentation, https://codeberg.org/rumpelsepp/curlyshed/src/branch/master/docs/guide.md
Project-URL: Issues, https://codeberg.org/rumpelsepp/curlyshed/issues
Description-Content-Type: text/markdown

# curlyshed

A Python HTTP client on top of [libcurl](https://curl.se/libcurl/) with blocking
and asyncio APIs, streaming responses and an optional requests compatibility layer.

## Install

```sh
uv add curlyshed
```

curlyshed 0.1 is an alpha and requires Python 3.14+, PycURL 7.48+ and libcurl
8.16+. PycURL wheels bundle libcurl on supported platforms. Building PycURL
from source requires libcurl development files and a C compiler.

## Quick start

```python
from curlyshed import http

with http.Client() as client:
    response = client.get("https://httpbingo.org/get", params={"q": "honey"})
    response.raise_for_status()
    print(response.json())
```

Use `http.AsyncClient` with `async with` and `await` for concurrent requests.
Existing requests code can opt in with `from curlyshed import requests`.
The upstream suite passes 272 of 366 tests. See the
[compatibility report](https://codeberg.org/rumpelsepp/curlyshed/src/branch/master/docs/requests-compat.md).

## HTTP features

- [x] HTTP/1.1 · `ClientConfig(http_version="1.1")`
- [x] HTTP/2 · `ClientConfig(http_version="2")`
- [x] HTTP/3 / QUIC · `ClientConfig(http_version="3")`
- [x] Connection reuse · reuse a `Client`, `AsyncClient` or `requests.Session`
- [x] HTTP/2 multiplexing · concurrent requests on one `AsyncClient`
- [x] Alt-Svc · `ClientConfig(alt_svc=True)`
- [x] Redirects · `follow_redirects=`, `ClientConfig(max_redirects=...)`
- [x] Cookies · `ClientConfig(cookies=True)`
- [x] Response decompression · `decode=True` (default)
- [x] HTTP(S) and SOCKS proxies · proxy environment variables or `proxies=` in requests
- [x] Custom CA bundle · `ClientConfig(ca_bundle=...)` or `verify=` in requests
- [x] TLS client certificates · `cert=` in requests
- [x] Basic and Digest authentication · `auth=` in requests
- [x] Range requests, conditional requests and Bearer auth · `headers=`
- [x] Streaming downloads · `stream()`, `output=` or `stream=True` in requests
- [x] Streaming uploads · binary file as `content=` in `Client` or `data=` in requests
- [x] Multipart uploads · `files=` in requests
- [x] Custom methods and URLs · `request(method, ...)`, `URL`, `params=`
- [x] Transfer limits · `ClientConfig(connect_timeout=..., timeout=..., total_timeout=..., max_body_size=...)`
- [x] Verbose transfer trace · `ClientConfig(trace=True)`
- [ ] Strict HTTP versions and cleartext HTTP/2 · `--http3-only`, `--http2-prior-knowledge`, `--http1.0`
- [ ] DNS and connection routing · `--doh-url`, `--resolve`, `--connect-to`, `--interface`, `-4`, `-6`
- [ ] TLS version and cipher selection · `--tlsv1.2`, `--tls-max`, `--ciphers`, `--tls13-ciphers`
- [ ] Public-key pinning, OCSP and HSTS · `--pinnedpubkey`, `--cert-status`, `--hsts`
- [ ] Automatic download resume and ETag files · `--continue-at -`, `--etag-save`, `--etag-compare`
- [ ] Bandwidth limiting and progress reporting · `--limit-rate`, libcurl's `CURLOPT_XFERINFOFUNCTION`
- [ ] Persistent cookie and Alt-Svc caches · `--cookie-jar`, `--alt-svc <file>`
- [ ] NTLM, Negotiate and automatic auth selection · `--ntlm`, `--negotiate`, `--anyauth`
- [ ] Separate proxy headers, proxy chaining and HTTPS proxy TLS settings · `--proxy-header`, `--preproxy`, `--proxy-cacert`
- [ ] Streaming uploads in `AsyncClient` · file or async iterator as a request body

See the [guide](https://codeberg.org/rumpelsepp/curlyshed/src/branch/master/docs/guide.md)
for examples and use `python -m curlyshed` to check your libcurl build.

## Benchmarks

![Async HTTP benchmark with 50 concurrent requests on Python 3.14, led by curlyshed at 12,713 requests per second](https://codeberg.org/rumpelsepp/curlyshed/raw/branch/master/docs/benchmark/plot-hero.svg)

[Results, raw measurements and reproduction instructions](https://codeberg.org/rumpelsepp/curlyshed/src/branch/master/docs/benchmark.md)

## License

[EUPL-1.2](https://codeberg.org/rumpelsepp/curlyshed/src/branch/master/LICENSES/EUPL-1.2.txt).
The vendored requests test suite is
[Apache-2.0](https://codeberg.org/rumpelsepp/curlyshed/src/branch/master/LICENSES/Apache-2.0.txt).
