Metadata-Version: 2.4
Name: cruds
Version: 1.6.0
Summary: A lightweight Python client for REST APIs — create, read, update, and delete with zero boilerplate
Author-email: John Brandborg <john.brandborg+pypi@pm.me>
License-Expression: MIT
Project-URL: Changelog, https://cruds.readthedocs.io/en/stable/changelog.html
Project-URL: Documentation, https://cruds.readthedocs.io/en/stable/
Project-URL: Source, https://github.com/johnbrandborg/cruds
Project-URL: Tracker, https://github.com/johnbrandborg/cruds/issues
Keywords: rest,api,crud,http,https,planhat
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2024.2.2
Requires-Dist: urllib3<3.0.0,>=2.5.0
Requires-Dist: PyYAML<7.0.0,>=6.0.1
Requires-Dist: jsonschema<5.0.0,>=4.21.1
Provides-Extra: rtd
Requires-Dist: furo; extra == "rtd"
Requires-Dist: sphinx; extra == "rtd"
Requires-Dist: sphinx-copybutton; extra == "rtd"
Requires-Dist: sphinx-design; extra == "rtd"
Requires-Dist: sphinxext-opengraph; extra == "rtd"
Dynamic: license-file

# CRUDs

[![PyPI - Version](https://img.shields.io/pypi/v/cruds)](https://pypi.org/project/cruds/)
[![Supported Python Version](https://img.shields.io/pypi/pyversions/cruds?logo=python&logoColor=FFE873)](https://pypi.org/project/cruds/)
[![Development](https://github.com/johnbrandborg/cruds/actions/workflows/development.yml/badge.svg)](https://github.com/johnbrandborg/cruds/actions/workflows/development.yml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=johnbrandborg_cruds&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=johnbrandborg_cruds)
[![Documentation Status](https://readthedocs.org/projects/cruds/badge/?version=latest)](https://cruds.readthedocs.io/en/latest/?badge=latest)

**CRUDs** is a lightweight Python client for REST APIs — create, read, update,
and delete with zero boilerplate.

```python
import cruds

api = cruds.Client("https://api.example.com", auth="your-token")

# Create a resource
user = api.create("users", data={"name": "Ada", "role": "engineer"})

# Read it back
user = api.read(f"users/{user['id']}")

# Update it
api.update(f"users/{user['id']}", data={"role": "lead"})

# Delete it
api.delete(f"users/{user['id']}")
```

No response objects to unpack. No manual JSON parsing. No boilerplate retry
logic. Just your data.

## Quickstart

```bash
pip install cruds
```

```python
import cruds

catfacts = cruds.Client("catfact.ninja")
fact = catfacts.read("fact")
print(fact["fact"])
```

## Why CRUDs over requests/httpx?

| You get                    | Without writing          |
|----------------------------|--------------------------|
| Semantic CRUD methods      | HTTP method boilerplate  |
| Automatic JSON SerDes      | `.json()` / `.raise_for_status()` calls |
| Retry with backoff         | `HTTPAdapter` / `Retry` setup |
| Bearer, Basic & OAuth2 auth| Manual header management |
| SSL verification           | `certifi` wiring         |

```python
# requests — 6 lines of ceremony
import requests
response = requests.get("https://api.example.com/users",
                        headers={"Authorization": "Bearer token"})
response.raise_for_status()
users = response.json()

# CRUDs — 2 lines of intent
import cruds
users = cruds.Client("api.example.com", auth="token").read("users")
```

## Features

- **Authentication** — Bearer tokens, username/password, and OAuth2 (Client
  Credentials, Resource Owner Password, Authorization Code with CSRF protection)
- **JSON Serialization** — Send and receive Python dicts and lists directly
- **Multipart File Uploads** — Upload files with `multipart/form-data` via a
  simple `files` parameter
- **Retries with backoff** — Configurable retry count, backoff factor, and
  status codes (429, 500–504, etc.)
- **Error handling** — Automatic exceptions for 4xx/5xx responses
- **SSL verification** — Enabled by default via certifi
- **Logging** — Built-in INFO/DEBUG logging for monitoring
- **Interfaces** — Build SDKs with YAML configuration (ships with a full
  [Planhat](https://cruds.readthedocs.io/en/latest/interfaces.html#planhat)
  interface)

## Documentation

Full user guide, API reference, and examples at
**[cruds.readthedocs.io](https://cruds.readthedocs.io)**.

## License

MIT — see [LICENSE](https://github.com/johnbrandborg/cruds/blob/main/LICENSE).

## Credits

* [urllib3 Team](https://github.com/urllib3)
