Metadata-Version: 2.4
Name: velocrium
Version: 0.1.0
Summary: The Next-Gen Async HTTP Client for Python - Fast, intuitive, and powerful
Project-URL: Homepage, https://github.com/jdevsky/velocrium
Project-URL: Documentation, https://velocrium.readthedocs.io
Project-URL: Repository, https://github.com/jdevsky/velocrium.git
Project-URL: Bug Tracker, https://github.com/jdevsky/velocrium/issues
Project-URL: Changelog, https://github.com/jdevsky/velocrium/blob/main/CHANGELOG.md
Project-URL: Author LinkedIn, https://linkedin.com/in/juste-elysee-malandila
Author-email: Juste Elysée MALANDILA <justech4dev@gmail.com>
License: MIT License
        
        Copyright (c) 2024 Juste Elysée MALANDILA
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: api,async,asyncio,client,http,httpx,requests,rest
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Requires-Python: >=3.8
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=22.0; extra == 'dev'
Requires-Dist: build>=0.8; extra == 'dev'
Requires-Dist: flake8>=4.0; extra == 'dev'
Requires-Dist: isort>=5.0; extra == 'dev'
Requires-Dist: mypy>=0.950; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# ⚡ VELOCRIUM

### *The Next-Generation Async HTTP Client for Python*

[![PyPI version](https://badge.fury.io/py/velocrium.svg)](https://badge.fury.io/py/velocrium)
[![Python Versions](https://img.shields.io/pypi/pyversions/velocrium.svg)](https://pypi.org/project/velocrium/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://pepy.tech/badge/velocrium)](https://pepy.tech/project/velocrium)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**Fast** • **Intuitive** • **Powerful** • **Modern**

[Documentation](https://velocrium.readthedocs.io) • [Examples](https://github.com/jdevsky/velocrium/tree/main/examples) • [Changelog](https://github.com/jdevsky/velocrium/blob/main/CHANGELOG.md)

</div>

---

## 🚀 Why VELOCRIUM?

VELOCRIUM is the **modern HTTP client** Python deserves. Built from the ground up with **async/await**, it combines the simplicity of `requests` with the power of `httpx` and adds features you didn't know you needed.

###  ✨ Key Features

| Feature | Description |
|---------|-------------|
| 🔄 **Async/Sync Transparent** | Same API works in both sync and async contexts |
| 🔁 **Smart Retry** | Exponential backoff, jitter, custom strategies |
| 💾 **HTTP Caching** | RFC-compliant caching with multiple backends |
| ⏱️ **Rate Limiting** | Built-in rate limiting (per-second, per-minute, per-hour) |
| 🔌 **Connection Pooling** | Optimized connection reuse and management |
| 🎯 **Type Hints** | Full type safety with IDE autocomplete |
| 📊 **Request Batching** | Execute multiple requests in parallel |
| 🔐 **Auth Support** | Basic, Bearer, OAuth, custom auth schemes |
| 🌐 **Proxy Support** | HTTP, HTTPS, SOCKS proxies |
| 📝 **Request/Response Hooks** | Middleware-style request/response processing |

---

## 📦 Installation

```bash
pip install velocrium
```

**With extras:**
```bash
pip install velocrium[redis]  # Redis caching support
pip install velocrium[all]    # All optional dependencies
```

---

## 🎯 Quick Start

### Basic Usage

```python
import velocrium

# Create a client
client = velocrium.Client()

# Make requests (works in sync context)
response = client.get("https://api.github.com/users/octocat")
print(response.json())

# Works in async context too!
async def fetch_user():
    response = await client.get("https://api.github.com/users/octocat")
    return response.json()
```

### With Smart Features

```python
import velocrium

client = velocrium.Client(
    # Automatic retry with exponential backoff
    retry=velocrium.Retry(
        max_attempts=3,
        backoff="exponential",
        jitter=True
    ),
    
    # HTTP caching
    cache=velocrium.Cache(
        ttl=3600,  # 1 hour
        backend="memory"  # or "redis", "disk"
    ),
    
    # Rate limiting
    rate_limit=velocrium.RateLimit("100/minute"),
    
    # Timeouts
    timeout=velocrium.Timeout(
        connect=5,
        read=30,
        write=10
    )
)

# All features work automatically!
response = client.get("https://api.example.com/data")
```

---

## 🔥 Advanced Features

### Batch Requests

```python
# Execute multiple requests in parallel
with client.batch() as batch:
    batch.get("https://api1.com/endpoint")
    batch.get("https://api2.com/endpoint")
    batch.post("https://api3.com/endpoint", json={"data": "value"})

responses = await batch.execute()
```

### Request/Response Hooks

```python
def log_request(request):
    print(f"→ {request.method} {request.url}")
    return request

def log_response(response):
    print(f"← {response.status_code} {response.url}")
    return response

client = velocrium.Client(
    hooks={
        "request": [log_request],
        "response": [log_response]
    }
)
```

### Custom Auth

```python
# Bearer token
client = velocrium.Client(
    auth=velocrium.BearerAuth("your-token")
)

# OAuth2
client = velocrium.Client(
    auth=velocrium.OAuth2(
        client_id="...",
        client_secret="...",
        token_url="..."
    )
)
```

---

## 📊 Comparison with Other Libraries

| Feature | velocrium | requests | httpx | aiohttp |
|---------|-----------|----------|-------|---------|
| Async/Sync Support | ✅ Both | ❌ Sync only | ✅ Both | ❌ Async only |
| Auto Retry | ✅ Built-in | ❌ Manual | ⚠️ Manual | ❌ Manual |
| HTTP Caching | ✅ Built-in | ❌ No | ❌ No | ❌ No |
| Rate Limiting | ✅ Built-in | ❌ No | ❌ No | ❌ No |
| Type Hints | ✅ Complete | ⚠️ Partial | ✅ Complete | ⚠️ Partial |
| Request Batching | ✅ Built-in | ❌ No | ❌ No | ⚠️ Manual |
| Learning Curve | 🟢 Easy | 🟢 Easy | 🟡 Medium | 🔴 Hard |

---

## 🎨 Real-World Examples

### API Client with Retry & Caching

```python
import velocrium

# Create a robust API client
api = velocrium.Client(
    base_url="https://api.example.com",
    retry=velocrium.Retry(max_attempts=3),
    cache=velocrium.Cache(ttl=300),  # 5 minutes
    headers={"User-Agent": "MyApp/1.0"}
)

# Fetch data (cached automatically)
users = api.get("/users").json()

# Post data (retry on failure)
result = api.post("/users", json={
    "name": "John Doe",
    "email": "john@example.com"
})
```

### Rate-Limited Scraper

```python
import velocrium

scraper = velocrium.Client(
    rate_limit=velocrium.RateLimit("10/second"),
    timeout=velocrium.Timeout(read=60)
)

async def scrape_pages(urls):
    results = []
    for url in urls:
        # Automatically rate-limited
        response = await scraper.get(url)
        results.append(response.text)
    return results
```

---

## 📚 Documentation

Full documentation available at **[velocrium.readthedocs.io](https://velocrium.readthedocs.io)**

- [User Guide](https://velocrium.readthedocs.io/guide)
- [API Reference](https://velocrium.readthedocs.io/api)
- [Examples](https://github.com/jdevsky/velocrium/tree/main/examples)
- [Changelog](https://github.com/jdevsky/velocrium/blob/main/CHANGELOG.md)

---

## 🧪 Testing

```bash
# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Run tests with coverage
pytest --cov=velocrium --cov-report=html

# Type checking
mypy src/velocrium

# Code formatting
black .
isort .
```

---

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/jdevsky/velocrium/blob/main/CONTRIBUTING.md) for guidelines.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a Pull Request

---

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 👤 Author

<div align="center">

**Juste Elysée MALANDILA**

[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://linkedin.com/in/juste-elysee-malandila)
[![Email](https://img.shields.io/badge/Email-D14836?style=for-the-badge&logo=gmail&logoColor=white)](mailto:justech4dev@gmail.com)
[![GitHub](https://img.shields.io/badge/GitHub-100000?style=for-the-badge&logo=github&logoColor=white)](https://github.com/jdevsky)

*Building the future of Python HTTP clients* 🚀

</div>

---

## ⭐ Show Your Support

If you find VELOCRIUM useful, please consider giving it a star on GitHub!

[![GitHub stars](https://img.shields.io/github/stars/jdevsky/velocrium.svg?style=social&label=Star)](https://github.com/jdevsky/velocrium)

---

<div align="center">

Made with ❤️ by [Juste Elysée MALANDILA](https://linkedin.com/in/juste-elysee-malandila)

**VELOCRIUM** - The Velocity Element ⚡

</div>
