AtoM AHG Python SDK

Python client library for the AtoM (Access to Memory) REST API.

Developed by The Archive and Heritage Group (Pty) Ltd.

Installation

pip install atom-ahg

Or install from source:

git clone https://github.com/ArchiveHeritageGroup/atom-ahg-python.git
cd atom-ahg-python
pip install -e .

Quick Start

from atom_ahg import AtomClient

# Initialize client
client = AtomClient(
    base_url="https://your-atom-instance.com",
    api_key="your-api-key"  # Optional for public endpoints
)

# List descriptions
descriptions = client.descriptions.list(limit=10)
for desc in descriptions.results:
    print(f"{desc.reference_code}: {desc.title}")

# Get a specific description
desc = client.descriptions.get("my-fonds-slug", full=True)
print(desc.scope_and_content)

# Search
results = client.search("photographs", entity_type="informationObject")
print(f"Found {results.total} results")

# Iterate over all descriptions
for desc in client.descriptions.iter_all(batch_size=100):
    process(desc)

Async Support

import asyncio
from atom_ahg import AsyncAtomClient

async def main():
    async with AsyncAtomClient("https://atom.example.com") as client:
        descriptions = await client.get("/api/v2/descriptions")
        print(descriptions)

asyncio.run(main())

API Resources

Descriptions (Information Objects)

# List
descriptions = client.descriptions.list(
    limit=10,
    offset=0,
    repository="my-repo",
    level="fonds"
)

# Get single
desc = client.descriptions.get("slug-or-id")
desc = client.descriptions.get("slug", full=True)  # Include nested data

# Create
new_desc = client.descriptions.create({
    "title": "My New Fonds",
    "levelOfDescription": "fonds",
    "repository": "my-repository-slug"
})

# Update
updated = client.descriptions.update("slug", {"title": "Updated Title"})

# Delete
client.descriptions.delete("slug")

Authorities (Actors)

# List
authorities = client.authorities.list(entity_type="corporateBody")

# Get
actor = client.authorities.get("person-slug")

# Create/Update/Delete
client.authorities.create({...})
client.authorities.update("slug", {...})
client.authorities.delete("slug")

Repositories

repos = client.repositories.list()
repo = client.repositories.get("repo-slug")

Taxonomies

taxonomies = client.taxonomies.list()
terms = client.taxonomies.get_terms("subject-taxonomy")

Search

# Basic search
results = client.search("query")

# Filtered search
results = client.search(
    "photographs",
    entity_type="informationObject",
    limit=50,
    filters={"repository": "my-repo"}
)

Batch Operations

# Batch create
result = client.batch.create_descriptions([
    {"title": "Item 1", ...},
    {"title": "Item 2", ...},
])

# Batch delete
result = client.batch.delete_descriptions(["slug1", "slug2"])

Error Handling

from atom_ahg import AtomClient
from atom_ahg.exceptions import (
    AtomAPIError,
    AtomAuthError,
    AtomNotFoundError,
    AtomValidationError
)

try:
    desc = client.descriptions.get("non-existent")
except AtomNotFoundError:
    print("Description not found")
except AtomAuthError:
    print("Authentication failed")
except AtomAPIError as e:
    print(f"API error: {e}")

Configuration

client = AtomClient(
    base_url="https://atom.example.com",
    api_key="your-api-key",
    timeout=60.0,           # Request timeout in seconds
    verify_ssl=True,        # SSL certificate verification
)

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src tests
ruff check src tests

# Type checking
mypy src

License

GPL-3.0 - See LICENSE for details.

Support

• Issues: https://github.com/ArchiveHeritageGroup/atom-ahg-python/issues
• Documentation: https://theahg.co.za/docs/sdk/python