Pyochain Library: Overview of the API

Pyochain provides collections, iterators, ABCs, and error/nullability handling types, all designed to work together in a cohesive and intuitive way.

Below is a diagram showing the pyochain API, and the relationships between its core types.

the colors represent the different categories of types:

Purple: small mixins classes
Green: abstract collection protocols, mirroring collections.abc
Blue: concrete collection types, implementing the abstract protocols and mirroring python standard library collections
Red: Result and its variants
Yellow: Option and its variants

---
config:
  layout: elk
---
flowchart TB
    Pipeable["Pipeable"] ==> PyoIterable["PyoIterable[T]"] & Result["Result[T, E]"] & Option["Option[T]"]
    Checkable["Checkable"] ==> PyoIterable
    PyoIterable --> PyoIterator["PyoIterator[T]"] & PyoCollection["PyoCollection[T]"]
    PyoIterator ==> Iter["Iter[T]"]
    PyoCollection --> PyoSequence["PyoSequence[T]"] & PyoSet["PyoSet[T]"] & PyoMappingView["PyoMappingView[T]"] & PyoMapping["PyoMapping[K,V]"]
    PyoSequence --> PyoMutableSequence["PyoMutableSequence[T]"]
    PyoSequence ==> Seq["Seq[T]"]
    PyoMutableSequence ==> Vec["Vec[T]"]
    PyoSet ==> Set["Set[T]"] & PyoKeysView["PyoKeysView[K]"] & PyoItemsView["PyoItemsView[K,V]"]
    PyoMappingView ==> PyoKeysView & PyoValuesView["PyoValuesView[V]"] & PyoItemsView
    PyoMapping ==> PyoMutableMapping["PyoMutableMapping[K,V]"]
    PyoMutableMapping ==> Dict["Dict[K,V]"]
    Result ==> Ok["Ok[T]"] & Err["Err[E]"]
    Option ==> Some["Some[T]"] & NONE["NONE"]
    Set ==> SetMut["SetMut[T]"]
    Seq ==> Vec

    style Pipeable stroke:#9C27B0,stroke-width:2px
    style PyoIterable stroke:#00C853,stroke-width:2px
    style Result stroke:#E53935,stroke-width:2px
    style Option stroke:#FDD835,stroke-width:2px
    style Checkable stroke:#9C27B0,stroke-width:2px
    style PyoIterator stroke:#00C853,stroke-width:2px
    style PyoCollection stroke:#00C853,stroke-width:2px
    style Iter stroke:#1E88E5,stroke-width:2px
    style PyoSequence stroke:#00C853,stroke-width:2px
    style PyoSet stroke:#00C853,stroke-width:2px
    style PyoMappingView stroke:#00C853,stroke-width:2px
    style PyoMapping stroke:#00C853,stroke-width:2px
    style PyoMutableSequence stroke:#00C853,stroke-width:2px
    style Seq stroke:#1E88E5,stroke-width:2px
    style Vec stroke:#1E88E5,stroke-width:2px
    style Set stroke:#1E88E5,stroke-width:2px
    style PyoKeysView stroke:#1E88E5,stroke-width:2px
    style PyoItemsView stroke:#1E88E5,stroke-width:2px
    style SetMut stroke:#1E88E5,stroke-width:2px
    style PyoValuesView stroke:#1E88E5,stroke-width:2px
    style PyoMutableMapping stroke:#00C853,stroke-width:2px
    style Dict stroke:#1E88E5,stroke-width:2px
    style Ok stroke:#E53935,stroke-width:2px
    style Err stroke:#E53935,stroke-width:2px
    style Some stroke:#FDD835,stroke-width:2px
    style NONE stroke:#FDD835,stroke-width:2px
    linkStyle 0 stroke:#9C27B0,stroke-width:2px,fill:none
    linkStyle 1 stroke:#9C27B0,stroke-width:2px,fill:none
    linkStyle 2 stroke:#AA00FF,stroke-width:2px,fill:none
    linkStyle 3 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 4 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 5 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 6 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 7 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 8 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 9 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 10 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 11 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 12 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 13 stroke:#00C853,fill:none,stroke-width:2px
    linkStyle 14 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 15 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 16 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 17 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 18 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 19 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 20 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 21 stroke:#00C853,stroke-width:2px,fill:none
    linkStyle 22 stroke:#D50000,stroke-width:2px,fill:none
    linkStyle 23 stroke:#D50000,stroke-width:2px,fill:none
    linkStyle 24 stroke:#FFD600,stroke-width:2px,fill:none
    linkStyle 25 stroke:#FFD600,stroke-width:2px,fill:none
    linkStyle 26 stroke:#2962FF,fill:none,stroke-width:2px
    linkStyle 27 stroke:#2962FF,fill:none,stroke-width:2px

Type Categories

Pyochain types can be broadly categorized into 4 groups:

Fluent mixins
Abstract collection protocols
Concrete collections & iterators
Option & Result types

See the sections below for an overview of each category, and the types they contain.

Fluent mixins

Fluent mixins are standalone classes that can be subclassed to enable functional method composition.

They depend only on Self for their implementation, making them universally applicable.

Mixin	Purpose	Main Capabilities	Inherited by
`Pipeable`	Functional chaining	`into()`, `inspect()` for fluent method composition	All pyochain objects
`Checkable`	Conditional operations	`then()`, `ok_or()`, `err_or()` for wrapping in `Option`/`Result`	All pyochain iterables + `Option` + `Result`

Abstract Collection protocols

Abstract collection protocols form a hierarchy that mirrors Python's collections.abc module.

Each protocol extends the corresponding one from collections.abc, inheriting its interface while adding pyochain-specific functionality.

Concrete types must implement the required methods (dunders) to satisfy the protocol contract.

ABC	Extends	Inherits from `collections.abc`	Required Methods (for concrete types)	Concrete Types
`PyoIterable[T]`	`Pipeable`, `Checkable`	`Iterable[T]`	`__iter__`	All pyochain collections
`PyoIterator[T]`	`PyoIterable[T]`	`Iterator[T]`	`__iter__`, `__next__`	`Iter[T]`
`PyoCollection[T]`	`PyoIterable[T]`	`Collection[T]`	`__contains__`, `__iter__`, `__len__`	All eager collections
`PyoSequence[T]`	`PyoCollection[T]`	`Sequence[T]`	`__getitem__`, `__len__`	`Seq[T]`
`PyoMutableSequence[T]`	`PyoSequence[T]`	`MutableSequence[T]`	`__setitem__`, `__delitem__`, `insert`	`Vec[T]`
`PyoSet[T]`	`PyoCollection[T]`	`Set[T]`	`__contains__`, `__iter__`, `__len__`	`Set[T]`, `PyoKeysView[K]`, `PyoItemsView[K,V]`
`PyoMappingView[T]`	`PyoCollection[T]`	`MappingView`	`__len__`	All mapping views
`PyoMapping[K, V]`	`PyoCollection[K]`	`Mapping[K, V]`	`__getitem__`, `__iter__`, `__len__`	`Dict[K,V]` (read-only interface)
`PyoMutableMapping[K, V]`	`PyoMapping[K, V]`	`MutableMapping[K, V]`	`__setitem__`, `__delitem__`	`Dict[K,V]`

Concrete Collections & Iterators

Pyochain provides concrete collection types that implement the abstract protocols described above.

All collections can be created from any object implementing Python's Iterable protocol.

Since these types fully implement their corresponding collections.abc protocols , they can act as drop-in replacements for their Python standard library counterparts.

Concrete Collection Types

Type	Underlying Structure	Implements `collections.abc`	Ordered	Uniqueness	Mutability
`Iter[T]`	`Iterator[T]`	`Iterator[T]`	N/A	N/A	N/A
`Seq[T]`	`tuple[T]`	`Sequence[T]`	Yes	No	No
`Vec[T]`	`list[T]`	`MutableSequence[T]`	Yes	No	Yes
`Set[T]`	`frozenset[T]`	`Set[T]`	No	Yes	No
`SetMut[T]`	`set[T]`	`MutableSet[T]`	No	Yes	Yes
`Dict[K,V]`	`dict[K, V]`	`MutableMapping[K, V]`	Yes	Keys	Yes
`PyoKeysView[K]`	`KeysView[K]`	`KeysView[K]`, `Set[K]`	No	Yes	No
`PyoValuesView[V]`	`ValuesView[V]`	`ValuesView[V]`	No	No	No
`PyoItemsView[K,V]`	`ItemsView[K,V]`	`ItemsView[K,V]`, `Set[tuple[K,V]]`	No	Yes	No

Option & Result Types

Pyochain provides two fundamental types for explicit handling of nullable values and errors: Option[T] and Result[T, E].

Option

Option[T] represents values that may or may not be present, serving as a type-safe alternative to using None.

Result

Result[T, E] represents the outcome of operations that can succeed or fail, promoting explicit error handling without exceptions.

A Result[T, E] is either Ok(value) for successful operations, or Err(error) for failures.

Using Result as a return type clearly signals to callers that error handling is required.

Conversion & Interoperability Map

The following graph illustrates all the built-in ways to convert between types in Pyochain.

Types are grouped by category.
Arrows color and direction represent conversion paths.
Arrow labels represent methods.

---
config:
  layout: elk
---
flowchart TB
 subgraph Collections["📦 Collections"]
    direction LR
        Seq["<b>Seq[T]</b><br>immutable<br>tuple"]
        Vec["<b>Vec[T]</b><br>mutable<br>list"]
        Set["<b>Set[T]</b><br>immutable<br>frozenset"]
        SetMut["<b>SetMut[T]</b><br>mutable<br>set"]
  end
 subgraph Lazy["⛓️ Lazy"]
    direction LR
        Iter["<b>Iter[T]</b><br>lazy iterator<br>Iterator"]
  end
 subgraph DictGroup["🔑 Dictionary"]
    direction LR
        Dict["<b>Dict[K,V]</b><br>mutable<br>dict"]
  end
 subgraph OptionGroup["🎁 Option Types"]
    direction LR
        Option["<b>Option[T]</b>"]
        Some["<b>Some[T]</b>"]
        NONE["<b>NONE</b>"]
  end
 subgraph ResultGroup["✅ Result Types"]
    direction LR
        Result["<b>Result[T,E]</b>"]
        Ok["<b>Ok[T]</b>"]
        Err["<b>Err[E]</b>"]
  end
 subgraph External["🌐 External Types"]
    direction LR
        AnyType["<b>Any Type</b><br>via .into(func)"]
  end
    Option -.-> Some & NONE
    Result -.-> Ok & Err
    Collections -- ".iter()" --> Lazy
    Lazy -- ".collect()" --> Collections
    Lazy -- ".collect(Dict)" --> DictGroup
    DictGroup -- ".iter() → Item[K,V]<br>.keys_iter() → K<br>.values_iter() → V" --> Lazy
    OptionGroup -- ".iter()" --> Lazy
    ResultGroup -- ".iter()" --> Lazy
    DictGroup -- ".get_item(key)<br>.insert(key, val)<br>.remove(key)" --> OptionGroup
    DictGroup -- ".try_insert(key, val)" --> ResultGroup
    Collections -- ".then(func)<br>.then_some()" --> OptionGroup
    Lazy -- ".then(func)<br>.then_some()" --> OptionGroup
    DictGroup -- ".then(func)<br>.then_some()" --> OptionGroup
    Collections -- ".ok_or(err)<br>.ok_or_else(func)" --> ResultGroup
    Lazy -- ".ok_or(err)<br>.ok_or_else(func)" --> ResultGroup
    DictGroup -- ".ok_or(err)<br>.ok_or_else(func)" --> ResultGroup
    OptionGroup -- ".ok_or(err)<br>.ok_or_else(func)" --> ResultGroup
    ResultGroup -- ".ok()<br>.err()" --> OptionGroup
    OptionGroup L_OptionGroup_ResultGroup_2@<-- ".transpose()" --> ResultGroup
    Collections -- ".into(func)" --> External
    Lazy -- ".into(func)" --> External
    DictGroup -- ".into(func)" --> External
    OptionGroup -- ".into(func)" --> External
    ResultGroup -- ".into(func)" --> External

     Seq:::collectionsStyle
     Vec:::collectionsStyle
     Set:::collectionsStyle
     SetMut:::collectionsStyle
     Iter:::iterStyle
     Dict:::dictStyle
     Option:::optionStyle
     Some:::optionStyle
     NONE:::optionStyle
     Result:::resultStyle
     Ok:::resultStyle
     Err:::resultStyle
     AnyType:::externalStyle
     Collections:::collectionsStyle
     OptionGroup:::optionStyle
     ResultGroup:::resultStyle
    classDef collectionsStyle fill:#1e88e5,stroke:#0d47a1,stroke-width:2px,color:#fff
    classDef iterStyle fill:#43a047,stroke:#1b5e20,stroke-width:2px,color:#fff
    classDef dictStyle fill:#fb8c00,stroke:#e65100,stroke-width:2px,color:#fff
    classDef optionStyle fill:#fdd835,stroke:#f57f17,stroke-width:2px,color:#000
    classDef resultStyle fill:#e53935,stroke:#b71c1c,stroke-width:2px,color:#fff
    classDef externalStyle fill:#9e9e9e,stroke:#424242,stroke-width:2px,color:#fff
    style Seq color:none
    style Vec color:none
    style Set color:none
    style SetMut color:none
    style Dict fill:#FF6D00,color:none,stroke:#FF6D00
    style Option color:#FFFFFF,fill:transparent,stroke:#FFD600
    style Some color:#FFFFFF,fill:transparent,stroke:#FFD600
    style NONE color:#FFFFFF,fill:transparent,stroke:#FFD600
    style Result fill:#D50000
    style Ok fill:#D50000
    style Err fill:#D50000
    style Collections fill:#000000,color:none,stroke:#2962FF
    style Lazy fill:#000000,stroke:#00C853
    style DictGroup fill:#000000,color:none,stroke:#FF6D00
    style OptionGroup fill:#000000,color:#FFFFFF,stroke:#FFD600
    style ResultGroup fill:#000000,stroke:#D50000
    style External fill:#000000
    linkStyle 0 stroke:#666,stroke-width:1px,stroke-dasharray:3,fill:none
    linkStyle 1 stroke:#666,stroke-width:1px,stroke-dasharray:3,fill:none
    linkStyle 2 stroke:#666,stroke-width:1px,stroke-dasharray:3,fill:none
    linkStyle 3 stroke:#666,stroke-width:1px,stroke-dasharray:3,fill:none
    linkStyle 4 stroke:#1e88e5,stroke-width:2.5px,fill:none
    linkStyle 5 stroke:#43a047,stroke-width:2.5px,fill:none
    linkStyle 6 stroke:#43a047,stroke-width:2.5px,fill:none
    linkStyle 7 stroke:#fb8c00,stroke-width:2.5px,fill:none
    linkStyle 8 stroke:#fdd835,stroke-width:2.5px,fill:none
    linkStyle 9 stroke:#e53935,stroke-width:2.5px,fill:none
    linkStyle 10 stroke:#fb8c00,stroke-width:2.5px,fill:none
    linkStyle 11 stroke:#fb8c00,stroke-width:2.5px,fill:none
    linkStyle 12 stroke:#1e88e5,stroke-width:2.5px,fill:none
    linkStyle 13 stroke:#43a047,stroke-width:2.5px,fill:none
    linkStyle 14 stroke:#fb8c00,stroke-width:2.5px,fill:none
    linkStyle 15 stroke:#1e88e5,stroke-width:2.5px,fill:none
    linkStyle 16 stroke:#43a047,stroke-width:2.5px,fill:none
    linkStyle 17 stroke:#fb8c00,stroke-width:2.5px,fill:none
    linkStyle 18 stroke:#fdd835,stroke-width:2.5px,fill:none
    linkStyle 19 stroke:#e53935,stroke-width:2.5px,fill:none
    linkStyle 20 stroke:#9c27b0,stroke-width:2.5px,fill:none
    linkStyle 21 stroke:#1e88e5,stroke-width:2.5px,fill:none
    linkStyle 22 stroke:#43a047,stroke-width:2.5px,fill:none
    linkStyle 23 stroke:#fb8c00,stroke-width:2.5px,fill:none
    linkStyle 24 stroke:#fdd835,stroke-width:2.5px,fill:none
    linkStyle 25 stroke:#e53935,stroke-width:2.5px,fill:none

    L_OptionGroup_ResultGroup_2@{ animation: none }