Metadata-Version: 2.3
Name: restic
Version: 0.1.0a0
Summary: A modern, type-safe Python library for building robust REST API clients with automatic Pydantic validation, async support, and extensible route patterns.
Keywords: api,rest,client,httpx,pydantic,async,wrapper
Author: tobasqo
Author-email: tobasqo <szymon.j.jaskowski@gmail.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: typing-extensions>=4.15.0
Requires-Python: >=3.10
Project-URL: Documentation, https://github.com/tobasqo/restic#readme
Project-URL: Homepage, https://github.com/tobasqo/restic
Project-URL: Repository, https://github.com/tobasqo/restic
Description-Content-Type: text/markdown

# Restic

[![PyPI version](https://badge.fury.io/py/restic.svg)](https://pypi.org/project/restic/)
[![Python versions](https://img.shields.io/pypi/pyversions/restic.svg)](https://pypi.org/project/restic/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A modern, type-safe Python library for building robust REST API clients with automatic Pydantic validation, async support, and extensible route patterns.

## Features

- **Type Safety**: Full type hints and Pydantic model validation for requests and responses
- **Async Support**: Both synchronous and asynchronous operations
- **Generic Routes**: Reusable route classes for common REST operations (CRUD)
- **Error Handling**: Comprehensive exception handling with detailed error messages
- **Flexible Configuration**: Customizable timeouts, authentication, and headers
- **Extensible**: Easy to extend with custom mixins and route logic

## Installation

**Requirements:** Python 3.10+

```bash
pip install restic
```

Or with UV:

```bash
uv add restic
```

## Dependencies

- **httpx**: HTTP client for making requests
- **pydantic**: Data validation and serialization
- **typing-extensions**: Enhanced type hints for older Python versions

## Usage & Examples

The package provides a `ResticClient` base class and reusable route mixins for building type-safe API clients. Routes are composed using mixins for different HTTP operations, with automatic request/response validation via Pydantic models.

See the `examples/` directory for complete usage examples:

- `json_placeholder.py`: Full example with JSONPlaceholder API

The code is simple enough that users can learn how to use it directly from the source code and examples.

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/tobasqo/restic.git
cd restic

# Install with UV
uv sync
```

### Testing

```bash
# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Run formatting
uv run ruff format .

# Run type checking
uv run mypy .
```

### Building

```bash
# Build the package
uv build
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## References

### Packages

These libraries are not integrated into the package but are worth mentioning for those who want to extend functionality:

- [Tenacity](https://tenacity.readthedocs.io/en/latest/) - retry on errors
- [HTTPX Limiter](https://pypi.org/project/httpx-limiter/) - rate limiting

### Other resources

- [Async usage of httpx](https://oneuptime.com/blog/post/2026-02-03-python-httpx-async-requests/view)
