# Flokkit Flow
A type-safe, async-first flow-based programming (FBP) framework for Python with zero dependencies.
## Features
- 🔒 **Type-safe** - Full type safety across the entire flow graph
- ⚡ **Async-first** - Built on asyncio with automatic sync function adaptation
- 🚦 **Backpressure** - Bounded queues with configurable strategies
- 🔄 **DAG Safety** - Automatic cycle detection prevents deadlocks
- 📦 **Zero Dependencies** - Pure Python, no external packages required
- 🔌 **Lifecycle Hooks** - Proper resource management with init/cleanup
- 🏭 **Flexible Patterns** - Support for both pipeline and server patterns
- 🎯 **Middleware System** - Extensible processing pipeline with logging, metrics, throttling, and retry support
## Installation
```bash
pip install flokkit-flow
```
## Documentation
Full documentation is available at: https://flokkit.gitlab.io/flow/
### Quick Install
```bash
# Using uv (replace {project_id} with actual ID)
# From source
uv pip install git+https://gitlab.com/flokkit/flow.git
```
### For Development
```bash
# Clone and install in editable mode
git clone https://gitlab.com/flokkit/flow.git
cd flow
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```
## Quick Start
```python
from flow import flow
# Build a simple pipeline
async def main():
builder = flow("My Pipeline")
def generate_numbers():
return 42
def double(x):
return x * 2
def print_result(x):
print(f"Result: {x}")
# Connect the nodes
(builder
.source(generate_numbers, int)
.transform(double, int)
.to(print_result))
# Run the pipeline
await builder.execute(duration=1.0)
# Run it
import asyncio
asyncio.run(main())
```
### Using Middleware
```python
from flow import flow, LoggingMiddleware, MetricsMiddleware
async def main():
# Create middleware instances
logger = LoggingMiddleware()
metrics = MetricsMiddleware()
# Build pipeline with middleware
builder = flow("Monitored Pipeline")
results = []
await (
builder
.with_middleware(logger, metrics) # Add middleware to all nodes
.source(lambda: [1, 2, 3, 4, 5], int)
.filter(lambda x: x % 2 == 0)
.transform(lambda x: x ** 2, int)
.to(results.append)
.execute(duration=1.0)
)
print(f"Results: {results}")
print(f"Metrics: {metrics.get_metrics()}")
asyncio.run(main())
```
## Examples
See the `examples/` directory for comprehensive examples:
- Basic flows and transformations
- Backpressure and queue strategies
- Split/merge patterns
- Async I/O and blocking operations
- Pipeline vs server patterns
- Lifecycle management
## Development
This project uses [just](https://github.com/casey/just) for development commands and [uv](https://github.com/astral-sh/uv) for fast dependency management.
```bash
# Install tools
curl -LsSf https://astral.sh/uv/install.sh | sh # Install uv
brew install just # Install just (macOS)
# Set up development environment
uv venv # Create virtual environment
source .venv/bin/activate # Activate it
just install-dev # Install all dev dependencies
# Development commands
just # List all commands
just test # Run tests
just typecheck # Run type checker
just check # Run all checks
just example 1 # Run specific example
```
### Common Commands
```bash
# Development workflow
just dev # Run checks and watch for changes
just test # Run tests (auto-detects pytest)
just typecheck # Run basedpyright
just check # Run all checks
# Examples
just example # List examples
just example 5 # Run example 5
just examples # Run all examples
# Utilities
just clean # Clean generated files
just stats # Show project statistics
```
## Documentation
### Building Documentation Locally
Flowy uses Sphinx for documentation with the modern Python documentation toolchain:
```bash
# Install documentation dependencies
just install-docs
# Build documentation
just docs-build
# Serve with auto-reload for development
just docs-serve
# Open in browser
just docs-open
```
### Documentation Structure
- **Getting Started**: Installation, quickstart, and core concepts
- **User Guide**: In-depth guides for common use cases
- **API Reference**: Complete API documentation with examples
- **Examples**: Practical examples with explanations
### Online Documentation
Documentation is automatically built and hosted on [Read the Docs](https://flowy.readthedocs.io) (when published).
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "flokkit-flow",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "flow-based-programming, fbp, dataflow, async, pipeline",
"author": null,
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/92/30/08ccf9e60780a7a1ed798eb7ba2dfdb1f3d3a009b2b1e97e63426acee9cb/flokkit_flow-0.2.0.tar.gz",
"platform": null,
"description": "# Flokkit Flow\n\nA type-safe, async-first flow-based programming (FBP) framework for Python with zero dependencies.\n\n## Features\n\n- \ud83d\udd12 **Type-safe** - Full type safety across the entire flow graph\n- \u26a1 **Async-first** - Built on asyncio with automatic sync function adaptation \n- \ud83d\udea6 **Backpressure** - Bounded queues with configurable strategies\n- \ud83d\udd04 **DAG Safety** - Automatic cycle detection prevents deadlocks\n- \ud83d\udce6 **Zero Dependencies** - Pure Python, no external packages required\n- \ud83d\udd0c **Lifecycle Hooks** - Proper resource management with init/cleanup\n- \ud83c\udfed **Flexible Patterns** - Support for both pipeline and server patterns\n- \ud83c\udfaf **Middleware System** - Extensible processing pipeline with logging, metrics, throttling, and retry support\n\n## Installation\n\n```bash\npip install flokkit-flow\n```\n\n## Documentation\n\nFull documentation is available at: https://flokkit.gitlab.io/flow/\n\n### Quick Install\n\n```bash\n# Using uv (replace {project_id} with actual ID)\n# From source\nuv pip install git+https://gitlab.com/flokkit/flow.git\n```\n\n### For Development\n\n```bash\n# Clone and install in editable mode\ngit clone https://gitlab.com/flokkit/flow.git\ncd flow\nuv venv\nsource .venv/bin/activate\nuv pip install -e \".[dev]\"\n```\n\n## Quick Start\n\n```python\nfrom flow import flow\n\n# Build a simple pipeline\nasync def main():\n builder = flow(\"My Pipeline\")\n \n def generate_numbers():\n return 42\n \n def double(x):\n return x * 2\n \n def print_result(x):\n print(f\"Result: {x}\")\n \n # Connect the nodes\n (builder\n .source(generate_numbers, int)\n .transform(double, int)\n .to(print_result))\n \n # Run the pipeline\n await builder.execute(duration=1.0)\n\n# Run it\nimport asyncio\nasyncio.run(main())\n```\n\n### Using Middleware\n\n```python\nfrom flow import flow, LoggingMiddleware, MetricsMiddleware\n\nasync def main():\n # Create middleware instances\n logger = LoggingMiddleware()\n metrics = MetricsMiddleware()\n \n # Build pipeline with middleware\n builder = flow(\"Monitored Pipeline\")\n \n results = []\n await (\n builder\n .with_middleware(logger, metrics) # Add middleware to all nodes\n .source(lambda: [1, 2, 3, 4, 5], int)\n .filter(lambda x: x % 2 == 0)\n .transform(lambda x: x ** 2, int)\n .to(results.append)\n .execute(duration=1.0)\n )\n \n print(f\"Results: {results}\")\n print(f\"Metrics: {metrics.get_metrics()}\")\n\nasyncio.run(main())\n```\n\n## Examples\n\nSee the `examples/` directory for comprehensive examples:\n- Basic flows and transformations\n- Backpressure and queue strategies\n- Split/merge patterns\n- Async I/O and blocking operations\n- Pipeline vs server patterns\n- Lifecycle management\n\n## Development\n\nThis project uses [just](https://github.com/casey/just) for development commands and [uv](https://github.com/astral-sh/uv) for fast dependency management.\n\n```bash\n# Install tools\ncurl -LsSf https://astral.sh/uv/install.sh | sh # Install uv\nbrew install just # Install just (macOS)\n\n# Set up development environment\nuv venv # Create virtual environment\nsource .venv/bin/activate # Activate it\njust install-dev # Install all dev dependencies\n\n# Development commands\njust # List all commands\njust test # Run tests\njust typecheck # Run type checker\njust check # Run all checks\njust example 1 # Run specific example\n```\n\n### Common Commands\n\n```bash\n# Development workflow\njust dev # Run checks and watch for changes\njust test # Run tests (auto-detects pytest)\njust typecheck # Run basedpyright\njust check # Run all checks\n\n# Examples\njust example # List examples\njust example 5 # Run example 5\njust examples # Run all examples\n\n# Utilities\njust clean # Clean generated files\njust stats # Show project statistics\n```\n\n## Documentation\n\n### Building Documentation Locally\n\nFlowy uses Sphinx for documentation with the modern Python documentation toolchain:\n\n```bash\n# Install documentation dependencies\njust install-docs\n\n# Build documentation\njust docs-build\n\n# Serve with auto-reload for development\njust docs-serve\n\n# Open in browser\njust docs-open\n```\n\n### Documentation Structure\n\n- **Getting Started**: Installation, quickstart, and core concepts\n- **User Guide**: In-depth guides for common use cases\n- **API Reference**: Complete API documentation with examples\n- **Examples**: Practical examples with explanations\n\n### Online Documentation\n\nDocumentation is automatically built and hosted on [Read the Docs](https://flowy.readthedocs.io) (when published).\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A type-safe, async-first flow-based programming framework for Python",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://flokkit.gitlab.io/flow/",
"Homepage": "https://gitlab.com/flokkit/flow",
"Issues": "https://gitlab.com/flokkit/flow/-/issues",
"Repository": "https://gitlab.com/flokkit/flow"
},
"split_keywords": [
"flow-based-programming",
" fbp",
" dataflow",
" async",
" pipeline"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf3f7df5b6737ce82fa6c79abfc1ad75467d99d42e0c6f4ee8d62f3d6098e2db",
"md5": "737c53a771980c8d281366bdc2541bcf",
"sha256": "b7e9cfa2ec94011fbce67d054178a6948a5acc2383a4ff3934cde67df0997a27"
},
"downloads": -1,
"filename": "flokkit_flow-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "737c53a771980c8d281366bdc2541bcf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23039,
"upload_time": "2025-07-22T11:26:12",
"upload_time_iso_8601": "2025-07-22T11:26:12.650677Z",
"url": "https://files.pythonhosted.org/packages/cf/3f/7df5b6737ce82fa6c79abfc1ad75467d99d42e0c6f4ee8d62f3d6098e2db/flokkit_flow-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "923008ccf9e60780a7a1ed798eb7ba2dfdb1f3d3a009b2b1e97e63426acee9cb",
"md5": "e53bd1df027d51b69054ca4ef8da624f",
"sha256": "151904ad37515ef237d4b055ba6900fb8efed024554f32f1b73033a1b31d83d4"
},
"downloads": -1,
"filename": "flokkit_flow-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e53bd1df027d51b69054ca4ef8da624f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 34108,
"upload_time": "2025-07-22T11:26:13",
"upload_time_iso_8601": "2025-07-22T11:26:13.485555Z",
"url": "https://files.pythonhosted.org/packages/92/30/08ccf9e60780a7a1ed798eb7ba2dfdb1f3d3a009b2b1e97e63426acee9cb/flokkit_flow-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 11:26:13",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "flokkit",
"gitlab_project": "flow",
"lcname": "flokkit-flow"
}
JSON