Metadata-Version: 2.4
Name: patera-apiinterface
Version: 0.13.3
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

Within an application lifespan, an interface reuses one HTTP client and closes
it at shutdown. Standalone and CLI endpoint calls use temporary clients closed
before the call returns, including failures. If you acquire `interface.client`
explicitly, call `await interface.aclose()` in that same event loop before it
closes. Access from another loop raises instead of discarding an unclosed client.

`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).
