Metadata-Version: 2.4
Name: aur-api-client
Version: 1.0.0
Summary: A thin client for the AUR web API
Author-email: "Atanasio \"Taxo\" Rubio (Groctel)" <git@taxorubio.com>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://git.sr.ht/~groctel/python-aur-api-client
Project-URL: Issues, https://todo.sr.ht/~groctel/python-aur-api-client
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: requests==2.34.2
Provides-Extra: dev
Requires-Dist: pytest==8.3; extra == "dev"
Requires-Dist: pytest-cov==5.0; extra == "dev"
Dynamic: license-file

# python-aur-api

**A thin client for the AUR web API**

## Installation

Even though the repository is called `python-aur-api`, you should find it by
the name `aur-api` in [PyPI]:

```sh
pip install aur-api
```

## Usage

First, import the symbols you need from the `aur` package:

```python
from aur import (
    ErrorResult, InfoResult, SearchBy, SearchResult,
    get_pkg_info, search_pkgbase_startswith, search_pkgname_startswith, search_pkg,
)
```

The package exposes four functions to interact with the AUR web [API endpoints]:

- `get_pkg_info(pkgnames: list[str]) -> InfoResult|ErrorResult`
- `search_pkgbase_startswith(term: str) -> list[str]`
- `search_pkgname_startswith(term: str) -> list[str]`
- `search_pkg(term: str, search_by: SearchBy) -> SearchResult|ErrorResult`

All fucntions make a request to the AUR and return a well-typed result object.
You can check whether you got an error with the following code:

```python
result = get_pkg_info([]) # An empty list will fail!
if isinstance(result, ErrorResult):
    print(f"The error was: {result.error}")
```

Check the `tests/test_basic.py` file for some simple examples.

## Testing

You can run [`pytest`] to run the tests. Since this is a very small project, we
strive to have 100% code coverage:

```sh
pytest --cov=src --cov-report=html --cov-branch --strict-markers
```

<!-- References -->

[API endpoints]: https://aur.archlinux.org/rpc/swagger
[PyPI]: https://pypi.org/
[`pytest`]: https://docs.pytest.org/en/stable/
