Repository: davideme/lamp-control-api-reference
Pull request #49: feat: Python implementation initial setup
Author: login: davideme
Created: 2025-04-19T21:18:11Z | Merged: 2025-04-20T08:57:54Z

This PR sets up the initial structure for the Python implementation of the Lamp Control API.

### Changes

#### Project Structure
- Created basic Python package structure (`lamp_control/`)
- Set up test directory structure mirroring the main package
- Added necessary `__init__.py` files

#### Configuration
- Added `pyproject.toml` with project metadata and tool configurations
- Configured development tools:
  - black for code formatting
  - ruff for linting
  - mypy for type checking
  - pytest for testing

#### Dependency Management
- Added `requirements.txt` with core dependencies
- Added `requirements-dev.txt` for development tools
- Selected modern, stable versions of all dependencies

#### Documentation
- Added ADR-010 documenting Python version selection (3.12)
- Created comprehensive README with setup instructions
- Added development workflow documentation

#### CI/CD
- Added GitHub Actions workflow for:
  - Running tests
  - Code quality checks
  - Coverage reporting
  - Multiple database support (PostgreSQL and MongoDB)

### Testing
The CI pipeline will automatically run:
- Unit tests with pytest
- Code formatting check with black
- Linting with ruff
- Type checking with mypy
- Test coverage reporting

### Next Steps
1. Implement core domain models
2. Set up database models and migrations
3. Implement REST API endpoints
4. Add GraphQL support
5. Add gRPC support

### Checklist
- [x] Added ADR for Python version selection
- [x] Set up project structure
- [x] Configured development tools
- [x] Added CI pipeline
- [x] Updated documentation
- [x] Included test structure


Diff:
diff --git a/.github/workflows/python-ci.yml b/.github/workflows/python-ci.yml
new file mode 100644
index 00000000..0375a3cc
--- /dev/null
+++ b/.github/workflows/python-ci.yml
@@ -0,0 +1,91 @@
+name: Python CI
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'src/python/**'
+      - '.github/workflows/python-ci.yml'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'src/python/**'
+      - '.github/workflows/python-ci.yml'
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
+      issues: write
+      pull-requests: write    
+    defaults:
+      run:
+        working-directory: src/python
+    strategy:
+      matrix:
+        python-version: ['3.12']
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_DB: lamp_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      mongodb:
+        image: mongo:7
+        ports:
+          - 27017:27017
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: 'src/python/requirements*.txt'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements-dev.txt
+
+    - name: Auto-format code
+      run: |
+        black .
+        ruff check . --fix
+
+    - uses: reviewdog/action-suggester@v1
+      with:
+        tool_name: black and ruff
+        # fail_level: error      
+
+    - name: Run code quality checks
+      run: |
+        black . --check --diff
+        ruff check . --diff
+        mypy .
+
+    - name: Run tests
+      env:
+        POSTGRES_HOST: localhost
+        POSTGRES_PORT: 5432
+        POSTGRES_USER: postgres
+        POSTGRES_PASSWORD: postgres
+        POSTGRES_DB: lamp_test
+        MONGODB_URI: mongodb://localhost:27017/lamp_test
+      run: |
+        pytest --cov=lamp_control --cov-report=xml
diff --git a/README.md b/README.md
index de4d6633..54642e75 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,8 @@ For the Node.js/TypeScript implementation, the following versions are required:
 
 Refer to [ADR-002](docs/adr/002-nodejs-and-npm-versions.md) for details.
 
+For the Python implementation requirements, see [Python README](src/python/README.md).
+
 ## Documentation
 
 For full details on the project requirements and specifications, see the [Product Requirements Document](docs/PRD.md).
diff --git a/docs/adr/010-python-version.md b/docs/adr/010-python-version.md
new file mode 100644
index 00000000..5a4fa6ac
--- /dev/null
+++ b/docs/adr/010-python-version.md
@@ -0,0 +1,121 @@
+# ADR-010: Python Version Selection
+
+## Status
+
+Accepted
+
+## Context
+
+For the Python implementation of the Lamp Control API, we need to select an appropriate Python version that balances modern features, long-term support, and ecosystem compatibility. The decision impacts development efficiency, maintainability, and future-proofing of the codebase.
+
+## Decision
+
+We will use Python 3.12 as the primary Python version for this project, with a minimum version requirement of 3.12.9.
+
+Key factors influencing this decision:
+
+1. **Support Timeline**
+   - Released: October 2023
+   - Security Support Until: October 2028
+   - Provides 3.5 years of remaining security maintenance
+
+2. **Technical Benefits**
+   - ~5% performance improvement over Python 3.11
+   - Enhanced error messages for better debugging
+   - Improved type annotation syntax and checking
+   - Better f-string parsing capabilities
+   - Enhanced debugging and profiling API
+   - Support for the buffer protocol
+
+3. **Ecosystem Compatibility**
+   - Wide adoption by major libraries and frameworks
+   - Mature tooling support
+   - Active security maintenance
+   - Strong type checking capabilities
+
+4. **Development Environment**
+   - Virtual environment support
+   - Compatible with modern development tools
+   - Extensive documentation and community support
+
+## Consequences
+
+### Positive
+
+1. **Long-term Stability**
+   - Security updates guaranteed until October 2028
+   - Stable API and feature set
+   - Regular maintenance releases
+
+2. **Development Experience**
+   - Modern language features
+   - Improved performance
+   - Better error messages and debugging
+   - Enhanced type checking capabilities
+
+3. **Ecosystem Benefits**
+   - Wide library compatibility
+   - Active community support
+   - Mature tooling ecosystem
+
+### Negative
+
+1. **Version Management**
+   - Development environments must maintain Python 3.12
+   - CI/CD pipelines need specific version configuration
+   - Some older libraries might not be fully optimized
+
+2. **Learning Curve**
+   - Teams need to familiarize with Python 3.12 features
+   - Documentation may need updates for version-specific features
+
+## Alternatives Considered
+
+1. **Python 3.13**
+   - **Why Not Selected:**
+     - Released October 2024 (6 months ago)
+     - Still in early adoption phase
+     - Many ecosystem tools still stabilizing support
+     - Limited real-world production usage data
+     - Some key dependencies not yet fully tested
+
+2. **Python 3.11**
+   - **Why Not Selected:**
+     - Support ends October 2027 (2.5 years remaining)
+     - Lacks improved type checking features of 3.12
+     - Missing performance improvements (~5% slower)
+     - Does not include enhanced error messages
+     - Most libraries now optimizing for 3.12+
+
+3. **Python 3.10**
+   - **Why Not Selected:**
+     - Support ends October 2026 (1.5 years remaining)
+     - Missing critical type annotation improvements
+     - Lacks performance optimizations
+     - Missing modern debugging capabilities
+     - Would require earlier upgrade planning
+
+## Implementation Notes
+
+1. Development Environment Setup:
+   ```bash
+   python3.12 -m venv venv
+   source venv/bin/activate
+   python --version  # Should show Python 3.12.x
+   ```
+
+2. Dependencies:
+   - All dependencies will specify minimum Python 3.12 compatibility
+   - `requirements.txt` will include version pins
+   - Development tools will be configured for Python 3.12
+
+3. CI/CD Configuration:
+   - Build environments will use Python 3.12
+   - Test matrices will include Python 3.12.x versions
+   - Docker images will be based on Python 3.12
+
+## References
+
+1. [Python Status and Release Schedule](https://devguide.python.org/versions/)
+2. [Python 3.12 Release Notes](https://docs.python.org/3.12/whatsnew/3.12.html)
+3. [PEP 693 – Python 3.12 Release Schedule](https://peps.python.org/pep-0693/) 
\ No newline at end of file
diff --git a/requirements-dev.txt b/requirements-dev.txt
new file mode 100644
index 00000000..38b2268c
--- /dev/null
+++ b/requirements-dev.txt
@@ -0,0 +1,21 @@
+# Development dependencies
+-r requirements.txt
+
+# Testing
+pytest>=8.0.2
+pytest-cov>=4.1.0
+pytest-asyncio>=0.23.5
+pytest-env>=1.1.3
+httpx>=0.27.0
+
+# Type checking
+mypy>=1.8.0
+types-python-dateutil>=2.8.19.20240106
+
+# Linting and formatting
+ruff>=0.3.0
+black>=24.2.0
+
+# Development tools
+pre-commit>=3.6.2
+pip-tools>=7.4.0 
\ No newline at end of file
diff --git a/src/python/.gitignore b/src/python/.gitignore
new file mode 100644
index 00000000..1feb84a4
--- /dev/null
+++ b/src/python/.gitignore
@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+ENV/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.pytest_cache/
+htmlcov/
+
+# Logs
+*.log
+logs/
+
+# Environment variables
+.env
+.env.*
+
+# Database
+*.db
+*.sqlite3
+
+# OS
+.DS_Store
+Thumbs.db 
\ No newline at end of file
diff --git a/src/python/README.md b/src/python/README.md
index abe15381..a79477cc 100644
--- a/src/python/README.md
+++ b/src/python/README.md
@@ -1,32 +1,76 @@
-# Python Implementation
+# Lamp Control API (Python Implementation)
 
-This directory contains the Python implementation of the Lamp Control API.
+Python implementation of the Lamp Control API, providing endpoints to control and monitor lamp status.
 
-## Features
+## Requirements
 
-- REST API (FastAPI with OpenAPI 3.0)
-- GraphQL (Strawberry or Ariadne)
-- gRPC
-- Database support for MySQL, PostgreSQL, and MongoDB
+- Python 3.12.9 or higher
+- pip (Python package installer)
+- virtualenv or venv (recommended)
 
-## Getting Started
+## Project Structure
 
-*Instructions will be added as implementation progresses*
+```
+lamp_control/
+├── api/        # API endpoints and routers
+├── core/       # Core functionality and config
+├── db/         # Database models and migrations
+├── models/     # Domain models
+├── schemas/    # Pydantic schemas
+├── services/   # Business logic
+└── utils/      # Utility functions
+```
+
+## Development Setup
+
+1. Create and activate a virtual environment:
+   ```bash
+   python3.12 -m venv venv
+   source venv/bin/activate  # On Windows: .\venv\Scripts\activate
+   ```
+
+2. Install development dependencies:
+   ```bash
+   pip install -r requirements-dev.txt
+   ```
 
-## Directory Structure
+3. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
 
+## Running Tests
+
+```bash
+pytest
 ```
-python/
-├── src/            # Source code
-├── tests/          # Test files
-├── config/         # Configuration files
-└── README.md       # This file
+
+## Code Quality
+
+This project uses several tools to ensure code quality:
+
+- `black` for code formatting
+- `ruff` for linting
+- `mypy` for static type checking
+- `pytest` for testing
+
+Run all quality checks:
+```bash
+black .
+ruff check .
+mypy .
+pytest
 ```
 
-## Implementation Details
+## API Documentation
 
-*Coming soon*
+Once running, API documentation is available at:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
 
-## Testing
+## Contributing
 
-*Coming soon*
+1. Create a new branch for your feature
+2. Make your changes
+3. Run tests and quality checks
+4. Submit a pull request
diff --git a/src/python/lamp_control/__init__.py b/src/python/lamp_control/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/lamp_control/api/__init__.py b/src/python/lamp_control/api/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/lamp_control/core/__init__.py b/src/python/lamp_control/core/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/lamp_control/db/__init__.py b/src/python/lamp_control/db/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/lamp_control/models/__init__.py b/src/python/lamp_control/models/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/lamp_control/schemas/__init__.py b/src/python/lamp_control/schemas/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/lamp_control/services/__init__.py b/src/python/lamp_control/services/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/lamp_control/utils/__init__.py b/src/python/lamp_control/utils/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/pyproject.toml b/src/python/pyproject.toml
new file mode 100644
index 00000000..ddcd18e3
--- /dev/null
+++ b/src/python/pyproject.toml
@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=69.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lamp-control-api"
+version = "0.1.0"
+description = "Python implementation of the Lamp Control API"
+requires-python = ">=3.12.9"
+authors = [
+    {name = "Lamp Control Team"}
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py312"]
+include = '\.pyi?$'
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+select = ["E", "F", "B", "I", "N", "UP", "PL", "RUF"]
+ignore = []
+
+[tool.ruff.isort]
+known-first-party = ["lamp_control"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra -q --cov=lamp_control --cov-report=term-missing"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto" 
\ No newline at end of file
diff --git a/src/python/requirements-dev.txt b/src/python/requirements-dev.txt
new file mode 100644
index 00000000..38b2268c
--- /dev/null
+++ b/src/python/requirements-dev.txt
@@ -0,0 +1,21 @@
+# Development dependencies
+-r requirements.txt
+
+# Testing
+pytest>=8.0.2
+pytest-cov>=4.1.0
+pytest-asyncio>=0.23.5
+pytest-env>=1.1.3
+httpx>=0.27.0
+
+# Type checking
+mypy>=1.8.0
+types-python-dateutil>=2.8.19.20240106
+
+# Linting and formatting
+ruff>=0.3.0
+black>=24.2.0
+
+# Development tools
+pre-commit>=3.6.2
+pip-tools>=7.4.0 
\ No newline at end of file
diff --git a/src/python/requirements.txt b/src/python/requirements.txt
new file mode 100644
index 00000000..ea62ddd2
--- /dev/null
+++ b/src/python/requirements.txt
@@ -0,0 +1,10 @@
+# Core dependencies
+fastapi>=0.110.0  # Modern web framework with high performance
+uvicorn>=0.27.1  # ASGI server for FastAPI
+pydantic>=2.6.3  # Data validation using Python type annotations
+sqlalchemy>=2.0.27  # SQL toolkit and ORM
+alembic>=1.13.1  # Database migrations
+python-dotenv>=1.0.1  # Environment variable management
+structlog>=24.1.0  # Structured logging
+prometheus-client>=0.20.0  # Metrics collection
+httpx>=0.27.0  # HTTP client for async requests 
\ No newline at end of file
diff --git a/src/python/tests/__init__.py b/src/python/tests/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/tests/api/__init__.py b/src/python/tests/api/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/tests/core/__init__.py b/src/python/tests/core/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/tests/db/__init__.py b/src/python/tests/db/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/tests/models/__init__.py b/src/python/tests/models/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/tests/services/__init__.py b/src/python/tests/services/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/python/tests/test_dummy.py b/src/python/tests/test_dummy.py
new file mode 100644
index 00000000..d2693725
--- /dev/null
+++ b/src/python/tests/test_dummy.py
@@ -0,0 +1,6 @@
+"""Dummy test module to verify CI pipeline functionality."""
+
+
+def test_dummy() -> None:
+    """A dummy test that always passes."""
+    assert True, "This test should always pass"
diff --git a/src/python/tests/utils/__init__.py b/src/python/tests/utils/__init__.py
new file mode 100644
index 00000000..e69de29b


Reviews:

Review comments:

PR comments:
user: login: davideme
created_at: 2025-04-20T08:28:39Z
body: Added a dummy test to verify the CI pipeline functionality. This ensures that:

1. The test runner is properly configured
2. Code coverage reporting works
3. Type checking passes (the test includes type annotations)
4. The CI workflow triggers correctly

This test will be replaced with actual unit tests as we implement the core functionality.
author_association: OWNER
user: login: davideme
created_at: 2025-04-20T08:32:43Z
body: Restructured the Python implementation to follow the project's standard directory layout:

- Moved all Python files to `src/python/`
- Updated GitHub Actions workflow to:
  - Use the correct working directory
  - Update path triggers
  - Fix coverage report path
  - Add proper pip cache path

This aligns with the project structure shown in the main README:
```
lamp-control-api-reference/
├── docs/
│   └── PRD.md
├── src/
│   ├── typescript/
│   ├── python/      <- Our implementation
│   ├── java/
│   ├── php/
│   ├── ruby/
│   └── go/
└── README.md
```
author_association: OWNER