relation

class janim.items.relation.ItemRelation

Bases: Generic

Defines the containment relationships in the directed acyclic graph of items, along with some useful operations.

This class is intended only as a base class for Item and is not meant to be instantiated directly.

property parents: list[RelT]

A copy of the parent-item list

property children: list[RelT]

A copy of the child-item list

has_child() → bool
index(obj: RelT) → int

Get the index of a child item in the list

Parameters:

obj – Child item to find

Returns:

Index of the child item

Raises:

ValueError – Child item not in the list

add(*objs: RelT, prepend: bool = False) → Self

Add child items to this item

Parameters:

  • objs – Child items to add

  • prepend – If insert=True (default is False), then insert at the beginning of the list of child items.

insert(index: int, *objs: RelT) → Self

Insert child items at the specified index

Parameters:

  • index – Index at which to insert

  • objs – Child items to insert

remove(*objs: RelT) → Self

Remove child items from this item

Parameters:

objs – Child items to remove

shuffle() → Self

Randomly shuffle the order of child items

Note

This method uses random.shuffle() to shuffle

For reproducible randomness, set the seed with random.seed() before calling this method

clear_parents() → Self

Clear parent items

clear_children() → Self

Clear child items

ancestors(unordered: bool = False) → list[RelT]

Get a list of ancestor items

Note: This method temporarily constructs a list from walk_ancestors(). For traversal purposes, it is recommended to use walk_ancestors() instead.

Parameters:

unordered – By default, items are traversed in DFS order. If unordered=True is specified, the order is not guaranteed, but performance may be better for complex structures.

descendants(unordered: bool = False) → list[RelT]

Get a list of descendant items

Note: This method temporarily constructs a list from walk_descendants(). For traversal purposes, it is recommended to use walk_descendants() instead.

Parameters:

unordered – By default, items are traversed in DFS order. If unordered=True is specified, the order is not guaranteed, but performance may be better for complex structures.

walk_ancestors(base_cls: None = None, *, unordered: bool = False) → Iterable[RelT]
walk_ancestors(base_cls: type[Filter], *, unordered: bool = False) → Iterable[Filter]

Traverse ancestor nodes for items that are instances of base_cls

Parameters:

  • base_cls – The base class to check against. If omitted, all items are traversed.

  • unordered – By default, items are traversed in DFS order. If unordered=True is specified, the order is not guaranteed, but performance may be better for complex structures.

walk_descendants(base_cls: None = None, *, unordered: bool = False) → Iterable[RelT]
walk_descendants(base_cls: type[Filter], *, unordered: bool = False) → Iterable[Filter]

Traverse descendant nodes for items that are instances of base_cls

Parameters:

  • base_cls – The base class to check against. If omitted, all items are traversed.

  • unordered – By default, items are traversed in DFS order. If unordered=True is specified, the order is not guaranteed, but performance may be better for complex structures.

walk_self_and_ancestors(root_only: bool = False, base_cls: None = None, *, unordered: bool = False) → Iterable[Self | RelT]
walk_self_and_ancestors(root_only: bool = False, base_cls: type[Filter] = object, *, unordered: bool = False) → Iterable[Filter]

Traverse the item itself and its descendant nodes for items that are instances of base_cls

Parameters:

  • root_only – Whether to ignore all ancestor nodes and consider only the root nodes

  • base_cls – The base class to check against. If omitted, all items are traversed.

  • unordered – By default, items are traversed in DFS order. If unordered=True is specified, the order is not guaranteed, but performance may be better for complex structures.

walk_self_and_descendants(root_only: bool = False, base_cls: None = None, *, unordered: bool = False) → Iterable[Self | RelT]
walk_self_and_descendants(root_only: bool = False, base_cls: type[Filter] = object, *, unordered: bool = False) → Iterable[Filter]

Traverse the item itself and its descendant nodes for items that are instances of base_cls

Parameters:

  • root_only – Whether to ignore all descendant nodes and consider only the root nodes

  • base_cls – The base class to check against. If omitted, all items are traversed.

  • unordered – By default, items are traversed in DFS order. If unordered=True is specified, the order is not guaranteed, but performance may be better for complex structures.

walk_nearest_ancestors(base_cls: type[Filter]) → Iterable

Traverse ancestor nodes for items that are instances of base_cls, excluding the ancestors of items that already satisfy the condition

walk_nearest_descendants(base_cls: type[Filter]) → Iterable

Traverse descendant nodes for items that are instances of base_cls, excluding the descendants of items that already satisfy the condition