Relationships¶

Methods for managing relationship edges between persons.

pyclann.client.RelationshipsClient ¶

RelationshipsClient(http: _HttpSession)

Methods for the /api/persons/{id}/relationships resource.

add ¶

add(person_id: str, rel_type: RelationshipType | str, related_id: str, *, sibling_type: SiblingType | str | None = None, spouse_from: str | None = None, spouse_to: str | None = None) -> None

Add a relationship between two persons.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID of the subject person.	required
`rel_type`	`RelationshipType \| str`	`RelationshipType.FATHER`, `MOTHER`, `SIBLING`, or `SPOUSE`.	required
`related_id`	`str`	Full record ID of the related person (`"person:01jd4a8xyz"`).	required
`sibling_type`	`SiblingType \| str \| None`	`SiblingType.BROTHER` or `SISTER`; required for Sibling relationships.	`None`
`spouse_from`	`str \| None`	Optional marriage/partnership start date.	`None`
`spouse_to`	`str \| None`	Optional marriage/partnership end date.	`None`

Raises:

Type	Description
`ClannValidationError`	If `sibling_type` is missing for a Sibling relationship.
`ClannAuthError`	If not authenticated.

get ¶

get(person_id: str) -> RelationshipsResponse

Return all relationships for a person, grouped by type.

Parameters:

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

Returns:

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

Raises:

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

remove ¶

remove(person_id: str, rel_type: RelationshipType | str, related_id: str) -> None

Delete a relationship edge.

Spouse edges are bidirectional; both directions are removed.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID of the subject person.	required
`rel_type`	`RelationshipType \| str`	:class:`~pyclann.models.RelationshipType` enum or its `url_slug` (`"has_father"`, `"has_mother"`, `"has_sibling"`, `"has_spouse"`).	required
`related_id`	`str`	Full record ID of the related person (`"person:01jd4a8xyz"`).	required

Raises:

Type	Description
`ClannValidationError`	If `rel_type` is not a recognised relationship table.
`ClannAuthError`	If not authenticated.

update_spouse_dates ¶

update_spouse_dates(person_id: str, related_id: str, *, spouse_from: str | None = None, spouse_to: str | None = None) -> None

Update the date attributes on a spouse relationship.

Parameters:

Name	Type	Description	Default
`person_id`	`str`	Full record ID or bare ULID of the subject person.	required
`related_id`	`str`	Full record ID of the spouse (`"person:01jd4a8xyz"`).	required
`spouse_from`	`str \| None`	New marriage/partnership start date, or `None` to clear.	`None`
`spouse_to`	`str \| None`	New marriage/partnership end date, or `None` to clear.	`None`

Raises:

Type	Description
`ClannAuthError`	If not authenticated.

get_family_tree ¶

get_family_tree(person_id: str) -> FamilyTreeNode

Return the recursive family-tree view centred on a person.

Goes up to 2 generations deep for ancestors; children, spouses, and siblings of the root are also included.

Parameters:

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

Returns:

Type	Description
`FamilyTreeNode`	class:`~pyclann.models.FamilyTreeNode` for the root person.

Raises:

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