Metadata-Version: 2.4
Name: larzhttp
Version: 0.1.0
Summary: An ergonomic HTTP client in pure Python — requests-style API over urllib, with sessions, JSON, retries, timeouts, gzip. Zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzhttp
Project-URL: Repository, https://github.com/larz-scripter/larzhttp
Project-URL: Documentation, https://github.com/larz-scripter/larzhttp#readme
Project-URL: Issues, https://github.com/larz-scripter/larzhttp/issues
Keywords: http,http-client,requests,urllib,rest,api-client,sessions,retries,requests-alternative,zero-dependency,pure-python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# larzhttp

**An ergonomic HTTP client in pure Python. Zero dependencies.**

The `requests`-style API everyone already knows — backed by the standard library
instead of a dependency tree.

```python
import larzhttp

r = larzhttp.get("https://api.example.com/items", params={"page": 2}, timeout=10)
r.status_code            # 200
r.ok                     # True
r.json()                 # parsed body

larzhttp.post(url, json={"name": "Ada"}, headers={"X-Key": "..."}).raise_for_status()
```

## Why

- **Zero dependencies.** It's `urllib` under the hood — nothing to install, no
  transitive supply chain, runs anywhere Python does. Perfect when you don't want
  to pull `requests` (and its deps) into a small tool, a lambda, or a locked-down
  environment.
- **Familiar API.** `get`/`post`/`put`/`patch`/`delete`/`head`, `params=`,
  `json=`, `data=`, `headers=`, `auth=`, `timeout=` — the shapes you already use.
- **The conveniences that matter.** JSON in and out, automatic **gzip/deflate**
  decoding, **basic auth**, cookie-persisting **sessions**, and **retries with
  exponential backoff** on connection errors and 5xx.
- **Real responses.** `.status_code`, `.ok`, `.text`, `.content`, `.json()`,
  `.headers`, `.url`, and `.raise_for_status()`.

## Install

```bash
pip install larzhttp
```

## Usage

```python
import larzhttp

# query params & JSON
larzhttp.get(url, params={"q": "hello", "page": 2})
larzhttp.post(url, json={"name": "Ada"})
larzhttp.post(url, data={"form": "field"})          # url-encoded form

# auth, headers, timeout
larzhttp.get(url, auth=("user", "pass"), headers={"X-Key": "k"}, timeout=5)

# handle errors
r = larzhttp.get(url)
r.raise_for_status()          # raises HTTPError on 4xx/5xx
```

### Sessions

A `Session` reuses headers, cookies, a base URL, and retry settings across
requests:

```python
from larzhttp import Session

with Session(base_url="https://api.example.com",
             headers={"Authorization": "Bearer TOKEN"},
             retries=3) as s:
    me = s.get("/me").raise_for_status().json()
    s.post("/events", json={"type": "login"})
```

### Retries & timeouts

```python
larzhttp.get(url, retries=3)          # backs off on connection errors and 5xx
larzhttp.get(url, timeout=2)          # raises Timeout if exceeded
```

Exceptions: `HTTPError` (from `raise_for_status`), `ConnectionError`, `Timeout`.

## Scope

larzhttp covers the everyday HTTP-client surface with zero dependencies. It's not
(yet) an async client, and it doesn't do HTTP/2 or connection pooling like the
big libraries — if you need those, reach for httpx. For scripts, SDKs, webhooks,
API calls, and services that value a tiny footprint, this is all you need.

## Tests

```bash
python -m unittest discover -s tests -v   # 21 tests against a live localhost server
```

## The Larz stack

Pure-Python, zero-dependency building blocks:

- **[larz](https://github.com/larz-scripter/larz)** — money-native web framework
- **[larzchain](https://github.com/larz-scripter/larzchain)** — from-scratch PoW blockchain
- **[larzmoney](https://github.com/larz-scripter/larzmoney)** — exact, penny-perfect money
- **[larzcrypt](https://github.com/larz-scripter/larzcrypt)** — pure-Python cryptography toolkit
- **[larzdb](https://github.com/larz-scripter/larzdb)** — crash-safe embedded database
- **[larzagent](https://github.com/larz-scripter/larzagent)** — zero-dep AI agent framework
- **[larzchart](https://github.com/larz-scripter/larzchart)** — data to inline SVG charts
- **[larzmark](https://github.com/larz-scripter/larzmark)** — Markdown + SEO static sites
- **[larztask](https://github.com/larz-scripter/larztask)** — durable background job queue
- **[larzvault](https://github.com/larz-scripter/larzvault)** — encrypted secrets manager
- **[larzvm](https://github.com/larz-scripter/larzvm)** — deterministic gas-metered VM
- **[larzcache](https://github.com/larz-scripter/larzcache)** — LRU/TTL/tiered caching
- **[larzvalidate](https://github.com/larz-scripter/larzvalidate)** — schema validation
- **[larzid](https://github.com/larz-scripter/larzid)** — decentralized identity
- **[larzrpc](https://github.com/larz-scripter/larzrpc)** — JSON-RPC over HTTP
- **[larzstate](https://github.com/larz-scripter/larzstate)** — durable workflows & state machines
- **larzhttp** — this library

## License

MIT © larz-scripter
