hdmi 0.2.0__tar.gz → 0.2.2__tar.gz

hdmi-0.2.2/.github/workflows/cicd.yml

@@ -0,0 +1,256 @@
+name: CI/CD
+
+on:
+  push:
+    branches:
+      - '**'
+    tags:
+      - '*.*.*'      # Semantic version tags (e.g., 0.1.0)
+      - '*.*.*-*'    # Pre-release tags (e.g., 0.1.0-rc1, 0.1.0-beta.1)
+  pull_request:
+
+permissions:
+  contents: write   # Required for creating GitHub releases
+  id-token: write   # Required for trusted publishing to PyPI
+
+jobs:
+  test:
+    name: Test (Py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.13']
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras
+
+      - name: Run linting
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Run type checking
+        run: uv run basedpyright
+
+      - name: Run tests
+        run: uv run pytest --cov=hdmi --cov-report=xml --cov-report=term
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+
+  build-python-package:
+    name: Build Python Package
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version
+        id: version
+        run: |
+          if [ "${{ github.ref_type }}" = "tag" ]; then
+            VERSION=${GITHUB_REF#refs/tags/}
+            echo "Building release version: $VERSION"
+          else
+            VERSION=$(git describe --tags --always --dirty)
+            echo "Building development version: $VERSION"
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Validate version matches tag
+        if: github.ref_type == 'tag'
+        run: |
+          TAG_VERSION="${{ steps.version.outputs.version }}"
+          # Extract version from __init__.py (dynamic versioning via hatch)
+          PACKAGE_VERSION=$(grep -E '^__version__ = ' src/hdmi/__init__.py | sed -E 's/__version__ = "(.+)"/\1/')
+          echo "Tag version: $TAG_VERSION"
+          echo "Package version: $PACKAGE_VERSION"
+          if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
+            echo "❌ Error: Tag version ($TAG_VERSION) does not match package version ($PACKAGE_VERSION)"
+            exit 1
+          fi
+          echo "✅ Version validation passed"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Install dependencies for validation
+        run: uv sync --all-extras
+
+      - name: Check package
+        run: uv run twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          retention-days: 7
+
+  all-checks-passed:
+    name: All Checks Passed
+    needs:
+      - build-python-package
+      - test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: All checks passed
+        run: echo "✅ All tests and package builds completed successfully"
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          allow-prereleases: true
+
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Test wheel installation
+        run: |
+          WHEEL=$(ls dist/*.whl)
+          echo "Testing wheel: $WHEEL"
+          uv pip install --system "$WHEEL"
+          python -c "import hdmi; print(f'hdmi installation successful')"
+          python -c "import sys; print(f'Python: {sys.version}')"
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    needs: all-checks-passed
+    runs-on: ubuntu-latest
+    if: github.ref_type == 'tag'
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/hdmi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: publish-to-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hdmi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-github-release:
+    name: Create GitHub Release
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Version: $VERSION"
+
+      - name: Create release notes
+        run: |
+          cat > release-notes.md <<EOF
+          # Release ${{ steps.version.outputs.version }}
+
+          This release was automatically created from tag ${{ github.ref_name }}.
+
+          ## Installation
+
+          \`\`\`bash
+          pip install hdmi==${{ steps.version.outputs.version }}
+          \`\`\`
+
+          See the [documentation](https://github.com/${{ github.repository }}) for more information.
+          EOF
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: release-notes.md
+          files: dist/*
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-beta') || contains(github.ref_name, '-alpha') }}

hdmi-0.2.2/.gitignore

@@ -0,0 +1,43 @@
+# OS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+*.so
+.venv/
+.python-version
+
+# Testing & Coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.hypothesis/
+
+# IDEs
+.idea/
+.vscode/
+*.iml
+
+# Build outputs
+build/
+dist/
+wheels/
+*.whl
+
+# Documentation
+docs/_build/
+
+# Type checkers
+.mypy_cache/
+.pytype/
+.pyre/
+.ruff_cache/
+
+# Claude Code
+.claude/*
+!.claude/commands/

hdmi-0.2.2/.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Install the package with documentation dependencies
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev

hdmi-0.2.2/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial implementation of dependency injection framework with type-driven configuration
+- `ContainerBuilder` for service registration with lifecycle scopes
+- `Container` for lazy service resolution at runtime
+- Automatic dependency discovery from Python type annotations
+- Comprehensive Sphinx documentation organized using Diátaxis framework
+- Support for multi-level dependency chains with recursive resolution
+- `IContainer` protocol for consistent container interface
+- Static type checking with basedpyright
+- `ServiceDefinition` class for declarative service configuration with optional factory and name support
+- Support for custom factory functions to control service instantiation
+- Named service registration for future multi-registration support
+- **Scoped Transient services** - new service type requiring scope context but creating fresh instances per request
+- Async container support with concurrent dependency resolution
+- Service lifecycle hooks (initializers and finalizers)
+- Task deduplication for diamond dependency patterns
+- Boolean-based scope API with `scoped` and `transient` flags
+- Circular dependency detection at build time with descriptive error messages showing the cycle path
+
+### Changed
+
+- Reorganized container implementation into `hdmi.containers` package for better modularity
+- `ServiceDefinition` is now exported from main `hdmi` package for direct usage
+- `ContainerBuilder.register()` now raises `ValueError` when both `ServiceDefinition` and `scope` parameter are provided
+- `UnresolvableDependencyError` now extends `KeyError` for backward compatibility while providing clearer error messages
+- Container resolution failures now raise `UnresolvableDependencyError` instead of raw `KeyError` with helpful guidance on how to fix the issue
+- **BREAKING**: Replaced string-based `scope` parameter with boolean flags `scoped` and `transient` in `ContainerBuilder.register()`
+  - Before: `builder.register(Service, scope="singleton|scoped|transient")`
+  - After: `builder.register(Service, scoped=True/False, transient=True/False)`
+- **BREAKING**: Relaxed scope validation - singleton and scoped services can now depend on transient services
+  - Transient dependencies are instantiated once during dependent's construction
+  - Only restriction: non-scoped services cannot depend on scoped services
+- Reorganized package structure: `ServiceDefinition` moved to `hdmi.types.definitions`, type utilities to `hdmi.utils.typing`

hdmi-0.2.2/CLAUDE.md

@@ -0,0 +1,198 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**hdmi** is a dependency injection framework for Python that manages dynamic dependencies with late (just-in-time)
+resolution. The framework provides:
+
+- Late-binding dependency resolution (instantiated only when needed)
+- Type-annotation-based configuration using Python's standard typing system
+- Scope-aware dependency validation (singleton, scoped, transient)
+- Early error detection at build time (before runtime)
+
+## Development Setup
+
+This project uses **uv** for dependency management and **pytest** for testing.
+
+### Common Commands
+
+**Quick Testing (pytest only):**
+```bash
+# Run only pytest tests (no linting or type checking)
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_filename.py
+
+# Run a specific test
+uv run pytest tests/test_filename.py::test_function_name
+
+# Run tests with verbose output
+uv run pytest -v
+
+# Run tests with coverage
+uv run pytest --cov=hdmi --cov-report=html
+```
+
+**Full Quality Checks (recommended for commits):**
+```bash
+# Run all checks: linting, formatting, type checking, and tests
+make test
+
+# Run with verbose test output
+make test TEST_VERBOSE=1
+
+# Run with coverage report
+make test TEST_COVERAGE=1
+
+# Show all available make targets
+make help
+```
+
+## Development Methodology
+
+**This project strictly follows Test-Driven Development (TDD).**
+
+All code must be developed using the Red-Green-Refactor cycle:
+
+1. **Red**: Write a failing test that describes the desired behavior
+2. **Green**: Write the minimum code necessary to make the test pass
+3. **Refactor**: Improve the code structure while keeping tests green
+
+**Key TDD Principles:**
+- Never write production code without a failing test first
+- Write only enough code to make the current test pass
+- Tests define the specification and behavior of the system
+- Each commit should include both tests and implementation
+
+**Testing Guidelines:**
+- Tests should be behavioral and describe what the code does, not how it does it
+- Use descriptive test names that explain the expected behavior
+- Keep tests focused on a single behavior
+- **Tests directory structure MUST mirror the Python package structure**:
+  - For `src/hdmi/module.py`, tests go in `tests/test_module.py`
+  - For `src/hdmi/subpackage/module.py`, tests go in `tests/subpackage/test_module.py`
+  - Maintain the same package hierarchy in tests as in src
+  - This ensures tests are organized, discoverable, and maintainable
+
+### Commit Guidelines
+
+**ALWAYS run `make test` before committing** to ensure all quality checks pass (linting, type checking, and tests).
+
+**Commit Message Best Practices:**
+- Focus on **what changed and why** for the user, not implementation details
+- Use conventional commits format: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`
+- **NEVER mention tests passing or coverage** in commit messages
+  - Tests passing is a prerequisite for all commits (enforced by `make test`)
+  - This information adds no value to the commit history
+- Keep messages concise and user-focused
+- Example: `feat: add scope validation for dependency graph` (good)
+- Example: `feat: add scope validation with tests passing at 95% coverage` (bad - unnecessary noise)
+
+## Documentation
+
+All features and architecture must be documented in the `docs/` directory using **Sphinx** and organized according to the **Diátaxis framework**.
+
+### Diátaxis Framework
+
+Documentation is organized into four categories:
+
+1. **Tutorials** (`docs/tutorials/`): Learning-oriented guides that help newcomers learn by doing
+   - Step-by-step instructions
+   - Complete working examples
+   - Assumes little prior knowledge
+
+2. **How-To Guides** (`docs/how-to/`): Goal-oriented guides for solving specific problems
+   - Focused on accomplishing specific tasks
+   - Assumes basic knowledge
+   - Practical and actionable
+
+3. **Reference** (`docs/reference/`): Information-oriented technical descriptions
+   - API documentation
+   - Complete and accurate technical details
+   - Generated from docstrings where appropriate
+
+4. **Explanation** (`docs/explanation/`): Understanding-oriented discussions
+   - Architecture and design decisions
+   - Conceptual background
+   - Why things are the way they are
+
+### Documentation Commands
+
+```bash
+# Build documentation
+make docs
+
+# Build and watch for changes (auto-rebuild on file changes)
+make docs-watch
+
+# Clean all build artifacts (including docs)
+make clean
+```
+
+## Architecture
+
+**hdmi** follows a two-phase architecture: **ContainerBuilder → Container**
+
+### Two-Phase Flow
+
+1. **ContainerBuilder** (Configuration Phase)
+   - Register service types and their dependencies
+   - Define lifecycles (singleton, scoped, transient)
+   - Configure using Python type annotations
+   - Mutable: can add/modify service definitions
+
+2. **Container** (Validation & Runtime Phase)
+   - Built from ContainerBuilder via `.build()`
+   - Validates the dependency graph (no cycles, all resolvable, scope-safe)
+   - Checks type compatibility and scope hierarchies
+   - Immutable: dependency graph is frozen
+   - Used at runtime to resolve service instances via `.get(ServiceType)`
+   - Services created lazily (just-in-time) when first requested
+
+### Example Flow
+
+```python
+# Phase 1: Configuration
+builder = ContainerBuilder()
+builder.register(DatabaseConnection)  # singleton (default)
+builder.register(UserRepository, scoped=True)     # scoped service
+builder.register(UserService, transient=True)      # transient service
+
+# Phase 2: Build & Runtime
+container = builder.build()  # validates graph, no instantiation yet
+
+# Service resolution (lazy instantiation)
+user_service = container.get(UserService)  # creates all dependencies on-demand
+```
+
+### Core Concepts
+
+1. **Type-Driven Dependencies**: Python type annotations define the dependency graph automatically
+
+2. **Scope Hierarchy & Validation**: Services can only depend on services in the same or higher scope
+   - **Singleton** (highest): One instance per container, lives for container lifetime
+   - **Scoped** (middle): One instance per scope (e.g., per web request)
+   - **Transient** (lowest): New instance every time it's requested
+
+   Validation rules:
+   - Singleton services can only depend on other singleton services
+   - Scoped services can depend on singleton or scoped services
+   - Transient services can depend on any scope
+
+3. **Late Resolution**: Services instantiated just-in-time, not eagerly (see `docs/explanation/why-late-binding.rst`)
+
+4. **Early Validation**: Configuration errors (cycles, missing deps, scope violations) caught at `.build()` time
+
+5. **Immutable Containers**: Once built, the dependency graph cannot be modified
+
+### Design Principles
+
+- **Fail Fast, Run Lazy**: Validate early (scope violations, cycles), instantiate late
+- **Type Annotations as Truth**: No separate configuration required
+- **Scope Safety**: Compile-time prevention of scope-related lifetime bugs
+- **Simplicity by Design**: Two core concepts (ContainerBuilder, Container), one clear workflow
+- **No External DSL**: Pure Python, no YAML/XML required (unlike harp/rodi)
+- **Minimal Overhead**: Lightweight and fast

hdmi-0.2.2/Makefile

@@ -0,0 +1,70 @@
+.PHONY: test install install-dev check docs docs-watch clean wheel help
+
+UV ?= $(shell command -v uv 2>/dev/null || echo "uv")
+RUN ?= $(UV) run
+TEST_VERBOSE ?=
+TEST_COVERAGE ?=
+
+# helpers
+define execute
+@echo "⚙️ \033[36m$@\033[0m: \033[2m$(1)\033[0m"
+@$(1)
+endef
+
+help:  ## Show available commands
+	@echo "Available commands:"
+	@echo
+	@echo "\033[1mDevelopment\033[0m"
+	@grep -E '^(install|install-dev):.*?##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?##"}; {printf "    make \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo "\033[1mTesting & Quality\033[0m"
+	@grep -E '^(test|check):.*?##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?##"}; {printf "    make \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo "\033[1mDocumentation\033[0m"
+	@grep -E '^(docs|docs-watch):.*?##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?##"}; {printf "    make \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo "\033[1mBuild\033[0m"
+	@grep -E '^(wheel):.*?##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?##"}; {printf "    make \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo "\033[1mCleanup\033[0m"
+	@grep -E '^(clean):.*?##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?##"}; {printf "    make \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+
+install:  ## Install dependencies (without dev tools)
+	$(call execute,$(UV) sync)
+
+install-dev:  ## Install dependencies with dev tools
+	$(call execute,$(UV) sync --extra dev)
+
+check: install-dev  ## Check and fix code with ruff (lint + format)
+	$(call execute,$(RUN) ruff check --fix .)
+	$(call execute,$(RUN) ruff format .)
+	$(call execute,$(RUN) basedpyright)
+
+test: install-dev check  ## Run all tests
+	$(call execute,$(RUN) pytest $(if $(TEST_VERBOSE),--verbose,) $(if $(TEST_COVERAGE),--cov=hdmi --cov-report=html --cov-report=term,))
+
+docs: install-dev  ## Build documentation with Sphinx
+	$(call execute,$(RUN) sphinx-build -b html docs docs/_build/html)
+
+docs-watch: install-dev  ## Build documentation and watch for changes
+	$(call execute,$(RUN) sphinx-autobuild docs docs/_build/html --watch src)
+
+clean:  ## Clean up temporary files
+	rm -rf .pytest_cache
+	rm -rf htmlcov
+	rm -rf .coverage
+	rm -rf docs/_build
+	rm -rf dist
+	rm -rf build
+	rm -rf *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+wheel: test clean  ## Build and check wheel for PyPI distribution
+	$(call execute,$(UV) build)
+	$(call execute,$(RUN) twine check dist/*)
+	@echo ""
+	@echo "Wheel built and validated successfully!"
+	@echo "Files ready for upload:"
+	@ls -lh dist/