Skip to content

README.md

Latest commit

 

History

History
198 lines (139 loc) · 4.67 KB

README.md

File metadata and controls

198 lines (139 loc) · 4.67 KB

Flowfull-Python Client

License: AGPL-3.0 Python 3.11+

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:

🔧 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