Metadata-Version: 2.4
Name: flowfull-python
Version: 1.0.0
Summary: Production-ready HTTP client for Flowfull backends
Author-email: "Pubflow, Inc." <enterprise@pubflow.com>
Maintainer-email: "Pubflow, Inc." <enterprise@pubflow.com>
License: AGPL-3.0-only
Project-URL: Homepage, https://pubflow.com
Project-URL: Documentation, https://github.com/pubflow/flowfull-python/tree/main/to-do
Project-URL: Repository, https://github.com/pubflow/flowfull-python
Project-URL: Issues, https://github.com/pubflow/flowfull-python/issues
Project-URL: Changelog, https://github.com/pubflow/flowfull-python/blob/main/CHANGELOG.md
Project-URL: Funding, https://pubflow.com/dual-licensing
Project-URL: Commercial License, https://pubflow.com/dual-licensing
Keywords: flowfull,http,client,api,pubflow,rest,crud
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Dynamic: license-file

# Flowfull-Python Client

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

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

```bash
pip install flowfull-python
```

### For Development

**Windows (PowerShell):**
```powershell
# Quick install (recommended)
.\install.ps1

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

**Linux/Mac:**
```bash
pip install -r requirements-dev.txt
```

See [QUICK-START.md](QUICK-START.md) for detailed installation guide.

## 🚀 Quick Start

### Basic Usage (Sync)

```python
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)

```python
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

```python
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

```python
# 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

```powershell
# 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](TESTING.md) for comprehensive testing guide.

## 📚 Documentation

Full documentation is available:

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

## 🔧 Configuration

```python
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](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**

