Persons¶

Methods for managing persons (/api/persons).

pyclann.client.PersonsClient ¶

PersonsClient(http: _HttpSession)

Methods for the /api/persons resource.

list ¶

list(*, created_by: str | None = None, tree: str | None = None) -> builtins.list[Person]

Return persons, optionally filtered by creator or tree.

Parameters:

Name	Type	Description	Default
`created_by`	`str \| None`	Return only persons created by this username.	`None`
`tree`	`str \| None`	Return only persons belonging to this tree slug.	`None`

Returns:

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

Raises:

Type	Description
`ClannAuthError`	If not authenticated.

create ¶

create(family_name: str, first_name: str, sex: Sex | str, trees: list[str], *, middle_name: str | None = None, date_of_birth: str | None = None, place_of_birth: str | None = None, date_of_death: str | None = None, place_of_death: str | None = None, nickname: str | None = None, username: str | None = None, email: str | None = None, biography: str | None = None, created_by: str | None = None) -> Person

Add a person to the database.

Parameters:

Name	Type	Description	Default
`family_name`	`str`	Family/surname.	required
`first_name`	`str`	Given name.	required
`sex`	`Sex \| str`	`Sex.MALE`, `Sex.FEMALE`, or the raw strings `"Male"`/`"Female"`.	required
`trees`	`list[str]`	Non-empty list of tree slugs this person belongs to.	required
`middle_name`	`str \| None`	Middle name.	`None`
`date_of_birth`	`str \| None`	ISO 8601 date or free-form string.	`None`
`place_of_birth`	`str \| None`	Place of birth.	`None`
`date_of_death`	`str \| None`	ISO 8601 date or free-form string.	`None`
`place_of_death`	`str \| None`	Place of death.	`None`
`nickname`	`str \| None`	Nickname.	`None`
`username`	`str \| None`	Associated user account username.	`None`
`email`	`str \| None`	Email address.	`None`
`biography`	`str \| None`	Markdown biography.	`None`
`created_by`	`str \| None`	Username of the creator.	`None`

Returns:

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

Raises:

Type	Description
`ClannAuthError`	If not authenticated.
`ClannValidationError`	If `trees` is empty or a tree doesn't exist.

get ¶

get(person_id: str) -> Person

Fetch a person by record ID.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID (`"person:01jd4a8xyz"`) or bare ULID.	required

Returns:

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

Raises:

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

update ¶

update(person_id: str, *, family_name: str | None = None, first_name: str | None = None, middle_name: str | None = None, sex: Sex | str | None = None, date_of_birth: str | None = None, place_of_birth: str | None = None, date_of_death: str | None = None, place_of_death: str | None = None, nickname: str | None = None, username: str | None = None, email: str | None = None, verified: bool | None = None, biography: str | None = None, created_by: str | None = None) -> Person

Update a person; only supplied fields are changed (MERGE semantics).

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID.	required

Returns:

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

Raises:

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

delete ¶

delete(person_id: str) -> None

Delete a person and all their relationship edges.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID.	required

Raises:

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

add_to_tree ¶

add_to_tree(person_id: str, tree: str) -> None

Add a person to an additional family tree.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID.	required
`tree`	`str`	Tree slug to add.	required

Raises:

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

remove_from_tree ¶

remove_from_tree(person_id: str, tree_name: str) -> None

Remove a person from a family tree.

A person must belong to at least one tree; removing from the last tree raises a :exc:~pyclann.exceptions.ClannValidationError.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID.	required
`tree_name`	`str`	Tree slug to remove.	required

Raises:

Type	Description
`ClannNotFoundError`	If the person does not exist.
`ClannValidationError`	If this is the person's last tree.
`ClannAuthError`	If not authenticated.

upload_image ¶

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

Upload a profile picture.

Accepts JPEG or PNG only; maximum 2 MB.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID.	required
`data`	`bytes`	Raw image bytes.	required
`content_type`	`str`	`"image/jpeg"` or `"image/png"`.	`'image/jpeg'`
`filename`	`str`	Filename hint for the multipart field.	`'profile.jpg'`

Raises:

Type	Description
`ClannNotFoundError`	If the person does not exist.
`ClannValidationError`	If the file type or size is invalid.
`ClannAuthError`	If not authenticated or storage quota exceeded.

get_image ¶

get_image(person_id: str) -> bytes

Download a person's profile picture.

This endpoint is public — no authentication is required.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID.	required

Returns:

Type	Description
`bytes`	Raw image bytes.

Raises:

Type	Description
`ClannNotFoundError`	If no image has been uploaded.

upload_life_image ¶

upload_life_image(person_id: str, data: bytes, content_type: str = 'image/jpeg', filename: str = 'life.jpg') -> None

Upload life-story media (photo, video, audio, or document).

Individual/Family plans accept images only. Professional/Enterprise plans also accept video (MP4, MOV, WebM), audio (MP3, WAV, OGG), and PDF.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID.	required
`data`	`bytes`	Raw file bytes.	required
`content_type`	`str`	MIME type of the file.	`'image/jpeg'`
`filename`	`str`	Filename hint for the multipart field.	`'life.jpg'`

Raises:

Type	Description
`ClannNotFoundError`	If the person does not exist.
`ClannValidationError`	If the file type is invalid.
`ClannAuthError`	If the plan does not allow this media type, or storage quota exceeded.

get_life_image ¶

get_life_image(person_id: str) -> bytes

Download a person's life-story media file.

This endpoint is public — no authentication is required.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID.	required

Returns:

Type	Description
`bytes`	Raw file bytes.

Raises:

Type	Description
`ClannNotFoundError`	If no life media has been uploaded.