Flowfull-Python Client

Production-ready HTTP client for Python applications to interact with Flowfull backends.

✨ Features

• ✅ Simple & User-Friendly - Like requests/httpx but for Flowfull
• ✅ Built-in Authentication - No separate auth package needed
• ✅ Type-Safe - Full type hints with Pydantic
• ✅ Async Support - Both sync and async APIs
• ✅ Powerful Query Builder - Chainable API with 14 filter operators
• ✅ Auto Session Management - Detects and injects session automatically
• ✅ Production-Ready - Retry logic, interceptors, error handling
• ✅ Pythonic - Follows PEP 8 and Python best practices

📦 Installation

For Users

pip install flowfull-python

For Development

Windows (PowerShell):

# Quick install (recommended)
.\install.ps1

# Or manual install
pip install -r requirements-dev.txt

Linux/Mac:

pip install -r requirements-dev.txt

See QUICK-START.md for detailed installation guide.

🚀 Quick Start

Basic Usage (Sync)

from core import FlowfullClient

# Create client (auto-detects session)
client = FlowfullClient("https://api.myapp.com")

# Simple GET
response = client.get("/users")
print(f"Found {len(response.data)} users")

Basic Usage (Async)

from core import AsyncFlowfullClient

async def main():
    async with AsyncFlowfullClient("https://api.myapp.com") as client:
        response = await client.get("/users")
        print(f"Found {len(response.data)} users")

Query Builder

from core import FlowfullClient, eq, gte, in_

client = FlowfullClient("https://api.myapp.com")

products = (
    client.query("/products")
    .where("status", eq("active"))
    .where("price", gte(50))
    .where("category", in_(["electronics", "books"]))
    .sort("price", "asc")
    .page(1)
    .limit(20)
    .get()
)

Authentication

# Create auth helper
auth = client.auth()

# Login
session = auth.login(
    email="user@example.com",
    password="password"
)

# Validate
is_valid = auth.validate_session()

# Refresh
user = auth.refresh_user()

# Logout
auth.logout()

🧪 Testing

Run Tests

# Quick start (auto-installs dependencies if needed)
python run_tests.py

# With coverage
python run_tests.py --cov

# With verbose output
python run_tests.py --verbose

See TESTING.md for comprehensive testing guide.

📚 Documentation

Full documentation is available:

• Quick Start: QUICK-START.md - Installation and setup
• Testing Guide: TESTING.md - Running and writing tests
• Architecture: to-do/00-ARCHITECTURE-OVERVIEW.md
• Setup Guide: to-do/01-SETUP.md
• Authentication: to-do/04-AUTHENTICATION.md
• Filter Syntax: to-do/FILTER-SYNTAX.md
• Quick Reference: to-do/QUICK-REFERENCE.md

🔧 Configuration

from core import FlowfullClient, FileStorage

client = FlowfullClient(
    base_url="https://api.myapp.com",
    storage=FileStorage("~/.myapp"),
    timeout=30.0,
    retry_attempts=3,
    retry_delay=1.0,
    retry_exponential=True,
    include_session=True,
)

📝 License

Flowfull-Python is licensed under the AGPL-3.0-only license.

What does this mean?

• ✅ Free to use - Use commercially without paying anything
• ✅ Modify freely - Change the code as needed
• ✅ Distribute - Share with others
• ⚠️ Share modifications - If you modify and offer as a web service, you must release your changes
• ⚠️ Same license - Derivative works must use AGPL-3.0

Commercial License Available

For organizations that cannot comply with AGPL-3.0 or need:

• 💼 Keep modifications private
• 🛡️ Legal indemnification
• 🎯 Enterprise support and SLA
• 🚀 Custom features

Contact: enterprise@pubflow.com Learn more: https://pubflow.com/dual-licensing

See LICENSE for full details.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

📧 Support

For issues and questions, please open an issue on GitHub.

For commercial support and licensing inquiries: enterprise@pubflow.com

---

Copyright © 2024-present Pubflow, Inc. SPDX-License-Identifier: AGPL-3.0-only

Made with ❤️ by the Pubflow Team