Development

git clone https://github.com/greysonlalonde/polyflux.git
cd polyflux

# Create and activate virtual environment (handled automatically by uv)
uv sync --all-groups

# Verify installation
uv run python --version  # Should be 3.12+

uv run pre-commit install

# Basic package
uv run scripts/create-package.py grpc

# With dependencies
uv run scripts/create-package.py mqtt asyncio-mqtt "paho-mqtt==1.6.1"

# Custom class name
uv run scripts/create-package.py grpc --class-name GRPC "grpcio>=1.50.0"

packages/new-package/
├── src/polyflux/new_package/
│   ├── __init__.py                 # Package exports
│   ├── client/
│   │   ├── __init__.py
│   │   ├── base.py                 # Unified client implementation (all protocols)
│   │   └── configurable.py        # Configuration schema
│   ├── server/
│   │   ├── __init__.py
│   │   ├── base.py                 # Unified server implementation (all protocols)
│   │   ├── configurable.py        # Server configuration
│   │   ├── exceptions.py           # Server-specific exceptions  
│   │   ├── types.py                # Server-specific types
│   │   └── utils.py                # Protocol-specific utility functions
│   └── shared/
│       ├── __init__.py
│       ├── protocol_data_unit.py   # PDU definitions
│       ├── types.py                # Shared type definitions
│       └── utils.py                # Shared utility functions
├── tests/                          # Comprehensive test suite
├── pyproject.toml                  # Package configuration
└── README.md                       # Package documentation

from typing import Protocol, runtime_checkable, Any
from polyflux.core import BaseExchange
from polyflux.core.shared.contracts.protocol_data_unit import Inbound

@runtime_checkable
class GrpcClient(BaseExchange[Inbound], Protocol):
    """gRPC-specific client protocol."""
    
    async def call_method(self, service: str, method: str, **kwargs: Any) -> bool:
        """Call gRPC method."""
        ...
    
    async def disconnect(self) -> None:
        """Close gRPC connection."""
        ...

class GrpcClientImpl(GrpcClient):
    """Concrete gRPC client implementation."""
    
    async def exchange(self, **kwargs: Any) -> Inbound:
        # Implementation here
        ...

from typing import TypedDict, NotRequired
from polyflux.core import BaseConfigSchema

class GrpcConfigSchema(BaseConfigSchema):
    host: str  # Required
    port: int  # Required
    timeout: NotRequired[float]  # Optional (inherited)
    ssl_enabled: NotRequired[bool]  # Optional
    credentials: NotRequired[dict[str, str]]  # Optional

# Bad: Missing type annotations
def connect_grpc(host):
    return grpc_client.connect(host)

# Bad: Not using protocols
class GrpcClient:
    def call_method(self, method):
        pass

# Bad: Hardcoded configuration
class Client:
    def __init__(self):
        self.timeout = 30  # Should be configurable

# Run all tests
./scripts/test-all-packages.sh

# Run specific package tests
uv run pytest packages/http/tests/ -v

# Run with coverage
uv run pytest packages/http/tests/ --cov=polyflux.http

# Run specific test
uv run pytest packages/http/tests/test_client.py::test_http_exchange -v

import pytest
from polyflux.http import HttpClient, HttpClientConfigSchema

@pytest.mark.asyncio
async def test_http_client_exchange():
    """Test HTTP client exchange functionality."""
    config: HttpClientConfigSchema = {
        "base_url": "https://httpbin.org",
        "timeout": 10.0
    }
    
    client = HttpClient()
    client.configure(config)
    
    async with client:
        response = await client.exchange(
            target="/get",
            method="GET"
        )
        
        assert response["status_code"] == 200
        assert b"httpbin" in response["data"]

# WebSocket test example (from production package)
from polyflux.websocket import WebSocketClient

@pytest.mark.asyncio
async def test_websocket_client_exchange():
    """Test WebSocket client exchange functionality."""
    async with WebSocketClient() as client:
        await client.connect("wss://echo.websocket.org")
        
        response = await client.exchange(
            target="wss://echo.websocket.org",
            message_type="text",
            data="Hello WebSocket!"
        )
        
        assert response["message_type"] == "text"
        assert "Hello WebSocket!" in response["data"]

# Build all packages
./scripts/build-all.sh

# Build specific package
cd packages/http && uv build

# Publish (maintainers only)
./scripts/publish.sh

# Bump version across all packages
./scripts/bump-version.sh 0.2.0

# Check for dead code
./scripts/check-dead-and-duplicate.sh

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.linting.mypyEnabled": true,
  "python.formatting.provider": "ruff",
  "python.linting.ruffEnabled": true
}