✨ Why Taipan Stack?

"Write less, build better."

Taipan Stack is a battle-tested foundation for production-grade Python projects that combines security, performance, and developer experience into a single, cohesive toolkit.

✨ What's New in v0.6.1

• Security & Hardening: Hardened RateLimiter against infinite tokens mutations, key decoding in JWT, and validate_project_name argument parsing. Fixed large password payload crashes and removed unused constants (PR #966, #967, #968, #973, #989).
• Concurrency & Resilience: Fixed a bulkhead acquisition memory leak in ResilienceOrchestrator and documented AdaptiveRetry features (PR #974, #980).
• Clean Code & Refactoring: Significantly reduced cyclomatic complexity across compatibility shims, validators, filesystems, and token buckets. Enforced strict web bridge type hints and clean keyword parameters (PR #971, #976, #979, #984, #988, #993, #997, #1002, #1003).
• QA and Standardized Testing: Fully standardized test file nomenclature, verified 1,460+ passing tests with 100% genuine branch coverage, and added rigorous microservice chaos engineering simulations (PR #972, #975, #981, #986, #990, #992, #994, #999, #1004).

🚀 Quick Start

Prerequisites

• Python 3.11+ (supports 3.11, 3.12, 3.13, 3.14)
• Poetry (install guide)

Installation

From PyPI

pip install taipanstack

From Source

# Clone the repository
git clone https://github.com/gabrielima7/TaipanStack.git
cd TaipanStack

# Install dependencies
poetry install --with dev

# Run quality checks
make all

Verify Installation

# Run tests with 100% coverage (1,430 tests)
make test

# Check architecture contracts
make lint-imports

# Run security scans
make security

# Run property-based fuzzing
make property-test

📐 Architecture

Taipan Stack follows a clean, layered architecture with strict dependency rules enforced by Import Linter.

                    ┌────────────────────────────────────────────────────────┐
                    │                      Application                       │
                    │                   (src/app/main.py)                    │
                    └───────────────────────────┬────────────────────────────┘
                                                │
          ┌───────────────┬─────────────────────┼───────────────┬──────────────┐
          ▼               ▼                     ▼               ▼              ▼
┌─────────────────┐┌──────────────┐     ┌──────────────┐┌──────────────┐┌──────────────┐
│    Security     ││   Config     │     │   Bridges    ││  Resilience  ││    Utils     │
│ guards, saniti- ││ models, gens │     │  http, db    ││ retry, break ││ logging, fs  │
│ zers, validators││              │     │              ││ watchdogs    ││ context      │
└────────┬────────┘└──────┬───────┘     └───────┬──────┘└───────┬──────┘└──────┬───────┘
         │                │                     │               │              │
         └────────────────┴─────────────────────┼───────────────┴──────────────┘
                                                ▼
                               ┌────────────────────────────────┐
                               │              Core              │
                               │  Result types, optimizations   │
                               └────────────────────────────────┘

Project Structure

TaipanStack/
├── src/
│   ├── app/              # Application entry point
│   └── taipanstack/
│       ├── bridges/      # 🌉 External communication integrations (http, db, web)
│       ├── config/       # ⚙️ Configuration models & generators
│       ├── core/         # 🎯 Result types, functional patterns
│       ├── resilience/   # 🌊 Reliability patterns (circuit breakers, retries, watchdogs)
│       ├── security/     # 🛡️ Guards, sanitizers, validators
│       └── utils/        # 🔧 Cross-cutting utilities (logging, cache, filesystem)
├── tests/                # ✅ 1,430 tests, 100% coverage
├── .semgrep/             # 🔍 Custom SAST rules
├── .github/              # 🔄 CI/CD + SBOM/SLSA workflows
├── Dockerfile            # 🐳 Hardened multi-stage container
└── pyproject.toml        # 📋 Modern dependency management

🔐 DevSecOps

Taipan Stack integrates security and quality at every level:

CI Pipeline

# Runs on every push/PR
✓ Test Matrix     → Python 3.11-3.14 × (Ubuntu, macOS, Windows)
✓ Linux Distros   → Ubuntu, Debian, Fedora, openSUSE, Arch, Alpine
✓ Code Quality    → Ruff check & format
✓ Type Check      → Mypy strict mode
✓ Security        → Bandit + Semgrep (custom rules)
✓ Architecture    → Import Linter contracts
✓ Benchmarks      → Performance regression (>5% = fail)
✓ SBOM + SLSA     → Supply-chain attestation on release

📚 API Highlights

Result Types (Rust-Style Error Handling)

from taipanstack.core.result import Result, Ok, Err, safe

@safe
def divide(a: int, b: int) -> float:
    return a / b

# Explicit error handling with pattern matching
match divide(10, 0):
    case Ok(value):
        print(f"Result: {value}")
    case Err(error):
        print(f"Error: {error}")

Security Guards

from taipanstack.security.guards import guard_path_traversal, guard_command_injection

# Prevent path traversal attacks
safe_path = guard_path_traversal(user_input, base_dir="/app/data")

# Prevent command injection
safe_cmd = guard_command_injection(
    ["git", "clone", repo_url],
    allowed_commands=["git"]
)

Retry with Exponential Backoff

from taipanstack.resilience.retry import retry

@retry(max_attempts=3, on=(ConnectionError, TimeoutError))
async def fetch_data(url: str) -> dict:
    return await http_client.get(url)

Circuit Breaker

from taipanstack.resilience.circuit_breaker import circuit_breaker

@circuit_breaker(failure_threshold=5, timeout=30)
def call_external_service() -> Response:
    return service.call()

🔗 Combining Result + Circuit Breaker

from taipanstack.core.result import safe, Ok, Err
from taipanstack.resilience.circuit_breaker import CircuitBreaker

breaker = CircuitBreaker(failure_threshold=3, timeout=60, name="payments")

@breaker
@safe
def charge_customer(customer_id: str, amount: float) -> dict:
    return payment_gateway.charge(customer_id, amount)

# Both circuit protection AND explicit error handling
result = charge_customer("cust_123", 49.99)
match result:
    case Ok(receipt):
        print(f"Payment successful: {receipt}")
    case Err(error):
        print(f"Payment failed safely: {error}")

🔗 Combining Result + Retry with Monitoring

from taipanstack.core.result import safe, unwrap_or
from taipanstack.resilience.retry import retry

@retry(
    max_attempts=3,
    on=(ConnectionError, TimeoutError),
    on_retry=lambda attempt, max_a, exc, delay: print(
        f"⚠️  Attempt {attempt}/{max_a} failed, retrying in {delay:.1f}s..."
    ),
)
@safe
def fetch_user_profile(user_id: str) -> dict:
    return api_client.get(f"/users/{user_id}")

# Retry handles transient failures, Result handles business errors
profile = unwrap_or(fetch_user_profile("usr_456"), {"name": "Unknown"})

🔗 Adaptive Resilience Pipeline

from taipanstack.core.result import Result, Ok, Err
from taipanstack.resilience.adaptive import ResilienceOrchestrator, AdaptiveCircuitBreaker
from taipanstack.resilience.retry import RetryConfig

# Compose an intelligent pipeline: Bulkhead -> Breaker -> Retry -> Timeout -> Fallback
orch = (
    ResilienceOrchestrator("billing_api")
    .with_bulkhead(max_concurrent=10, max_queue=50) # Prevent resource exhaustion
    .with_circuit_breaker(AdaptiveCircuitBreaker("billing", target_error_rate=0.1)) # Auto-tunes thresholds
    .with_retry(RetryConfig(max_attempts=3, initial_delay=0.1))
    .with_fallback({"status": "unavailable"})
)

async def process_billing() -> Result[dict, Exception]:
    # The orchestrator handles all concurrency, retry, circuit breaking, and fallbacks
    return await orch.execute(stripe_gateway.charge)

Intelligent Caching

from taipanstack.utils.cache import cached
from taipanstack.core.result import Result

@cached(ttl=60)
async def get_user_data(user_id: int) -> Result[dict, Exception]:
    return await db.fetch(user_id) # Only Ok() results are cached

Fallbacks & Timeouts

from taipanstack.resilience.resilience import fallback, timeout
from taipanstack.core.result import Result

@fallback({"status": "offline"}, exceptions=(TimeoutError,))
@timeout(seconds=5.0)
async def fetch_remote_status() -> Result[dict, Exception]:
    return await api.get_status()

🐳 Docker

# Build hardened image
docker build -t taipanstack:latest .

# Run (rootless, read-only)
docker run --rm --read-only taipanstack:latest

Security features: multi-stage build, Alpine base (<50MB), non-root appuser (UID 1000), healthcheck, no shell in runtime.

🛠️ Tech Stack

🤝 Contributing

Contributions are welcome! Please check our Contributing Guide for details on:

• 🐛 Bug reports
• ✨ Feature requests
• 📝 Documentation improvements
• 🔧 Pull requests

📝 License

This project is open-sourced under the MIT License.