# agravity-client

A fully **Pythonic, Pydantic v2–driven, async** REST client for the
[Agravity DAM API](https://agravity.io) (v10.3.0).

Built on [`httpx`](https://www.python-httpx.org/) and
[Pydantic](https://docs.pydantic.dev/), this library gives you:

- **Typed return values** – every endpoint returns a validated Pydantic model.
- **Async-first** – all network calls are `async def` using `httpx.AsyncClient`.
- **Context-manager support** – clean connection lifecycle.
- **Auto-configuration** – reads `AGRAVITY_*` env vars or a `.env` file via
  `pydantic-settings`.


## Installation

```bash
pip install agravity-client
```

_Or in development mode:_

```bash
pip install -e ".[dev]"
```


## Quick start

```python
import asyncio
from agravity_client import AgravityClient, AgravityConfig

async def main():
    config = AgravityConfig(api_key="YOUR_API_KEY")  # or set AGRAVITY_API_KEY env var

    async with AgravityClient(config) as client:
        # ------------------------------------------------------------------
        # Version & capabilities
        # ------------------------------------------------------------------
        version = await client.general.get_version()
        print(version.version)

        # ------------------------------------------------------------------
        # List assets in a collection
        # ------------------------------------------------------------------
        page = await client.assets.list_assets(
            collection_id="your-collection-id",
            limit=25,
        )
        for asset in page.assets or []:
            print(asset.id, asset.name)

        # ------------------------------------------------------------------
        # Upload an asset
        # ------------------------------------------------------------------
        with open("photo.jpg", "rb") as fh:
            new_asset = await client.assets.upload_asset(
                fh.read(),
                "photo.jpg",
                name="My photo",
                collection_id="your-collection-id",
            )
        print("Created:", new_asset.id)

        # ------------------------------------------------------------------
        # Search
        # ------------------------------------------------------------------
        from agravity_client.models import AzSearchOptions
        results = await client.search.search(
            AzSearchOptions(searchterm="sunset", limit=10)
        )
        print(results.count, "results")

asyncio.run(main())
```


## Configuration

| Setting | Env variable | Default |
|---------|-------------|---------|
| `base_url` | `AGRAVITY_BASE_URL` | `https://devagravitypublic.azurewebsites.net/api` |
| `api_key` | `AGRAVITY_API_KEY` | _(empty)_ |
| `timeout` | `AGRAVITY_TIMEOUT` | `60.0` |
| `verify_ssl` | `AGRAVITY_VERIFY_SSL` | `true` |

Copy `.env.example` to `.env` and fill in your values.


## API modules

| Attribute | Endpoints covered |
|-----------|-------------------|
| `client.assets` | `/assets`, `/assetsupload`, `/assetsbulkupdate`, all sub-resources |
| `client.collections` | `/collections` CRUD, ancestors, descendants, preview, bynames |
| `client.collection_types` | `/collectiontypes` |
| `client.relations` | `/relations`, `/assetrelationtypes` |
| `client.search` | `/search`, `/search/facette`, `/search/adminstatus`, `/savedsearch` |
| `client.sharing` | `/sharing`, `/sharing/quickshares` |
| `client.portals` | `/portals` |
| `client.workspaces` | `/workspaces` |
| `client.auth` | `/auth/containerwrite`, `/auth/inbox`, `/auth/users` |
| `client.download_formats` | `/downloadformats` |
| `client.static_lists` | `/staticdefinedlists` |
| `client.translations` | `/translations` |
| `client.publishing` | `/publish` |
| `client.secure_upload` | `/secureupload` |
| `client.helper` | `/helper/*` |
| `client.webappdata` | `/webappdata` |
| `client.general` | `/version`, `/deleted`, `/durable`, `/negotiate`, `/public`, `/config` |
| `client.ai` | `/ai/reverseassetsearch` |


## Development

```bash
# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Unix

# Install in editable mode with all dev dependencies
pip install -e ".[dev]"

# Lint & format
ruff check .
ruff format .

# Type-check
mypy agravity_client

# Run tests
pytest
```


## Building & Publishing

### Update Version

Update the version number across all project files:

```bash
# PowerShell
.\update_version.ps1 0.2.0

# Python
python update_version.py 0.2.0

# Bash
./update_version.sh 0.2.0
```

### Build Wheel

Build distribution packages:

```bash
# PowerShell
.\build_wheel.ps1

# Python
python build_wheel.py

# Bash
./build_wheel.sh
```

### Upload to Forgejo PyPI

First, create your `.pypirc` configuration:

```bash
cp .pypirc.example .pypirc
# Edit .pypirc with your Forgejo access token
```

Then upload:

```bash
# PowerShell
.\upload_wheel_to_forgejo_pypi.ps1

# Bash
./upload_wheel_to_forgejo_pypi.sh

# Windows Batch
upload_wheel_to_forgejo_pypi.bat
```

The package will be available at:
`https://git.him-tools.de/HIM-public/-/packages/pypi/agravity-client`


## Licence

MIT