flowkit-async 1.0.0
Fluent async workflows with lazy execution for Python
Requires Python: >=3.8
Keywords: async, workflow, simplification, http, api

# 🚀 **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)