Metadata-Version: 2.4
Name: flowkitx
Version: 1.0.1
Summary: Fluent async workflows with lazy execution for Python
Author-email: FlowKit Contributors <contributors@flowkit.dev>
Maintainer-email: FlowKit Contributors <contributors@flowkit.dev>
License-Expression: MIT
Project-URL: Homepage, https://github.com/flowkit/flowkit
Project-URL: Documentation, https://flowkit.readthedocs.io
Project-URL: Repository, https://github.com/flowkit/flowkit
Project-URL: Bug Tracker, https://github.com/flowkit/flowkit/issues
Keywords: async,workflow,simplification,http,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: AsyncIO
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.0
Requires-Dist: anyio>=4.0.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.104.0; extra == "fastapi"
Provides-Extra: django
Requires-Dist: django>=4.2.0; extra == "django"
Provides-Extra: flask
Requires-Dist: flask>=2.3.0; extra == "flask"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: hypothesis>=6.80.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Dynamic: license-file

# 🚀 **FlowKit - Simplify Async Workflows**

[![PyPI version](https://badge.fury.io/py/flowkit-async.svg)](https://badge.fury.io/py/flowkit-async)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/flowkit/flowkit/actions/workflows/publish.yml/badge.svg)](https://github.com/flowkit/flowkit/actions)

> **FlowKit provides fluent async workflows with lazy execution and minimal boilerplate.**

## ⚡ **Why FlowKit?**

**Before (Traditional Async):**
```python
async def fetch_user_data(user_id):
    async with aiohttp.ClientSession() as session:
        async with session.get(f"https://api.example.com/users/{user_id}") as response:
            user = await response.json()
            async with session.get("https://api.example.com/posts", params={"userId": user_id}) as posts_response:
                posts = await posts_response.json()
                return {"user": user, "posts": posts}
```

**After (FlowKit):**
```python
@flowkit.simple
def fetch_user_data(user_id):
    user = flowkit.get(f"https://api.example.com/users/{user_id}").json()
    posts = flowkit.get("https://api.example.com/posts", params={"userId": user_id}).json()
    return {"user": user, "posts": posts}
```

## 🎯 **Key Features**

- 🔗 **Fluent API** - Chain operations with `.pipe()` method
- 🛡️ **Type Safe** - Full IDE support and type hints
- 🚀 **Modern Foundation** - Built on battle-tested httpx
- 🔧 **Framework Ready** - FastAPI, Django, Flask examples
- 📦 **Simple Installation** - `pip install flowkit-async`

## 📦 **Installation**

```bash
pip install flowkit-async
```

## 🔧 **How FlowKit Works**

FlowKit provides lazy async pipelines - operations are queued and executed when awaited.

```python
import flowkit

# FlowKit operations return awaitable Flow objects
user_flow = flowkit.get("https://api.example.com/users/1")
posts_flow = flowkit.get("https://api.example.com/posts")

# Execute both operations
user = await user_flow.json()
posts = await posts_flow.json()
```

### **Core Concept: Flow Objects**
Flow objects are awaitable pipelines that:
- Chain operations without immediate execution
- Execute when awaited in the current event loop
- Enable fluent, readable async patterns

**This is structured async workflows, not sync-to-async magic.**

## 🔧 **How FlowKit Works**

FlowKit provides lazy async pipelines.
API calls return awaitable Flow objects that record operations
and execute asynchronously when awaited.

FlowKit does NOT:
- convert blocking code into async
- use threads or greenlets
- bypass the event loop

This is structured async composition, not async magic.

## 🏆 **Real-World Examples**

### **Data Processing Pipeline**
```python
@flowkit.simple
def fetch_user_data(user_id: int):
    """Fetch and process user data."""
    return (flowkit.get(f"https://jsonplaceholder.typicode.com/users/{user_id}")
              .json()
              .pipe(lambda user: {**user, "processed": True}))
```

**Note:** `@flowkit.simple` is intended for synchronous functions.
If used on async functions, it acts as a pass-through wrapper.

### **Concurrent Operations**
```python
@flowkit.simple
def fetch_dashboard():
    """Fetch multiple data sources concurrently."""
    users = flowkit.get("https://jsonplaceholder.typicode.com/users").json()
    posts = flowkit.get("https://jsonplaceholder.typicode.com/posts").json()
    comments = flowkit.get("https://jsonplaceholder.typicode.com/comments").json()
    
    # These execute concurrently when awaited
    return {"users": users, "posts": posts, "comments": comments}
```

## 🛠 **When to Use FlowKit**

FlowKit is ideal for:
- API-heavy applications with multiple calls
- Data pipelines and processing workflows
- Teams wanting consistent async patterns
- Rapid prototyping with clean syntax

## ⚠️ **Important Notes**

FlowKit does NOT:
- Block the event loop or use thread pools
- Make synchronous code magically non-blocking  
- Replace understanding of asyncio fundamentals
- Work with CPU-bound operations

Always use async/await with CPU-intensive tasks.

## 🆚 **How FlowKit Compares**

| Feature | FlowKit | aiohttp | httpx | requests |
|---------|---------|---------|-------|----------|
| Fluent API | ✅ | ❌ | ❌ | ❌ |
| Type Safe | ✅ | ✅ | ✅ | ✅ |
| Sessions | ✅ | ✅ | ✅ | ❌ |
| Pipelines | ✅ | ❌ | ❌ | ❌ |

FlowKit provides **structured async workflows** with minimal overhead on top of httpx
and is comparable in performance for typical I/O-bound workloads.

## 📋 **License**

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

---

**🚀 Try FlowKit today for cleaner async workflows:**

```bash
pip install flowkit-async
```

**⭐ Star us on GitHub!** [github.com/flowkit/flowkit](https://github.com/flowkit/flowkit)
