taipanstack 0.5.2

TaipanStack - Modular, secure, and scalable Python stack for robust development

🐍 Taipan Stack

The Modern Python Foundation

Launch secure, high-performance Python applications in seconds.

---

Features • Quick Start • Architecture • DevSecOps • API • Contributing

---

✨ 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.5.2

• Sentinel Hardening: Enforced multicast and unspecified IP address bounds checking inside guard_ssrf (PR #826) and added negative domain bounds checks to resilience LBYL type guards (PR #823).
• Resilience under Chaos: Protected CircuitBreaker and Retry against runtime property type mutations and configuration exception changes under chaos, and fixed NaN last_failure_time lockout vulnerability (PR #811, #819, #830).
• Complexity Refactor: Reduced cyclomatic and cognitive complexity in watchdogs, orchestrators, bridges, and circuit breakers (PR #813, #817, #821, #835).
• QA & Typing: Standardized test naming convention (test_*.py) and refactored test suite to achieve 100% genuine coverage over 1,226 passing tests (PR #816, #825, #831, #837).
• Bridges API Reference: Added new API documentation reference for the Bridges module (PR #822).

🛡️ Security First Path traversal protection Command injection guards Input sanitizers & validators Secret detection integration SBOM + SLSA supply-chain attestation	⚡ High Performance uvloop async event loop orjson fast JSON serialization Pydantic v2 validation
🎯 Rust-Style Error Handling Ok/Err Result types Explicit error propagation Pattern matching support No silent failures	🔧 Developer Experience Pre-configured quality tools 100% code coverage (1,226 tests) Architecture enforcement Hardened Docker template

---

🚀 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,226 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      │       │     Utils       │
│ guards, saniti- │       │    models,      │       │  logging, retry │
│ zers, validators│       │   generators    │       │ metrics, fs     │
└────────┬────────┘       └────────┬────────┘       └────────┬────────┘
         │                         │                         │
         └─────────────────────────┼─────────────────────────┘
                                   ▼
                    ┌─────────────────────────────────────┐
                    │              Core                   │
                    │    Result types, base patterns      │
                    └─────────────────────────────────────┘

Project Structure

TaipanStack/
├── src/
│   ├── app/              # Application entry point
│   └── taipanstack/
│       ├── core/         # 🎯 Result types, functional patterns
│       ├── config/       # ⚙️ Configuration models & generators
│       ├── security/     # 🛡️ Guards, sanitizers, validators
│       └── utils/        # 🔧 Logging, metrics, retry, filesystem
├── tests/                # ✅ 1,226 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:

Category	Tools	Purpose
SAST	Bandit, Semgrep + custom rules	Static Application Security Testing
SCA	pip-audit	Dependency vulnerability scanning
SBOM	Syft (CycloneDX)	Software Bill of Materials
SLSA	Cosign (Sigstore)	Artifact signing & attestation
Types	Mypy (strict)	Compile-time type checking
Lint	Ruff	Lightning-fast linting & formatting
Arch	Import Linter	Dependency rule enforcement
Test	Pytest, Hypothesis, mutmut	Property-based & mutation testing
Containers	Docker (Alpine, rootless)	Hardened-by-default images

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

Runtime	Quality	DevSecOps
Pydantic v2 Orjson Uvloop Structlog Result	Ruff Mypy Bandit Pytest + Hypothesis mutmut	GitHub Actions Syft + Cosign (SBOM/SLSA) Dependabot Pre-commit Poetry Docker (Alpine, rootless)

---

🤝 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.

---

Made with ❤️ for the Python community

⬆ Back to Top