{"id":45892046,"url":"https://github.com/gabrielima7/taipanstack","last_synced_at":"2026-05-08T20:01:29.390Z","repository":{"id":326235020,"uuid":"1104659158","full_name":"gabrielima7/TaipanStack","owner":"gabrielima7","description":"Modular, secure, and scalable Python stack for robust development - Security guards, Result types, Retry logic, Circuit breakers, and more.","archived":false,"fork":false,"pushed_at":"2026-05-02T08:18:35.000Z","size":15810,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-02T09:16:32.240Z","etag":null,"topics":["api","devops","python","python3","stack","toolkit","utils"],"latest_commit_sha":null,"homepage":"https://gabrielima7.github.io/TaipanStack/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabrielima7.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"agents.md","dco":null,"cla":null}},"created_at":"2025-11-26T14:07:07.000Z","updated_at":"2026-05-01T18:17:22.000Z","dependencies_parsed_at":"2026-05-08T20:00:56.151Z","dependency_job_id":null,"html_url":"https://github.com/gabrielima7/TaipanStack","commit_stats":null,"previous_names":["gabrielima7/stack","gabrielima7/taipanstack"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/gabrielima7/TaipanStack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielima7%2FTaipanStack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielima7%2FTaipanStack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielima7%2FTaipanStack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielima7%2FTaipanStack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabrielima7","download_url":"https://codeload.github.com/gabrielima7/TaipanStack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielima7%2FTaipanStack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32795416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","devops","python","python3","stack","toolkit","utils"],"created_at":"2026-02-27T18:30:37.433Z","updated_at":"2026-05-08T20:01:29.384Z","avatar_url":"https://github.com/gabrielima7.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🐍 Taipan Stack\n\n### **The Modern Python Foundation**\n\n*Launch secure, high-performance Python applications in seconds.*\n\n[![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776AB?style=flat\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n[![Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen?style=flat\u0026logo=codecov)](https://github.com/gabrielima7/TaipanStack)\n[![Code Style](https://img.shields.io/badge/Code%20Style-Ruff-D7FF64?style=flat\u0026logo=ruff\u0026logoColor=black)](https://github.com/astral-sh/ruff)\n[![Type Checked](https://img.shields.io/badge/Type%20Checked-Mypy-blue?style=flat)](http://mypy-lang.org/)\n[![License](https://img.shields.io/badge/License-MIT-green?style=flat)](LICENSE)\n[![Security](https://img.shields.io/badge/Security-Bandit%20%7C%20Semgrep-red?style=flat)](SECURITY.md)\n[![SBOM](https://img.shields.io/badge/SBOM-CycloneDX-informational?style=flat\u0026logo=owasp)](https://github.com/gabrielima7/TaipanStack/actions/workflows/sbom-slsa.yml)\n[![SLSA](https://img.shields.io/badge/SLSA-Sigstore-blueviolet?style=flat)](https://github.com/gabrielima7/TaipanStack/actions/workflows/sbom-slsa.yml)\n[![PyPI](https://img.shields.io/pypi/v/taipanstack?style=flat\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/taipanstack/)\n\n---\n\n[**Features**](#-features) • [**Quick Start**](#-quick-start) • [**Architecture**](#-architecture) • [**DevSecOps**](#-devsecops) • [**API**](#-api-highlights) • [**Contributing**](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Why Taipan Stack?\n\n\u003e **\"Write less, build better.\"**\n\nTaipan Stack is a battle-tested foundation for production-grade Python projects that combines **security**, **performance**, and **developer experience** into a single, cohesive toolkit.\n\n### ✨ What's New in v0.4.8\n- **Hardening Resilience**: Hardened `RateLimiter` and `CircuitBreaker` against state corruption and type mutations via chaos testing (PR #689, #684).\n- **Complexity Reduction**: Major reduction of cyclomatic complexity across core modules, subprocess utilities, and web bridges (PR #706, #692).\n- **Security Hardening**: Restored missing type guard for password verification and enhanced durability of atomic writes (Commit f83b6745, PR #688).\n- **Performance**: Implemented concurrent execution for async health checks in `HealthPinger` (PR #694).\n- **Total Stack Coverage**: Reached **1,315 passing tests** with 100% verified genuine coverage across all modules.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🛡️ Security First\n- Path traversal protection\n- Command injection guards\n- Input sanitizers \u0026 validators\n- Secret detection integration\n- **SBOM + SLSA** supply-chain attestation\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### ⚡ High Performance\n- `uvloop` async event loop\n- `orjson` fast JSON serialization\n- `Pydantic v2` validation\n- Performance benchmarks with regression detection\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🎯 Rust-Style Error Handling\n- `Ok`/`Err` Result types\n- Explicit error propagation\n- Pattern matching support\n- No silent failures\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🔧 Developer Experience\n- Pre-configured quality tools\n- **100% code coverage** (1315 tests)\n- Architecture enforcement\n- Hardened Docker template\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** (supports 3.11, 3.12, 3.13, 3.14)\n- **Poetry** ([install guide](https://python-poetry.org/docs/#installation))\n\n### Installation\n\n#### From PyPI\n\n```bash\npip install taipanstack\n```\n\n#### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/gabrielima7/TaipanStack.git\ncd TaipanStack\n\n# Install dependencies\npoetry install --with dev\n\n# Run quality checks\nmake all\n```\n\n### Verify Installation\n\n```bash\n# Run tests with 100% coverage (1315 tests)\nmake test\n\n# Check architecture contracts\nmake lint-imports\n\n# Run security scans\nmake security\n\n# Run property-based fuzzing\nmake property-test\n\n# Run performance benchmarks\nmake benchmark\n```\n\n---\n\n## 📐 Architecture\n\nTaipan Stack follows a clean, layered architecture with strict dependency rules enforced by **Import Linter**.\n\n```\n                    ┌─────────────────────────────────────┐\n                    │             Application             │\n                    │          (src/app/main.py)          │\n                    └─────────────────┬───────────────────┘\n                                      │\n          ┌───────────────────────────┼───────────────────────────┐\n          ▼                           ▼                           ▼\n┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐\n│    Security     │       │     Config      │       │     Utils       │\n│ guards, saniti- │       │    models,      │       │  logging, retry │\n│ zers, validators│       │   generators    │       │ metrics, fs     │\n└────────┬────────┘       └────────┬────────┘       └────────┬────────┘\n         │                         │                         │\n         └─────────────────────────┼─────────────────────────┘\n                                   ▼\n                    ┌─────────────────────────────────────┐\n                    │              Core                   │\n                    │    Result types, base patterns      │\n                    └─────────────────────────────────────┘\n```\n\n### Project Structure\n\n```text\nTaipanStack/\n├── src/\n│   ├── app/              # Application entry point\n│   └── taipanstack/\n│       ├── core/         # 🎯 Result types, functional patterns\n│       ├── config/       # ⚙️ Configuration models \u0026 generators\n│       ├── security/     # 🛡️ Guards, sanitizers, validators\n│       └── utils/        # 🔧 Logging, metrics, retry, filesystem\n├── tests/                # ✅ 1315 tests, 100% coverage\n├── .semgrep/             # 🔍 Custom SAST rules\n├── .github/              # 🔄 CI/CD + SBOM/SLSA workflows\n├── Dockerfile            # 🐳 Hardened multi-stage container\n└── pyproject.toml        # 📋 Modern dependency management\n```\n\n---\n\n## 🔐 DevSecOps\n\nTaipan Stack integrates security and quality at every level:\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| **SAST** | Bandit, Semgrep + custom rules | Static Application Security Testing |\n| **SCA** | Safety, pip-audit | Dependency vulnerability scanning |\n| **SBOM** | Syft (CycloneDX) | Software Bill of Materials |\n| **SLSA** | Cosign (Sigstore) | Artifact signing \u0026 attestation |\n| **Types** | Mypy (strict) | Compile-time type checking |\n| **Lint** | Ruff | Lightning-fast linting \u0026 formatting |\n| **Arch** | Import Linter | Dependency rule enforcement |\n| **Test** | Pytest, Hypothesis, mutmut | Property-based \u0026 mutation testing |\n| **Perf** | pytest-benchmark | Performance regression detection |\n| **Containers** | Docker (Alpine, rootless) | Hardened-by-default images |\n\n### CI Pipeline\n\n```yaml\n# Runs on every push/PR\n✓ Test Matrix     → Python 3.11-3.14 × (Ubuntu, macOS, Windows)\n✓ Linux Distros   → Ubuntu, Debian, Fedora, openSUSE, Arch, Alpine\n✓ Code Quality    → Ruff check \u0026 format\n✓ Type Check      → Mypy strict mode\n✓ Security        → Bandit + Semgrep (custom rules)\n✓ Architecture    → Import Linter contracts\n✓ Benchmarks      → Performance regression (\u003e5% = fail)\n✓ SBOM + SLSA     → Supply-chain attestation on release\n```\n\n---\n\n## 📚 API Highlights\n\n### Result Types (Rust-Style Error Handling)\n\n```python\nfrom taipanstack.core.result import Result, Ok, Err, safe\n\n@safe\ndef divide(a: int, b: int) -\u003e float:\n    return a / b\n\n# Explicit error handling with pattern matching\nmatch divide(10, 0):\n    case Ok(value):\n        print(f\"Result: {value}\")\n    case Err(error):\n        print(f\"Error: {error}\")\n```\n\n### Security Guards\n\n```python\nfrom taipanstack.security.guards import guard_path_traversal, guard_command_injection\n\n# Prevent path traversal attacks\nsafe_path = guard_path_traversal(user_input, base_dir=\"/app/data\")\n\n# Prevent command injection\nsafe_cmd = guard_command_injection(\n    [\"git\", \"clone\", repo_url],\n    allowed_commands=[\"git\"]\n)\n```\n\n### Retry with Exponential Backoff\n\n```python\nfrom taipanstack.resilience.retry import retry\n\n@retry(max_attempts=3, on=(ConnectionError, TimeoutError))\nasync def fetch_data(url: str) -\u003e dict:\n    return await http_client.get(url)\n```\n\n### Circuit Breaker\n\n```python\nfrom taipanstack.resilience.circuit_breaker import circuit_breaker\n\n@circuit_breaker(failure_threshold=5, timeout=30)\ndef call_external_service() -\u003e Response:\n    return service.call()\n```\n\n### 🔗 Combining Result + Circuit Breaker\n\n```python\nfrom taipanstack.core.result import safe, Ok, Err\nfrom taipanstack.resilience.circuit_breaker import CircuitBreaker\n\nbreaker = CircuitBreaker(failure_threshold=3, timeout=60, name=\"payments\")\n\n@breaker\n@safe\ndef charge_customer(customer_id: str, amount: float) -\u003e dict:\n    return payment_gateway.charge(customer_id, amount)\n\n# Both circuit protection AND explicit error handling\nresult = charge_customer(\"cust_123\", 49.99)\nmatch result:\n    case Ok(receipt):\n        print(f\"Payment successful: {receipt}\")\n    case Err(error):\n        print(f\"Payment failed safely: {error}\")\n```\n\n### 🔗 Combining Result + Retry with Monitoring\n\n```python\nfrom taipanstack.core.result import safe, unwrap_or\nfrom taipanstack.resilience.retry import retry\n\n@retry(\n    max_attempts=3,\n    on=(ConnectionError, TimeoutError),\n    on_retry=lambda attempt, max_a, exc, delay: print(\n        f\"⚠️  Attempt {attempt}/{max_a} failed, retrying in {delay:.1f}s...\"\n    ),\n)\n@safe\ndef fetch_user_profile(user_id: str) -\u003e dict:\n    return api_client.get(f\"/users/{user_id}\")\n\n# Retry handles transient failures, Result handles business errors\nprofile = unwrap_or(fetch_user_profile(\"usr_456\"), {\"name\": \"Unknown\"})\n```\n\n### 🔗 Adaptive Resilience Pipeline\n\n```python\nfrom taipanstack.core.result import Result, Ok, Err\nfrom taipanstack.resilience.adaptive import ResilienceOrchestrator, AdaptiveCircuitBreaker\nfrom taipanstack.resilience.retry import RetryConfig\n\n# Compose an intelligent pipeline: Bulkhead -\u003e Breaker -\u003e Retry -\u003e Timeout -\u003e Fallback\norch = (\n    ResilienceOrchestrator(\"billing_api\")\n    .with_bulkhead(max_concurrent=10, max_queue=50) # Prevent resource exhaustion\n    .with_circuit_breaker(AdaptiveCircuitBreaker(\"billing\", target_error_rate=0.1)) # Auto-tunes thresholds\n    .with_retry(RetryConfig(max_attempts=3, initial_delay=0.1))\n    .with_fallback({\"status\": \"unavailable\"})\n)\n\nasync def process_billing() -\u003e Result[dict, Exception]:\n    # The orchestrator handles all concurrency, retry, circuit breaking, and fallbacks\n    return await orch.execute(stripe_gateway.charge)\n```\n\n### Intelligent Caching\n\n```python\nfrom taipanstack.utils.cache import cached\nfrom taipanstack.core.result import Result\n\n@cached(ttl=60)\nasync def get_user_data(user_id: int) -\u003e Result[dict, Exception]:\n    return await db.fetch(user_id) # Only Ok() results are cached\n```\n\n### Fallbacks \u0026 Timeouts\n\n```python\nfrom taipanstack.resilience.resilience import fallback, timeout\nfrom taipanstack.core.result import Result\n\n@fallback({\"status\": \"offline\"}, exceptions=(TimeoutError,))\n@timeout(seconds=5.0)\nasync def fetch_remote_status() -\u003e Result[dict, Exception]:\n    return await api.get_status()\n```\n\n---\n\n## 🐳 Docker\n\n```bash\n# Build hardened image\ndocker build -t taipanstack:latest .\n\n# Run (rootless, read-only)\ndocker run --rm --read-only taipanstack:latest\n```\n\nSecurity features: multi-stage build, Alpine base (\u003c50MB), non-root `appuser` (UID 1000), healthcheck, no shell in runtime.\n\n---\n\n## 🛠️ Tech Stack\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eRuntime\u003c/th\u003e\n\u003cth\u003eQuality\u003c/th\u003e\n\u003cth\u003eDevSecOps\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n- Pydantic v2\n- Orjson\n- Uvloop\n- Structlog\n- Result\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n- Ruff\n- Mypy\n- Bandit\n- Pytest + Hypothesis\n- mutmut\n- pytest-benchmark\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n- GitHub Actions\n- Syft + Cosign (SBOM/SLSA)\n- Dependabot\n- Pre-commit\n- Poetry\n- Docker (Alpine, rootless)\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please check our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- 🐛 Bug reports\n- ✨ Feature requests\n- 📝 Documentation improvements\n- 🔧 Pull requests\n\n---\n\n## 📝 License\n\nThis project is open-sourced under the [MIT License](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ for the Python community**\n\n[⬆ Back to Top](#-taipanstack)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielima7%2Ftaipanstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabrielima7%2Ftaipanstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielima7%2Ftaipanstack/lists"}