mp-commons 0.2.0__tar.gz

mp_commons-0.2.0/.devcontainer/devcontainer.json

@@ -0,0 +1,64 @@
+{
+  "name": "mp-commons Dev Container",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+
+  // Install uv + project dependencies on container creation
+  "onCreateCommand": "curl -LsSf https://astral.sh/uv/install.sh | sh && /root/.cargo/bin/uv pip install -e '.[dev]'",
+
+  // Start required Docker-in-Docker services for integration tests
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {
+      "version": "latest",
+      "enableNonRootDocker": "true"
+    },
+    "ghcr.io/devcontainers/features/git:1": {}
+  },
+
+  // VS Code extensions — Python tooling and database viewers
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "ms-python.mypy-type-checker",
+        "cweijan.vscode-redis-client",
+        "cweijan.vscode-postgresql-client2",
+        "eamodio.gitlens",
+        "github.vscode-pull-request-github"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/root/.venv/bin/python",
+        "editor.formatOnSave": true,
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff",
+          "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "explicit",
+            "source.organizeImports.ruff": "explicit"
+          }
+        },
+        "mypy-type-checker.args": ["--config-file=pyproject.toml"],
+        "ruff.args": ["--config=pyproject.toml"]
+      }
+    }
+  },
+
+  // Expose common service ports for local development
+  "forwardPorts": [
+    8000,   // uvicorn (example service)
+    5432,   // PostgreSQL
+    6379,   // Redis
+    9200,   // Elasticsearch
+    9000,   // MinIO
+    9092,   // Kafka
+    4222,   // NATS
+    5672    // RabbitMQ
+  ],
+
+  // Run infrastructure services via docker-compose
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "app",
+  "workspaceFolder": "/workspace",
+
+  "postCreateCommand": "echo 'Dev container ready. Run: make test-unit'"
+}

mp_commons-0.2.0/.devcontainer/docker-compose.yml

@@ -0,0 +1,84 @@
+version: "3.9"
+
+# Development infrastructure for mp-commons local development.
+# All services are optional — comment out what you don't need.
+# Start with: docker compose -f .devcontainer/docker-compose.yml up -d
+
+services:
+  app:
+    image: mcr.microsoft.com/devcontainers/python:1-3.12-bullseye
+    volumes:
+      - ..:/workspace:cached
+    command: sleep infinity
+    environment:
+      DATABASE_URL: "postgresql+asyncpg://dev:dev@postgres:5432/devdb"
+      REDIS_URL: "redis://redis:6379/0"
+      ELASTICSEARCH_URL: "http://elasticsearch:9200"
+      KAFKA_BOOTSTRAP_SERVERS: "kafka:9092"
+      NATS_URL: "nats://nats:4222"
+
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: devdb
+      POSTGRES_USER: dev
+      POSTGRES_PASSWORD: dev
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+
+  elasticsearch:
+    image: elasticsearch:8.13.0
+    restart: unless-stopped
+    environment:
+      discovery.type: single-node
+      ES_JAVA_OPTS: "-Xms512m -Xmx512m"
+      xpack.security.enabled: "false"
+    ports:
+      - "9200:9200"
+
+  minio:
+    image: minio/minio:latest
+    restart: unless-stopped
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    volumes:
+      - minio-data:/data
+
+  kafka:
+    image: bitnami/kafka:3.7
+    restart: unless-stopped
+    environment:
+      KAFKA_CFG_NODE_ID: 0
+      KAFKA_CFG_PROCESS_ROLES: controller,broker
+      KAFKA_CFG_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
+      KAFKA_CFG_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
+      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
+      KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "0@kafka:9093"
+      KAFKA_CFG_CONTROLLER_LISTENER_NAMES: CONTROLLER
+    ports:
+      - "9092:9092"
+
+  nats:
+    image: nats:2.10-alpine
+    restart: unless-stopped
+    ports:
+      - "4222:4222"
+      - "8222:8222"  # NATS monitoring
+
+volumes:
+  postgres-data:
+  minio-data:

mp_commons-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: "🐛 Bug Report"
+description: "Report a reproducible bug in mp-commons."
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to file a bug report.
+        Please fill in as much detail as possible to help us reproduce and fix the issue quickly.
+
+  - type: input
+    id: version
+    attributes:
+      label: "mp-commons version"
+      placeholder: "e.g. 0.3.1"
+    validations:
+      required: true
+
+  - type: input
+    id: python_version
+    attributes:
+      label: "Python version"
+      placeholder: "e.g. 3.12.3"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: "Bug description"
+      description: "A clear and concise description of what the bug is."
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: "Minimal reproduction"
+      description: "Paste a minimal code snippet or steps that reliably reproduce the issue."
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: "Expected behaviour"
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: "Actual behaviour"
+      description: "Include the full traceback if available."
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: "Additional context"
+      description: "Any other relevant information (OS, extras installed, related issues)."

mp_commons-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: "📖 Documentation"
+    url: "https://github.com/marcusPrado02/python-commons/tree/main/docs"
+    about: "Browse architecture docs and ADRs."

mp_commons-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,55 @@
+name: "✨ Feature Request"
+description: "Propose a new feature or enhancement for mp-commons."
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement!
+        Please describe the problem you need to solve and the solution you have in mind.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: "Problem statement"
+      description: "What problem does this feature solve? What are you trying to achieve?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: "Proposed solution"
+      description: "Describe the API or behaviour you'd like to see, ideally with a code example."
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: "Alternatives considered"
+      description: "Have you tried any workarounds? What other approaches did you consider?"
+
+  - type: dropdown
+    id: layer
+    attributes:
+      label: "Affected layer"
+      options:
+        - "kernel"
+        - "application"
+        - "resilience"
+        - "observability"
+        - "config"
+        - "adapter"
+        - "testing"
+        - "packaging / CI"
+        - "other"
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: "Additional context"
+      description: "Links to relevant ADRs, issues, or external references."

mp_commons-0.2.0/.github/dependabot.yml

@@ -0,0 +1,34 @@
+version: 2
+
+updates:
+  # Python dependencies (pip ecosystem — covers pyproject.toml extras)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "08:00"
+      timezone: "America/Sao_Paulo"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "python"
+    ignore:
+      # Only accept patch/minor updates automatically for major adapters
+      - dependency-name: "fastapi"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "sqlalchemy"
+        update-types: ["version-update:semver-major"]
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "08:00"
+      timezone: "America/Sao_Paulo"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"

mp_commons-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,48 @@
+## Summary
+
+<!-- What does this PR do? One or two sentences. -->
+
+Closes #<!-- issue number -->
+
+---
+
+## Type of change
+
+- [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
+- [ ] ✨ New feature (non-breaking change that adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] ♻️ Refactoring (no functional change)
+- [ ] 📝 Documentation / comments
+- [ ] 🔧 CI / build / tooling
+
+---
+
+## Changes
+
+<!--
+A concise bullet list of what changed and why.
+Include affected modules (e.g. kernel/ddd, adapters/fastapi).
+-->
+
+-
+-
+
+---
+
+## Testing
+
+- [ ] I added or updated unit tests that cover my changes
+- [ ] I added or updated integration tests where applicable
+- [ ] All existing tests pass locally (`make test`)
+- [ ] Type-checked with mypy (`make typecheck`)
+- [ ] Linted with ruff (`make lint`)
+
+---
+
+## Checklist
+
+- [ ] My code follows the project's [Architecture Principles](docs/architecture/)
+- [ ] I updated `CHANGELOG.md` under `[Unreleased]`
+- [ ] `kernel.*` imports only stdlib (no new external deps added to the kernel)
+- [ ] New public symbols are exported via the relevant `__init__.py` `__all__`
+- [ ] I have read and agree to the **CONTRIBUTING.md** guidelines

mp_commons-0.2.0/.github/release-drafter.yml

@@ -0,0 +1,65 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+
+categories:
+  - title: '🚀 Features'
+    labels:
+      - 'feat'
+      - 'feature'
+  - title: '🐛 Bug Fixes'
+    labels:
+      - 'fix'
+      - 'bugfix'
+  - title: '💥 Breaking Changes'
+    labels:
+      - 'breaking'
+      - 'breaking-change'
+  - title: '🧪 Tests'
+    labels:
+      - 'test'
+      - 'tests'
+  - title: '🔧 Maintenance & Chores'
+    labels:
+      - 'chore'
+      - 'maintenance'
+      - 'ci'
+      - 'dependencies'
+  - title: '📚 Documentation'
+    labels:
+      - 'docs'
+      - 'documentation'
+  - title: '⚡ Performance'
+    labels:
+      - 'performance'
+      - 'perf'
+
+change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
+change-title-escapes: '\<*_&'
+
+version-resolver:
+  major:
+    labels:
+      - 'breaking'
+      - 'breaking-change'
+  minor:
+    labels:
+      - 'feat'
+      - 'feature'
+  patch:
+    labels:
+      - 'fix'
+      - 'bugfix'
+      - 'chore'
+      - 'docs'
+      - 'test'
+      - 'dependencies'
+      - 'ci'
+  default: patch
+
+template: |
+  ## Changes
+
+  $CHANGES
+
+  ---
+  *Full Changelog*: https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...v$RESOLVED_VERSION

mp_commons-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,169 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "develop"]
+    tags: ["v*"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint & Type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v2
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dev deps
+        run: uv sync --extra dev
+      - name: ruff check
+        run: uv run ruff check src tests
+      - name: ruff format (check)
+        run: uv run ruff format --check src tests
+      - name: mypy
+        run: uv run mypy src
+
+  test:
+    name: Tests – Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dev deps
+        run: uv sync --extra dev
+      - name: Run unit tests
+        run: |
+          uv run pytest tests/unit -x -q \
+            --cov=src/mp_commons \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            -m "not integration"
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  integration:
+    # C-01 — Full integration test suite.
+    # PostgreSQL and Redis are provided as sidecar services.
+    # All other adapters (Elasticsearch, S3/MinIO, DynamoDB, Cassandra,
+    # Redis Streams, Pulsar, MongoDB, etc.) are spun up on-demand by
+    # testcontainers-python — Docker is available on ubuntu-latest runners.
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    needs: [test]
+    services:
+      redis:
+        image: redis:7-alpine
+        ports: ["6379:6379"]
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_DB: test
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v2
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+      - name: Install dev deps
+        run: uv sync --extra dev
+      - name: Run integration tests
+        env:
+          DATABASE_URL: "postgresql+asyncpg://test:test@localhost:5432/test"
+          REDIS_URL: "redis://localhost:6379/0"
+          # testcontainers-python manages all other service containers automatically
+          TESTCONTAINERS_RYUK_DISABLED: "false"
+        run: uv run pytest tests/integration -x -q -m integration
+
+  security:
+    name: Security Scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v2
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: bandit
+        run: uvx bandit -r src -c pyproject.toml
+      - name: pip-audit
+        run: uvx pip-audit
+
+  mutation:
+    name: Mutation Testing (opt-in)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v2
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dev deps + mutmut
+        run: |
+          uv sync --extra dev
+          uvx --with mutmut mutmut --version
+      - name: Run unit tests to build coverage baseline
+        run: |
+          uv run pytest tests/unit -q \
+            --cov=src/mp_commons \
+            --cov-report=xml \
+            -m "not integration"
+      - name: Run mutation testing
+        run: |
+          uv run mutmut run --use-coverage
+          uv run mutmut results
+      - name: Check mutation score
+        run: |
+          SCORE=$(uv run mutmut results | grep -oP 'Survived: \K\d+')
+          KILLED=$(uv run mutmut results | grep -oP 'Killed: \K\d+')
+          TOTAL=$((SCORE + KILLED))
+          if [ "$TOTAL" -eq 0 ]; then
+            echo "No mutations generated" && exit 0
+          fi
+          PCT=$((KILLED * 100 / TOTAL))
+          echo "Mutation score: ${PCT}% (killed ${KILLED}/${TOTAL})"
+          if [ "$PCT" -lt 80 ]; then
+            echo "ERROR: Mutation score ${PCT}% is below the 80% threshold" && exit 1
+          fi
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write   # create GitHub release assets
+      id-token: write   # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v2
+      - name: Build
+        run: uv build
+      - name: Generate SBOM (CycloneDX JSON)
+        run: uvx --from cyclonedx-bom cyclonedx-py environment --output-format json -o sbom.json
+      - name: Upload SBOM as release asset
+        uses: softprops/action-gh-release@v2
+        with:
+          files: sbom.json
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mp_commons-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Docs
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Build docs (strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v2
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install deps
+        run: uv sync --extra dev
+      - name: mkdocs build --strict
+        run: uv run mkdocs build --strict
+
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: [lint]
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v2
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install deps
+        run: uv sync --extra dev
+      - name: Configure Git for gh-deploy
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Deploy to GitHub Pages
+        run: uv run mkdocs gh-deploy --force

mp_commons-0.2.0/.github/workflows/release-drafter.yml

@@ -0,0 +1,21 @@
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update_release_draft:
+    name: Draft Next Release Notes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: release-drafter/release-drafter@v6
+        with:
+          config-name: release-drafter.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}