ClannClient

The top-level client. Instantiate once, call login(), then access resources through the sub-client attributes.

pyclann.ClannClient

ClannClient(api_url: str, auth_url: str | None = None)

Client for the Clann family-tree REST API.

Authentication is handled by the ullav-user-management service (separate from the Clann server). Call :meth:login before making any API requests; a :exc:~pyclann.exceptions.ClannAuthError will be raised otherwise.

The JWT is stored in the session and sent automatically with every request. Tokens expire according to the server's configuration; call :meth:login again to refresh.

Parameters:

Name	Type	Description	Default
api_url	str	Base URL of the Clann server, e.g. "http://localhost:8090".	required
auth_url	str | None	Base URL of the authentication service, e.g. "http://localhost:8081". Defaults to api_url when both services are behind the same proxy.	None

Example

.. code-block:: python

from pyclann import ClannClient

client = ClannClient(
    api_url="http://localhost:8090",
    auth_url="http://localhost:8081",
)
client.login(email="user@example.com", password="secret")

# Trees
trees = client.trees.list(owner="alice")
tree = client.trees.create("walsh-family", "Walsh Family", owner="alice")

# Persons
person = client.persons.create(
    "Walsh", "Patrick", "Male",
    trees=["walsh-family"],
    created_by="alice",
)

# Relationships
client.relationships.add(
    person.id,
    "Father",
    father.id,
)

# Life events
client.life_events.create(
    person.id, "Born in Galway", "Birth",
    date="1845-03-12",
    created_by="alice",
)

login

login(email: str, password: str) -> LoginInfo

Authenticate and store the JWT for subsequent requests.

Parameters:

Name	Type	Description	Default
email	str	User email address.	required
password	str	User password.	required

Returns:

Type	Description
LoginInfo	class:~pyclann.models.LoginInfo containing the token, user
LoginInfo	details, roles, and permissions.

Raises:

Type	Description
ClannAuthError	If the credentials are invalid.