agravity_client/README.md

agravity-client

A fully Pythonic, Pydantic v2–driven, async REST client for the Agravity DAM API (v10.3.0).

Built on httpx and Pydantic, 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

pip install agravity-client

Or in development mode:

pip install -e ".[dev]"

Quick start

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

# 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:

# 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:

# PowerShell
.\build_wheel.ps1

# Python
python build_wheel.py

# Bash
./build_wheel.sh

Upload to Forgejo PyPI

First, create your .pypirc configuration:

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

Then upload:

# 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