Progression¶

Overview¶

The Progression class combines a list-like structure of IDs (IDType) with the properties of an Ordering. It allows insertion, removal, and slicing while preserving a strict sequence of items. The optional name field enables easy identification or labeling of the progression. Also included is a convenience function, prog(), for quick creation of a new Progression.

Progression¶

class lionagi.protocols.generic.progression.Progression(Element, Ordering[E], Generic[E])¶

Inherits from: Element Ordering

Tracks an ordered sequence of item IDs, plus an optional name. This class offers list-like methods such as indexing, slicing, insertion, and removal while ensuring that the items are all valid IDType objects.

Attributes¶

orderlist[ID[E].ID]: The stored list of IDs, each representing an element in the progression.
namestr | None: An optional string giving this progression a human-readable name.

Validators & Serializers¶

classmethod lionagi.protocols.generic.progression._validate_ordering(value: Any) → list[IDType]¶: Private class method that ensures the given value is a valid list of IDs, flattening nested structures via validate_order(). Raises ValueError if items are invalid.

lionagi.protocols.generic.progression._serialize_order(value: list[IDType]) → list[str]¶

Private instance method that serializes each IDType in the list into its UUID string representation.

Basic Methods¶

lionagi.protocols.generic.progression.__len__() → int¶: Returns the number of IDs in the progression.

lionagi.protocols.generic.progression.__bool__() → bool¶: Returns True if the progression has at least one ID, otherwise False.

lionagi.protocols.generic.progression.__contains__(item: Any) → bool¶: Checks if all IDs in the given item (Element, IDType, UUID, or a collection thereof) exist in this progression.

lionagi.protocols.generic.progression.__getitem__(key: int | slice) → IDType | list[IDType]¶

Fetches either a single ID (if key is an int) or a new sub-Progression (if key is a slice).

Raises¶

lionagi._errors.ItemNotFoundError: If the requested index or slice is out of range.
TypeError: If key is neither an int nor a slice.

lionagi.protocols.generic.progression.__setitem__(key: int | slice, value: Any) → None¶: Replaces items at the specified position(s) with new IDs validated via validate_order().

lionagi.protocols.generic.progression.__delitem__(key: int | slice) → None¶: Removes items at the specified position(s).

Iteration & Utility¶

lionagi.protocols.generic.progression.__iter__() → Iterator[IDType]¶: Iterates over the IDs in order.

lionagi.protocols.generic.progression.__list__() → list[IDType]¶: Returns a shallow copy of the entire order list.

lionagi.protocols.generic.progression.clear() → None¶: Clears all IDs from the progression.

Collective-Like Methods¶

The following methods satisfy the Ordering interface:

lionagi.protocols.generic.progression.include(item: Any) → bool¶: Adds new IDs (if not already present). Returns True if at least one ID was appended, else False.

lionagi.protocols.generic.progression.exclude(item: Any) → bool¶: Removes occurrences of specified IDs. Returns True if one or more items were removed, else False.

Additional List-Like Methods¶

lionagi.protocols.generic.progression.append(item: Any) → None¶: Appends one or more validated IDs to the end of the progression.

lionagi.protocols.generic.progression.pop(index: int = -1) → IDType¶: Removes and returns a single ID by index (defaulting to the last item). Raises lionagi._errors.ItemNotFoundError if the index is invalid.

lionagi.protocols.generic.progression.popleft() → IDType¶: Removes and returns the first ID. Raises lionagi._errors.ItemNotFoundError if the progression is empty.

lionagi.protocols.generic.progression.remove(item: Any) → None¶: Removes the first occurrence of each specified ID. Raises lionagi._errors.ItemNotFoundError if any ID is not found.

lionagi.protocols.generic.progression.count(item: Any) → int¶: Counts occurrences of a given ID in the progression.

lionagi.protocols.generic.progression.index(item: Any, start: int = 0, end: int | None = None) → int¶: Finds the position of the first occurrence of an ID. Raises ValueError if the ID is not found within the given range.

lionagi.protocols.generic.progression.extend(other: Progression)¶: Appends all IDs from another Progression to this one. Raises ValueError if other is not a Progression.

lionagi.protocols.generic.progression.insert(index: int, item: ID.RefSeq) → None¶: Inserts one or more IDs at a specific index.

Advanced Operators¶

lionagi.protocols.generic.progression.__add__(other: Any) → Progression[E]¶: Returns a new Progression with IDs from both this instance and other (validated).

lionagi.protocols.generic.progression.__radd__(other: Any) → Progression[E]¶: Allows concatenation when this progression is on the right-hand side.

lionagi.protocols.generic.progression.__iadd__(other: Any) → Self¶: In-place addition of IDs. Uses append() under the hood.

lionagi.protocols.generic.progression.__sub__(other: Any) → Progression[E]¶: Returns a new Progression excluding any IDs in other.

lionagi.protocols.generic.progression.__isub__(other: Any) → Self¶: In-place removal of IDs found in other. Uses remove() internally.

lionagi.protocols.generic.progression.__reverse__() → Progression[E]¶: Returns a new reversed copy of the progression.

lionagi.protocols.generic.progression.__eq__(other: object) → bool¶: Checks whether two progressions have the same order and name.

lionagi.protocols.generic.progression.__gt__(other: Progression[E]) → bool¶: Compares whether this progression’s order is “greater.”

lionagi.protocols.generic.progression.__lt__(other: Progression[E]) → bool¶: Compares whether this progression’s order is “less.”

lionagi.protocols.generic.progression.__ge__(other: Progression[E]) → bool¶: Greater-or-equal comparison by order.

lionagi.protocols.generic.progression.__le__(other: Progression[E]) → bool¶: Less-or-equal comparison by order.

lionagi.protocols.generic.progression.__repr__() → str¶: Developer-friendly string showing the name and order.

Example¶

from lionagi.protocols.generic.progression import Progression, prog
from lionagi.protocols.generic.element import Element

class MyElem(Element):
    pass

elem1, elem2 = MyElem(), MyElem()

# Create a new progression
p = Progression(order=[elem1.id], name="My Progression")
p.append(elem2)

# Alternatively, use the `prog` function
p2 = prog([elem1, elem2], name="Quickly Built")
assert p2.name == "Quickly Built"

prog¶

lionagi.protocols.generic.progression.prog(order: Any, name: str = None) → Progression¶

A convenience function to instantiate a new Progression without manually creating the object.

Parameters¶

orderAny: Any structure that can be validated by validate_order(), e.g., a list of Element, IDType, or string-based UUIDs.
namestr, optional: A label for the newly created progression.

Returns¶

Progression: The resulting progression containing the validated IDs.

File Location¶

Source File: lionagi/protocols/generic/progression.py