https://github.com/gabrielima7/taipanstack
Modular, secure, and scalable Python stack for robust development - Security guards, Result types, Retry logic, Circuit breakers, and more.
https://github.com/gabrielima7/taipanstack
api devops python python3 stack toolkit utils
Last synced: about 2 months ago
JSON representation
Modular, secure, and scalable Python stack for robust development - Security guards, Result types, Retry logic, Circuit breakers, and more.
- Host: GitHub
- URL: https://github.com/gabrielima7/taipanstack
- Owner: gabrielima7
- License: mit
- Created: 2025-11-26T14:07:07.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-05-02T08:18:35.000Z (about 2 months ago)
- Last Synced: 2026-05-02T09:16:32.240Z (about 2 months ago)
- Topics: api, devops, python, python3, stack, toolkit, utils
- Language: Python
- Homepage: https://gabrielima7.github.io/TaipanStack/
- Size: 15.1 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: agents.md
Awesome Lists containing this project
README
# 🐍 Taipan Stack
### **The Modern Python Foundation**
*Launch secure, high-performance Python applications in seconds.*
[](https://www.python.org/)
[](https://github.com/gabrielima7/TaipanStack)
[](https://github.com/astral-sh/ruff)
[](http://mypy-lang.org/)
[](LICENSE)
[](SECURITY.md)
[](https://github.com/gabrielima7/TaipanStack/actions/workflows/sbom-slsa.yml)
[](https://github.com/gabrielima7/TaipanStack/actions/workflows/sbom-slsa.yml)
[](https://pypi.org/project/taipanstack/)
---
[**Features**](#-features) • [**Quick Start**](#-quick-start) • [**Architecture**](#-architecture) • [**DevSecOps**](#-devsecops) • [**API**](#-api-highlights) • [**Contributing**](#-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.4.8
- **Hardening Resilience**: Hardened `RateLimiter` and `CircuitBreaker` against state corruption and type mutations via chaos testing (PR #689, #684).
- **Complexity Reduction**: Major reduction of cyclomatic complexity across core modules, subprocess utilities, and web bridges (PR #706, #692).
- **Security Hardening**: Restored missing type guard for password verification and enhanced durability of atomic writes (Commit f83b6745, PR #688).
- **Performance**: Implemented concurrent execution for async health checks in `HealthPinger` (PR #694).
- **Total Stack Coverage**: Reached **1,315 passing tests** with 100% verified genuine coverage across all modules.
### 🛡️ 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
- Performance benchmarks with regression detection
### 🎯 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** (1315 tests)
- Architecture enforcement
- Hardened Docker template
---
## 🚀 Quick Start
### Prerequisites
- **Python 3.11+** (supports 3.11, 3.12, 3.13, 3.14)
- **Poetry** ([install guide](https://python-poetry.org/docs/#installation))
### Installation
#### From PyPI
```bash
pip install taipanstack
```
#### From Source
```bash
# 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
```bash
# Run tests with 100% coverage (1315 tests)
make test
# Check architecture contracts
make lint-imports
# Run security scans
make security
# Run property-based fuzzing
make property-test
# Run performance benchmarks
make benchmark
```
---
## 📐 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
```text
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/ # ✅ 1315 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** | Safety, 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 |
| **Perf** | pytest-benchmark | Performance regression detection |
| **Containers** | Docker (Alpine, rootless) | Hardened-by-default images |
### CI Pipeline
```yaml
# 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)
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```bash
# 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
- pytest-benchmark
- GitHub Actions
- Syft + Cosign (SBOM/SLSA)
- Dependabot
- Pre-commit
- Poetry
- Docker (Alpine, rootless)
---
## 🤝 Contributing
Contributions are welcome! Please check our [Contributing Guide](CONTRIBUTING.md) for details on:
- 🐛 Bug reports
- ✨ Feature requests
- 📝 Documentation improvements
- 🔧 Pull requests
---
## 📝 License
This project is open-sourced under the [MIT License](LICENSE).
---
**Made with ❤️ for the Python community**
[⬆ Back to Top](#-taipanstack)