Metadata-Version: 2.4
Name: katunog
Version: 1.0.1
Summary: Katunog API
Author-email: Fred Tupas <fred.tupas21@gmail.com>
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: aiohttp<4.0.0,>=3.9.5
Requires-Dist: pandas<3.0.0,>=2.2.2
Requires-Dist: pydantic>=2.13.4
Description-Content-Type: text/markdown

# Katunog API Project

## Overview

The Katunog project is a comprehensive initiative developed by the Department of
Science and Technology (DOST) to create a music database of Philippine
indigenous instruments and make them available to the public. The project's
primary objective is to bridge the gap between traditional music practices and
the current generation by providing an online portal containing rich
descriptions, sound variations, and related multimedia of various Philippine
musical instruments.

This repository provides `katunog`, an async Python client for the Katunog
GraphQL API, plus a command-line tool built on top of it.

## Prerequisites

-   [uv](https://docs.astral.sh/uv/) -- manages the Python install (pinned via
    `.python-version`) and all dependencies, so you don't need Python or
    Poetry installed separately.
-   `make`

## Setup

```shell
git clone https://github.com/ftupas/katunog.git
cd katunog
make install
```

`make install` runs `uv sync`, which installs the pinned Python version (if
needed) and all project dependencies from `pyproject.toml` / `uv.lock`.

## Usage

### As a library

```python
import asyncio

from katunog import KatunogClient


async def main() -> None:
    async with KatunogClient() as client:
        page = await client.list_instruments(page=1, limit=10)
        for instrument in page.objects:
            print(instrument.local_name, instrument.english_name)

        instrument = await client.get_instrument(page.objects[0].id)
        if instrument is not None:
            await client.download_media(instrument, file_type="audio", dest="downloads/audio.zip")


asyncio.run(main())
```

See `src/katunog/client.py` for the full set of available methods
(`list_instruments`, `get_instrument`, `provinces`, `regions`, `islands`,
`hornbostels`, `ethnolinguistics`, `summaries`, `site_settings`,
`featured_instruments`, `download_media`, ...).

### CLI

A `katunog` console script is also available:

```shell
uv run katunog --help
```

## Testing

```shell
make test
```

Runs the offline test suite (with coverage). Tests that hit the real Katunog
server are opt-in and excluded by default; run them explicitly with:

```shell
make test-live
```

## Releasing

Releases are cut by CI from tags. To publish version `X.Y.Z`:

```shell
# 1. bump `version` in pyproject.toml, commit it
git tag vX.Y.Z && git push origin vX.Y.Z
```

`.github/workflows/release.yml` then runs on the tag: it fails fast if the tag
and the `pyproject.toml` version disagree (a PyPI version can never be
republished), runs `make lint` / `make test` / `make build`, publishes to PyPI
via [trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no
API token stored), creates the GitHub release, and commits the regenerated
`CHANGELOG.md` back to `main`.

One-time setup before the first release:

-   PyPI → project → *Publishing* → add a trusted publisher: owner `ftupas`,
    repo `katunog`, workflow `release.yml`, environment `pypi`. If the project
    does not exist on PyPI yet, add it as a *pending* publisher.
-   GitHub → *Settings* → *Environments* → create an environment named `pypi`.

### Changelog

[`CHANGELOG.md`](CHANGELOG.md) and the release notes are generated from the
commit history by [git-cliff](https://git-cliff.org) (config: `cliff.toml`) —
don't edit them by hand, the next release overwrites your edits.

Because they are only as good as the commit subjects, write commits as
`type: imperative subject`:

```
feat: add dataframe export to the list command
fix: retry downloads that 500 on the first attempt
```

`feat`/`init` land under **Features**, `fix` under **Bug Fixes**, `perf`,
`refactor`, `docs` and `test` under their own headings, and anything else under
**Other Changes**. `chore`, `ci`, `build` and `style` commits are dropped as
noise. Preview what the next release will say:

```shell
uvx git-cliff --unreleased --tag vX.Y.Z
```

## Documentation

For the full API research this client was built against (endpoints, quirks,
and gotchas of the upstream Katunog server), see
[`docs/api-endpoints.md`](docs/api-endpoints.md).

## License

MIT
