easyseries 0.1.3

A comprehensive HTTP utility toolkit built on httpx with CLI support

EasySeries

A comprehensive HTTP utility toolkit built on httpx with CLI support. EasySeries provides modern Python developers with a robust foundation for building HTTP clients and utilities with advanced features like rate limiting, metrics collection, retry logic, and comprehensive error handling.

✨ Features

• 🚀 Modern Python: Built with Python 3.10+ using latest async/await patterns
• 🔧 httpx Integration: Leverages the powerful httpx library for HTTP operations
• 📊 Metrics & Monitoring: Built-in request metrics and performance tracking
• 🛡️ Error Handling: Comprehensive error handling with custom exceptions
• ⚡ Rate Limiting: Configurable rate limiting to respect API limits
• 🔄 Retry Logic: Intelligent retry mechanisms with exponential backoff
• 🎯 CLI Interface: Friendly command-line interface for testing and utilities
• 📝 Type Safety: Full type hints for better development experience
• ⚙️ Configuration: Flexible configuration with environment variable support

🚀 Quick Start

Installation

# Using pip
pip install easyseries

# Using uv (recommended)
uv add easyseries

### Basic Usage

```python
import asyncio
from easyseries import HTTPClient

async def main():
    async with HTTPClient(base_url="https://api.example.com") as client:
        # GET request
        response = await client.get("/users")
        users = response.json()

        # POST request
        new_user = await client.post("/users", json={
            "name": "John Doe",
            "email": "[e-mail]"
        })

asyncio.run(main())

CLI Usage

# Make a simple request
easyseries request https://httpbin.org/get

# POST with JSON data
easyseries request https://httpbin.org/post \
    --method POST \
    --data '{"name": "John", "age": 30}'

# Benchmark an endpoint
easyseries benchmark https://httpbin.org/get \
    --requests 100 \
    --concurrency 10

# View configuration
easyseries config

📋 Development Setup

This project uses modern Python tooling for the best development experience.

Prerequisites

• Python 3.10 or higher
• uv (recommended) or pip

Initial Setup

# Clone the repository
git clone https://github.com/ScienisTmiaoT/easyseries.git
cd easyseries

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install all dependencies including dev tools
uv sync --all-extras --dev

# Install pre-commit hooks
uv run pre-commit install

Development Commands

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=easyseries --cov-report=html

# Lint and format code
uv run ruff check .
uv run ruff format .

# Type checking
uv run mypy src/easyseries

# Run all checks (lint, format, type check, test)
uv run pre-commit run --all-files

📚 Documentation

Building Documentation Locally

# Install documentation dependencies
uv sync --extra docs

# Build documentation
cd docs
uv run sphinx-build -b html source _build/html

# Serve documentation locally
python -m http.server 8000 -d _build/html

Documentation Structure

• API Reference: Complete API documentation with examples
• User Guide: Step-by-step tutorials and how-to guides
• Development: Contributing guidelines and development setup

🔧 Configuration

EasySeries supports configuration through environment variables or .env files:

# .env file example
EASYSERIES_TIMEOUT=30.0
EASYSERIES_MAX_RETRIES=3
EASYSERIES_BASE_URL=https://api.myservice.com
EASYSERIES_USER_AGENT=MyApp/1.0.0
EASYSERIES_ENABLE_METRICS=true
EASYSERIES_RATE_LIMIT_REQUESTS=100

🧪 Testing

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=easyseries

# Run specific test file
uv run pytest tests/test_http/test_client.py

# Run with markers
uv run pytest -m "not slow"

Test Structure

• tests/test_http/ - HTTP client tests
• tests/test_cli/ - CLI interface tests
• tests/conftest.py - Shared pytest fixtures

🏗️ Project Structure

easyseries/
├── src/easyseries/          # Main package
│   ├── cli/                 # CLI interface
│   ├── core/                # Core functionality
│   └── http/                # HTTP client modules
├── tests/                   # Test suite
├── docs/                    # Documentation
├── scripts/                 # Utility scripts
└── .github/workflows/       # CI/CD workflows

🔄 Dependency Management

Adding Dependencies

# Add runtime dependency
uv add httpx

# Add development dependency
uv add --dev pytest

# Add optional dependency group
uv add --optional docs sphinx

Updating Dependencies

# Update all dependencies
uv sync --upgrade

# Update specific dependency
uv add httpx@latest

# Check for outdated dependencies
uv tree --outdated

Environment Management

# Create lock file
uv lock

# Sync from lock file
uv sync

# Export requirements
uv export --format requirements-txt > requirements.txt

🚀 Publishing

Building the Package

# Build wheel and source distribution
uv build

# Check the built package
uv run twine check dist/*

Publishing to PyPI

The project uses GitHub Actions for automated publishing:

• Automatic Publishing: Push a tag starting with v (e.g., v1.0.0)
• Manual Publishing: Use the GitHub Actions workflow dispatch

# Create and push a tag
git tag v1.0.0
git push origin v1.0.0

# Or publish manually
uv publish --token $PYPI_TOKEN

🤖 CI/CD

GitHub Actions Workflows

• CI Pipeline (.github/workflows/ci.yml):

  • Runs on Python 3.10, 3.11, 3.12, 3.13
  • Linting, type checking, and testing
  • Code coverage reporting
  • Security scanning

• Publishing (.github/workflows/publish.yml):

  • Publishes to PyPI on tag push
  • Deploys documentation to GitHub Pages
  • Runs on successful CI completion

Branch Protection

Recommended branch protection rules for main:

• Require pull request reviews
• Require status checks to pass
• Require branches to be up to date
• Include administrators

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Steps

• Fork the repository
• Create a feature branch: git checkout -b feature/amazing-feature
• Make your changes and add tests
• Run the test suite: uv run pytest
• Commit your changes: git commit -m 'Add amazing feature'
• Push to the branch: git push origin feature/amazing-feature
• Open a Pull Request

📞 Support

• 📖 Documentation
• 🐛 Bug Reports
• 💬 Discussions

🎯 Roadmap

• WebSocket support
• GraphQL client utilities
• Plugin system for custom middleware
• Built-in caching mechanisms
• Prometheus metrics export
• OpenAPI schema validation

EasySeries - Making HTTP requests in Python easier than ever! 🚀