Trees¶

Methods for managing family trees (/api/trees).

pyclann.client.TreesClient ¶

TreesClient(http: _HttpSession)

Methods for the /api/trees resource.

list ¶

list(*, owner: str | None = None, team_id: str | None = None) -> builtins.list[FamilyTree]

Return family trees, optionally filtered by owner or team.

Parameters:

Name	Type	Description	Default
`owner`	`str \| None`	Return only trees owned by this username.	`None`
`team_id`	`str \| None`	Return only trees linked to this team UUID.	`None`

Returns:

Type	Description
`list[FamilyTree]`	List of :class:`~pyclann.models.FamilyTree` objects.

Raises:

Type	Description
`ClannAuthError`	If not authenticated.

create ¶

create(name: str, display_name: str, owner: str, *, is_primary: bool = False) -> FamilyTree

Create a new family tree.

Parameters:

Name	Type	Description	Default
`name`	`str`	Globally unique slug, e.g. `"smith-family"`.	required
`display_name`	`str`	Human-readable name shown in the UI.	required
`owner`	`str`	Username of the tree owner.	required
`is_primary`	`bool`	Set as the owner's primary tree.	`False`

Returns:

Type	Description
`FamilyTree`	The newly created :class:`~pyclann.models.FamilyTree`.

Raises:

Type	Description
`ClannAuthError`	If not authenticated.
`ClannValidationError`	If the name is already taken.

get ¶

get(name: str) -> FamilyTree

Fetch a family tree by its slug name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique tree slug.	required

Returns:

Type	Description
`FamilyTree`	class:`~pyclann.models.FamilyTree`.

Raises:

Type	Description
`ClannNotFoundError`	If the tree does not exist.
`ClannAuthError`	If not authenticated.

update ¶

update(name: str, display_name: str) -> FamilyTree

Update the display name of a tree.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique tree slug.	required
`display_name`	`str`	New human-readable name.	required

Returns:

Type	Description
`FamilyTree`	The updated :class:`~pyclann.models.FamilyTree`.

Raises:

Type	Description
`ClannNotFoundError`	If the tree does not exist.
`ClannAuthError`	If not authenticated.

delete ¶

delete(name: str) -> None

Delete a tree and all persons exclusively belonging to it.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique tree slug.	required

Raises:

Type	Description
`ClannNotFoundError`	If the tree does not exist.
`ClannAuthError`	If not authenticated.

set_primary ¶

set_primary(name: str) -> FamilyTree

Mark a tree as the owner's primary tree.

Clears is_primary on all other trees belonging to the same owner.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique tree slug.	required

Returns:

Type	Description
`FamilyTree`	The updated :class:`~pyclann.models.FamilyTree`.

Raises:

Type	Description
`ClannNotFoundError`	If the tree does not exist.
`ClannAuthError`	If not authenticated.

set_team ¶

set_team(name: str, team_id: str | None) -> FamilyTree

Link or unlink a team from a tree.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique tree slug.	required
`team_id`	`str \| None`	UUID of the team to link, or `None` to unlink.	required

Returns:

Type	Description
`FamilyTree`	The updated :class:`~pyclann.models.FamilyTree`.

Raises:

Type	Description
`ClannNotFoundError`	If the tree does not exist.
`ClannAuthError`	If not authenticated.

upload_image ¶

upload_image(name: str, data: bytes, content_type: str = 'image/jpeg', filename: str = 'tree.jpg') -> None

Upload a tree avatar image.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique tree slug.	required
`data`	`bytes`	Raw image bytes (JPEG or PNG).	required
`content_type`	`str`	MIME type, e.g. `"image/jpeg"` or `"image/png"`.	`'image/jpeg'`
`filename`	`str`	Filename hint for the multipart field.	`'tree.jpg'`

Raises:

Type	Description
`ClannNotFoundError`	If the tree does not exist.
`ClannValidationError`	If the file type or size is invalid.
`ClannAuthError`	If not authenticated.

get_image ¶

get_image(name: str) -> bytes

Download the tree avatar image.

This endpoint is public — no authentication is required.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique tree slug.	required

Returns:

Type	Description
`bytes`	Raw image bytes.

Raises:

Type	Description
`ClannNotFoundError`	If the tree has no image.