taipanstack 0.2.5

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

🐍 TaipanStack

The Modern Python Foundation

Launch secure, high-performance Python applications in seconds.

---

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

---

✨ Why TaipanStack?

"Write less, build better."

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

🛡️ Security First Path traversal protection Command injection guards Input sanitizers & validators Secret detection integration	⚡ High Performance uvloop async event loop orjson fast JSON serialization Pydantic v2 validation Optimized for production
🎯 Rust-Style Error Handling Ok/Err Result types Explicit error propagation Pattern matching support No silent failures	🔧 Developer Experience Pre-configured quality tools Comprehensive test suite Architecture enforcement Zero-config setup

---

🚀 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 coverage (97%+ coverage)
make test

# Check architecture contracts
make lint-imports

# Run security scans
make security

---

📐 Architecture

TaipanStack 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/                # ✅ Comprehensive test suite (97%+ coverage)
├── pyapp/                # 📦 Standalone executable builder
├── .github/              # 🔄 CI/CD workflows
└── pyproject.toml        # 📋 Modern dependency management

---

🔐 DevSecOps

TaipanStack integrates security and quality at every level:

Category	Tools	Purpose
SAST	Bandit, Semgrep	Static Application Security Testing
SCA	Safety	Dependency vulnerability scanning
Types	Mypy (strict)	Compile-time type checking
Lint	Ruff	Lightning-fast linting & formatting
Arch	Import Linter	Dependency rule enforcement
Test	Pytest, Hypothesis	Property-based testing

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
✓ Architecture    → Import Linter contracts

---

📚 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.utils.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.utils.circuit_breaker import circuit_breaker

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

---

🛠️ Tech Stack

Runtime	Quality	DevOps
Pydantic v2 Orjson Uvloop Structlog Result	Ruff Mypy Bandit Pytest Hypothesis	GitHub Actions Dependabot Pre-commit Poetry Import Linter

---

🤝 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