199 lines
5.1 KiB
Markdown
199 lines
5.1 KiB
Markdown
# 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
|