# ebonnal/streamable architecture

> Architecture diagram of the GitHub repository ebonnal/streamable, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ebonnal/streamable
- Repository: https://github.com/ebonnal/streamable

## Overview

streamable is a dependency-free Python library for lazy, fluent synchronous and asynchronous iterable streams. The principal workflow wraps an iterable or iterable-producing callable, builds a chain of operations, traverses that chain through a sync or async visitor, and yields elements as the caller iterates. Operation coverage includes transformation, filtering, grouping, flattening, throttling, buffering, progress observation, and exception handling. The excerpts show async dispatch and both iterator engines; the synchronous visitor and some internal wiring are supported by the SOURCE INDEX and README, not inspected source excerpts.

Main entry points: [`streamable/_stream.py`](https://github.com/ebonnal/streamable/blob/main/streamable/_stream.py) (Lazy stream chain), [`streamable/_afunctions.py`](https://github.com/ebonnal/streamable/blob/main/streamable/_afunctions.py) (Async operation adapters), [`streamable/visitors/_iter.py`](https://github.com/ebonnal/streamable/blob/main/streamable/visitors/_iter.py) (Sync visitor), [`streamable/visitors/_aiter.py`](https://github.com/ebonnal/streamable/blob/main/streamable/visitors/_aiter.py) (Async visitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Stream API"]
  node_public["Public API<br/>[__init__.py]"]
  node_stream["Lazy stream chain<br/>[_stream.py]"]
end

subgraph group_dispatch["Iteration Dispatch"]
  node_sync_dispatch["Sync visitor<br/>[_iter.py]"]
  node_async_dispatch["Async visitor<br/>[_aiter.py]"]
end

subgraph group_operations["Stream Operations"]
  node_sync_ops["Sync operation adapters<br/>[_functions.py]"]
  node_async_ops["Async operation adapters<br/>[_afunctions.py]"]
  node_sync_engine["Sync iterators<br/>[_iterators.py]"]
  node_async_engine["Async iterators<br/>[_aiterators.py]"]
end

subgraph group_runtime["Runtime Support"]
  node_iter_adapt["Iterator adapters<br/>[_iter.py]"]
  node_async_helpers["Async helpers<br/>[_async.py]"]
  node_func_helpers["Function adapters<br/>[_func.py]"]
  node_validation["Argument validation<br/>[_validation.py]"]
  node_observation["Progress records<br/>[_observation.py]"]
  node_logging["Log formatting<br/>[_logging.py]"]
  node_context["Context management<br/>[_context.py]"]
end

node_caller(("Stream consumer"))
node_source(("Iterable source"))

node_caller -->|"imports"| node_public
node_source -->|"wraps source"| node_stream
node_public -->|"exports"| node_stream
node_caller -->|"iterates"| node_stream
node_stream -->|"accepts visitor"| node_sync_dispatch
node_stream -->|"accepts visitor"| node_async_dispatch
node_sync_dispatch -->|"dispatches operations"| node_sync_ops
node_async_dispatch -->|"dispatches operations"| node_async_ops
node_sync_ops -->|"builds iterators"| node_sync_engine
node_async_ops -->|"builds iterators"| node_async_engine
node_sync_dispatch -->|"adapts sources"| node_iter_adapt
node_async_dispatch -->|"adapts sources"| node_iter_adapt
node_async_ops -->|"normalizes callbacks"| node_func_helpers
node_async_ops -->|"uses async types"| node_async_helpers
node_async_engine -->|"uses iterator protocols"| node_iter_adapt
node_stream -->|"validates options"| node_validation
node_stream -->|"configures progress"| node_observation
node_observation -->|"formats records"| node_logging
node_async_engine -.->|"closes iterators"| node_context
node_caller -->|"receives elements"| node_sync_engine

click node_public "https://github.com/ebonnal/streamable/blob/main/streamable/__init__.py"
click node_stream "https://github.com/ebonnal/streamable/blob/main/streamable/_stream.py"
click node_sync_dispatch "https://github.com/ebonnal/streamable/blob/main/streamable/visitors/_iter.py"
click node_async_dispatch "https://github.com/ebonnal/streamable/blob/main/streamable/visitors/_aiter.py"
click node_sync_ops "https://github.com/ebonnal/streamable/blob/main/streamable/_functions.py"
click node_async_ops "https://github.com/ebonnal/streamable/blob/main/streamable/_afunctions.py"
click node_sync_engine "https://github.com/ebonnal/streamable/blob/main/streamable/_iterators.py"
click node_async_engine "https://github.com/ebonnal/streamable/blob/main/streamable/_aiterators.py"
click node_iter_adapt "https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_iter.py"
click node_async_helpers "https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_async.py"
click node_func_helpers "https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_func.py"
click node_validation "https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_validation.py"
click node_observation "https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_observation.py"
click node_logging "https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_logging.py"
click node_context "https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_context.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public,node_stream toneBlue
class node_sync_dispatch,node_async_dispatch toneAmber
class node_sync_ops,node_async_ops,node_sync_engine,node_async_engine toneMint
class node_iter_adapt,node_async_helpers,node_func_helpers,node_validation,node_observation,node_logging,node_context toneRose
class node_caller,node_source toneIndigo
```

## Components

### Stream API

- [Public API](https://github.com/ebonnal/streamable/blob/main/streamable/__init__.py): `streamable/__init__.py`
- [Lazy stream chain](https://github.com/ebonnal/streamable/blob/main/streamable/_stream.py): `streamable/_stream.py`

### Iteration Dispatch

- [Sync visitor](https://github.com/ebonnal/streamable/blob/main/streamable/visitors/_iter.py): `streamable/visitors/_iter.py`
- [Async visitor](https://github.com/ebonnal/streamable/blob/main/streamable/visitors/_aiter.py): `streamable/visitors/_aiter.py`

### Stream Operations

- [Sync operation adapters](https://github.com/ebonnal/streamable/blob/main/streamable/_functions.py): `streamable/_functions.py`
- [Async operation adapters](https://github.com/ebonnal/streamable/blob/main/streamable/_afunctions.py): `streamable/_afunctions.py`
- [Sync iterators](https://github.com/ebonnal/streamable/blob/main/streamable/_iterators.py): `streamable/_iterators.py`
- [Async iterators](https://github.com/ebonnal/streamable/blob/main/streamable/_aiterators.py): `streamable/_aiterators.py`

### Runtime Support

- [Iterator adapters](https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_iter.py): `streamable/_tools/_iter.py`
- [Async helpers](https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_async.py): `streamable/_tools/_async.py`
- [Function adapters](https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_func.py): `streamable/_tools/_func.py`
- [Argument validation](https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_validation.py): `streamable/_tools/_validation.py`
- [Progress records](https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_observation.py): `streamable/_tools/_observation.py`
- [Log formatting](https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_logging.py): `streamable/_tools/_logging.py`
- [Context management](https://github.com/ebonnal/streamable/blob/main/streamable/_tools/_context.py): `streamable/_tools/_context.py`

### Other components

- **Stream consumer**
- **Iterable source**

## Connections

- Stream consumer → Public API: imports (evidence: `README.md`)
- Iterable source → Lazy stream chain: wraps source (evidence: `README.md`)
- Public API → Lazy stream chain: exports (evidence: `streamable/__init__.py`)
- Stream consumer → Lazy stream chain: iterates (evidence: `README.md`)
- Lazy stream chain → Sync visitor: accepts visitor (evidence: `streamable/_stream.py`)
- Lazy stream chain → Async visitor: accepts visitor (evidence: `streamable/_stream.py`)
- Sync visitor → Sync operation adapters: dispatches operations (evidence: `streamable/visitors/_iter.py`)
- Async visitor → Async operation adapters: dispatches operations (evidence: `streamable/visitors/_aiter.py`)
- Sync operation adapters → Sync iterators: builds iterators (evidence: `streamable/_functions.py`)
- Async operation adapters → Async iterators: builds iterators (evidence: `streamable/_afunctions.py`)
- Sync visitor → Iterator adapters: adapts sources (evidence: `streamable/visitors/_iter.py`)
- Async visitor → Iterator adapters: adapts sources (evidence: `streamable/visitors/_aiter.py`)
- Async operation adapters → Function adapters: normalizes callbacks (evidence: `streamable/_afunctions.py`)
- Async operation adapters → Async helpers: uses async types (evidence: `streamable/_afunctions.py`)
- Async iterators → Iterator adapters: uses iterator protocols (evidence: `streamable/_aiterators.py`)
- Lazy stream chain → Argument validation: validates options (evidence: `streamable/_stream.py`)
- Lazy stream chain → Progress records: configures progress (evidence: `streamable/_stream.py`)
- Progress records → Log formatting: formats records (evidence: `streamable/_tools/_observation.py`)
- Async iterators → Context management: closes iterators (evidence: `streamable/_aiterators.py`)
- Stream consumer → Sync iterators: receives elements (evidence: `README.md`)
