Metadata-Version: 2.4
Name: patera-apiinterface
Version: 0.11.0
Summary: Declarative async HTTP clients for external APIs in Patera applications
Keywords: patera,http,client,api
Author: Marko Šterk
Author-email: Marko Šterk <marko_sterk@hotmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Dist: httpx>=0.28.1
Requires-Dist: patera>=0.121
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/MarkoSterk/Patera
Project-URL: Documentation, https://github.com/MarkoSterk/Patera#readme
Project-URL: Repository, https://github.com/MarkoSterk/Patera
Project-URL: Issues, https://github.com/MarkoSterk/Patera/issues
Project-URL: Changelog, https://github.com/MarkoSterk/Patera/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# patera-apiinterface

Declarative async HTTP clients for external APIs in Patera applications. Part of [Patera](https://github.com/MarkoSterk/Patera), a modular async-first Python web framework.

## Installation

```sh
pip install patera-apiinterface
# or, with uv
uv add "patera[apiinterface]"
```

Requires Python 3.13 or newer and `patera>=0.121`.

## Usage

`patera-apiinterface` turns annotated methods into HTTP calls (with [HTTPX](https://www.python-httpx.org)):

```python
from patera import HttpMethod
from patera.apiinterface import ApiInterface, AuthType, auth, headers, method, resource, service, timeout


@service("GITHUB_URL")                         # config key or literal URL
@auth(AuthType.BEARER, token="GITHUB_TOKEN")   # config key or literal value
@headers({"X-Client": "my-app"})
@timeout(10)
class GithubApi(ApiInterface):

    @method(HttpMethod.GET)
    @resource("/repos/<repo_id>")              # filled from the argument of the same name
    async def get_repo(self, repo_id: int) -> Repo: ...   # Pydantic return types are validated

    @method(HttpMethod.POST)
    @resource("/repos")
    async def create_repo(self, name: str, private: bool) -> dict: ...   # arguments become the JSON body
```

See the [External APIs section of the Patera documentation](https://github.com/MarkoSterk/Patera#external-apis) for the full guide.

## License

MIT. See [LICENSE](https://github.com/MarkoSterk/Patera/blob/main/LICENSE).
