feat: Standardize on Python 3.12+ with forward compatibility for 3.13 (#132)

jeremyeder · claude · web-flow · commit 84f2c467eac6 · 2025-11-24T11:03:56.000-05:00
* feat: standardize on Python 3.12+ with forward compatibility for 3.13 Migrate project to require Python 3.12 as minimum version while maintaining forward compatibility with Python 3.13 through CI testing matrix. **Configuration Changes:** - pyproject.toml: Update requires-python to >=3.12, add 3.13 classifier - pyproject.toml: Update black target-version to py312 - pyproject.toml: Improve description to highlight assess/bootstrap/learning - pyproject.toml: Bump version to 2.1.0 (minor release) - .pre-commit-config.yaml: Update language_version to python3.12 - uv.lock: Regenerate with new Python requirement (55 packages) **CI/CD Workflows (5 files):** - tests.yml: Test matrix now covers ['3.12', '3.13'] for forward compatibility - agentready-assessment.yml: Use Python 3.12 - security.yml: Use Python 3.12 - continuous-learning.yml: Use Python 3.12 - publish-pypi.yml: Use Python 3.12 **Bootstrap Templates (5 files):** - workflows/tests-python.yml.j2: Generate workflows testing 3.12 and 3.13 - workflows/agentready-assessment.yml.j2: Use Python 3.12 - workflows/security.yml.j2: Use Python 3.12 - precommit-python.yaml.j2: Use Python 3.12 - CONTRIBUTING.md.j2: Update Python version references **Documentation (5 files):** - CLAUDE.md: Update "Python 3.11+" → "Python 3.12+" - docs/user-guide.md: Update version references - docs/developer-guide.md: Update version references - docs/examples.md: Update version references - docs/attributes.md: Update version references **Verification:** - ✅ Dependencies verified: radon 6.0.1 and lizard 1.17.10 work with Python 3.12 - ✅ Test suite: 685 tests passed - ✅ CLI functional: agentready --version works - ✅ Batch assessment: Successfully assessed 3 repositories **Rationale:** - Python 3.12 provides good balance of recent features and stability - Codebase already uses 3.10+ syntax (union types, generic annotations) - Testing both 3.12 and 3.13 ensures smooth future upgrades - No breaking changes to code required 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: apply black/isort formatting from rebase Fix formatting issues that emerged after rebasing on main. Auto-formatters (black, isort, ruff --fix) applied to ensure CI passes. Changes: - Black reformatted 12 files - isort organized imports - ruff removed unused imports (align.py) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: fix black formatting in test_security.py * chore: fix isort formatting * fix: resolve ruff lint errors to pass CI - Fix undefined 'repo' variable in align.py (use assessment.repository) - Add noqa comments for intentional jsonschema import checks - Fix unused variable warnings in test files All linters now pass: black, isort, and ruff. --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.github/workflows/agentready-assessment.yml b/.github/workflows/agentready-assessment.yml
@@ -21,7 +21,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install AgentReady
         run: |
diff --git a/.github/workflows/continuous-learning.yml b/.github/workflows/continuous-learning.yml
@@ -37,7 +37,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install uv
         uses: astral-sh/setup-uv@v3
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
@@ -27,7 +27,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install build dependencies
         run: |
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
@@ -43,7 +43,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install dependencies
         run: |
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11', '3.12']
+        python-version: ['3.12', '3.13']
 
     steps:
       - name: Checkout code
@@ -45,7 +45,7 @@ jobs:
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4
-        if: matrix.python-version == '3.11'
+        if: matrix.python-version == '3.12'
         with:
           files: ./coverage.xml
           fail_ci_if_error: false
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -15,7 +15,7 @@ repos:
     rev: 24.1.1
     hooks:
       - id: black
-        language_version: python3.11
+        language_version: python3.12
 
   - repo: https://github.com/pycqa/isort
     rev: 5.13.2
diff --git a/.skills-proposals/discovered-skills.json b/.skills-proposals/discovered-skills.json
@@ -1,5 +1,5 @@
 {
-  "generated_at": "2025-11-24T09:11:46.886647",
+  "generated_at": "2025-11-24T09:52:54.795626",
   "skill_count": 0,
   "min_confidence": 70,
   "discovered_skills": []
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -428,7 +428,7 @@ agentready/
 
 ## Technologies
 
-- **Python 3.11+** (only N and N-1 versions supported)
+- **Python 3.12+** (only N and N-1 versions supported)
 - **Click** - CLI framework
 - **Jinja2** - HTML template engine
 - **Anthropic** - Claude API client (for LLM enrichment)
diff --git a/batch-repos.txt b/batch-repos.txt
@@ -0,0 +1,3 @@
+https://github.com/ambient-code/agentready
+https://github.com/ambient-code/platform
+https://github.com/ambient-code/spec-kit-rh
diff --git a/docs/attributes.md b/docs/attributes.md
@@ -111,7 +111,7 @@ CLAUDE.md files provide **immediate project context** without repeated explanati
 
 ```markdown
 # Tech Stack
-- Python 3.11+, pytest, black + isort
+- Python 3.12+, pytest, black + isort
 - FastAPI, PostgreSQL, Redis
 
 # Standard Commands
@@ -233,7 +233,7 @@ print(result)
 
 ## Requirements
 
-- Python 3.11+
+- Python 3.12+
 - PostgreSQL 14+
 - Redis 7+ (optional, for caching)
 
@@ -943,7 +943,7 @@ Clear documentation of prerequisites, environment variables, and configuration r
 
 **Must document**:
 
-- Language/runtime version (Python 3.11+, Node.js 18+)
+- Language/runtime version (Python 3.12+, Node.js 18+)
 - System dependencies (PostgreSQL, Redis, etc.)
 - Environment variables (`.env.example` with all variables)
 - Optional: IDE setup, debugging config
diff --git a/docs/developer-guide.md b/docs/developer-guide.md
@@ -24,7 +24,7 @@ Comprehensive guide for contributors and developers extending AgentReady.
 
 ### Prerequisites
 
-- **Python 3.11 or 3.12**
+- **Python 3.12 or 3.13**
 - **Git**
 - **uv** or **pip** (uv recommended for faster dependency management)
 - **Make** (optional, for convenience commands)
diff --git a/docs/examples.md b/docs/examples.md
@@ -53,7 +53,7 @@ AgentReady assesses itself to validate the scoring algorithm and demonstrate exp
 
 **Why it passes**: Comprehensive project documentation covering:
 
-- Tech stack (Python 3.11+, pytest, black, isort, ruff)
+- Tech stack (Python 3.12+, pytest, black, isort, ruff)
 - Repository structure (src/, tests/, docs/, examples/)
 - Standard commands (setup, test, lint, format)
 - Development workflow (GitHub Flow, feature branches)
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -29,7 +29,7 @@ Complete guide to installing, configuring, and using AgentReady to assess your r
 
 ### Prerequisites
 
-- **Python 3.11 or 3.12** (AgentReady supports versions N and N-1)
+- **Python 3.12 or 3.13** (AgentReady supports versions N and N-1)
 - **Git** (for repository analysis)
 - **pip** or **uv** (Python package manager)
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,17 +1,17 @@
 [project]
 name = "agentready"
-version = "2.2.0"
-description = "Assess git repositories against 25 evidence-based attributes for AI-assisted development readiness"
+version = "2.3.0"
+description = "Assess and bootstrap git repositories for AI-assisted development with automated remediation and continuous learning"
 authors = [{name = "Jeremy Eder", email = "jeder@redhat.com"}]
 readme = "README.md"
 license = {text = "MIT"}
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Quality Assurance",
 ]
 
@@ -61,7 +61,7 @@ agentready = [
 
 [tool.black]
 line-length = 88
-target-version = ["py311"]
+target-version = ["py312"]
 extend-exclude = '''
 /(
   \.eggs
diff --git a/src/agentready/cli/align.py b/src/agentready/cli/align.py
@@ -6,9 +6,7 @@
 import click
 
 from ..models.config import Config
-from ..models.repository import Repository
 from ..services.fixer_service import FixerService
-from ..services.language_detector import LanguageDetector
 from ..services.scanner import Scanner
 
 
@@ -120,7 +118,9 @@ def align(repository, dry_run, attributes, interactive):
         attribute_list = [a.strip() for a in attributes.split(",")]
 
     fixer_service = FixerService()
-    fix_plan = fixer_service.generate_fix_plan(assessment, repo, attribute_list)
+    fix_plan = fixer_service.generate_fix_plan(
+        assessment, assessment.repository, attribute_list
+    )
 
     if not fix_plan.fixes:
         click.echo("\n✅ No automatic fixes available.")
diff --git a/src/agentready/models/batch_assessment.py b/src/agentready/models/batch_assessment.py
@@ -2,7 +2,6 @@
 
 from dataclasses import dataclass, field
 from datetime import datetime
-from pathlib import Path
 
 from .assessment import Assessment
 
diff --git a/src/agentready/reporters/csv_reporter.py b/src/agentready/reporters/csv_reporter.py
@@ -112,7 +112,9 @@ def generate(
                     # SECURITY: Sanitize all string fields
                     row = {
                         "repo_url": self.sanitize_csv_field(result.repository_url),
-                        "repo_name": self.sanitize_csv_field(assessment.repository.name),
+                        "repo_name": self.sanitize_csv_field(
+                            assessment.repository.name
+                        ),
                         "overall_score": assessment.overall_score,
                         "certification_level": self.sanitize_csv_field(
                             assessment.certification_level
diff --git a/src/agentready/services/assessment_cache.py b/src/agentready/services/assessment_cache.py
@@ -6,7 +6,7 @@
 from pathlib import Path
 from typing import Optional
 
-from ..models import Assessment, BatchAssessment, RepositoryResult
+from ..models import Assessment
 
 
 class AssessmentCache:
@@ -230,7 +230,9 @@ def get_stats(self) -> dict:
                 )
                 valid = cursor.fetchone()[0]
 
-                cursor = conn.execute("SELECT COUNT(DISTINCT repository_url) FROM assessments")
+                cursor = conn.execute(
+                    "SELECT COUNT(DISTINCT repository_url) FROM assessments"
+                )
                 unique_repos = cursor.fetchone()[0]
 
                 return {
@@ -258,7 +260,6 @@ def _deserialize_assessment(data: dict) -> Assessment:
         # In practice, you'd need full deserialization logic
         # For now, we'll use a placeholder that assumes the cached JSON
         # has the correct structure
-        from .scanner import Scanner
 
         # Note: This is a simplified approach. In production, you'd need
         # proper deserialization that reconstructs all nested objects
diff --git a/src/agentready/services/batch_scanner.py b/src/agentready/services/batch_scanner.py
@@ -6,7 +6,7 @@
 from typing import Callable, Optional
 from uuid import uuid4
 
-from ..models import Assessment, BatchAssessment, BatchSummary, RepositoryResult
+from ..models import BatchAssessment, BatchSummary, RepositoryResult
 from .assessment_cache import AssessmentCache
 from .repository_manager import RepositoryManager
 from .scanner import Scanner
diff --git a/src/agentready/services/github_scanner.py b/src/agentready/services/github_scanner.py
@@ -146,9 +146,7 @@ def get_org_repos(
                 response.raise_for_status()
 
             except requests.Timeout:
-                raise GitHubAPIError(
-                    f"GitHub API timeout for organization: {org_name}"
-                )
+                raise GitHubAPIError(f"GitHub API timeout for organization: {org_name}")
 
             except requests.HTTPError as e:
                 # SECURITY: Redact token before raising
diff --git a/src/agentready/services/schema_validator.py b/src/agentready/services/schema_validator.py
@@ -5,7 +5,7 @@
 from typing import Any
 
 try:
-    import jsonschema
+    import jsonschema  # noqa: F401
     from jsonschema import Draft7Validator, validators
 
     JSONSCHEMA_AVAILABLE = True
diff --git a/src/agentready/templates/bootstrap/CONTRIBUTING.md.j2 b/src/agentready/templates/bootstrap/CONTRIBUTING.md.j2
@@ -11,7 +11,7 @@ Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
 ### Prerequisites
 
 {% if language == 'python' %}
-- Python 3.11 or higher
+- Python 3.12 or higher
 - pip or uv for package management
 - Git
 {% elif language == 'javascript' %}
diff --git a/src/agentready/templates/bootstrap/precommit-python.yaml.j2 b/src/agentready/templates/bootstrap/precommit-python.yaml.j2
@@ -15,7 +15,7 @@ repos:
     rev: 24.1.1
     hooks:
       - id: black
-        language_version: python3.11
+        language_version: python3.12
 
   - repo: https://github.com/pycqa/isort
     rev: 5.13.2
diff --git a/src/agentready/templates/bootstrap/workflows/agentready-assessment.yml.j2 b/src/agentready/templates/bootstrap/workflows/agentready-assessment.yml.j2
@@ -21,7 +21,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install AgentReady
         run: |
diff --git a/src/agentready/templates/bootstrap/workflows/security.yml.j2 b/src/agentready/templates/bootstrap/workflows/security.yml.j2
@@ -44,7 +44,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install dependencies
         run: |
diff --git a/src/agentready/templates/bootstrap/workflows/tests-python.yml.j2 b/src/agentready/templates/bootstrap/workflows/tests-python.yml.j2
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11', '3.12']
+        python-version: ['3.12', '3.13']
 
     steps:
       - name: Checkout code
diff --git a/tests/integration/test_github_integration.py b/tests/integration/test_github_integration.py
@@ -1,9 +1,9 @@
 """Integration tests for GitHub scanner (requires GITHUB_TOKEN)."""
 
 import os
+import urllib.parse
 
 import pytest
-import urllib.parse
 
 from agentready.services.github_scanner import GitHubOrgScanner
 
diff --git a/tests/integration/test_schema_commands.py b/tests/integration/test_schema_commands.py
@@ -72,7 +72,7 @@ def sample_report(tmp_path):
 def test_validate_report_valid(runner, sample_report):
     """Test validate-report command with valid report."""
     try:
-        import jsonschema
+        import jsonschema  # noqa: F401
     except ImportError:
         pytest.skip("jsonschema not installed")
 
@@ -85,7 +85,7 @@ def test_validate_report_valid(runner, sample_report):
 def test_validate_report_nonexistent(runner, tmp_path):
     """Test validate-report command with nonexistent file."""
     try:
-        import jsonschema
+        import jsonschema  # noqa: F401
     except ImportError:
         pytest.skip("jsonschema not installed")
 
@@ -100,7 +100,7 @@ def test_validate_report_nonexistent(runner, tmp_path):
 def test_validate_report_invalid_json(runner, tmp_path):
     """Test validate-report command with invalid JSON."""
     try:
-        import jsonschema
+        import jsonschema  # noqa: F401
     except ImportError:
         pytest.skip("jsonschema not installed")
 
@@ -117,7 +117,7 @@ def test_validate_report_invalid_json(runner, tmp_path):
 def test_validate_report_no_strict(runner, sample_report):
     """Test validate-report with --no-strict option."""
     try:
-        import jsonschema
+        import jsonschema  # noqa: F401
     except ImportError:
         pytest.skip("jsonschema not installed")
 
@@ -174,7 +174,7 @@ def test_migrate_report_unsupported_version(runner, sample_report):
 def test_validate_then_migrate_workflow(runner, sample_report, tmp_path):
     """Test full workflow: validate, migrate, validate again."""
     try:
-        import jsonschema
+        import jsonschema  # noqa: F401
     except ImportError:
         pytest.skip("jsonschema not installed")
 
diff --git a/tests/security/test_xss_prevention.py b/tests/security/test_xss_prevention.py
@@ -57,9 +57,7 @@ def create_test_batch_with_payload(payload: str, inject_location: str):
     )
 
     repo_url = (
-        "https://github.com/test/repo"
-        if inject_location != "repo_url"
-        else payload
+        "https://github.com/test/repo" if inject_location != "repo_url" else payload
     )
     error = payload if inject_location == "error_message" else None
 
diff --git a/tests/unit/cli/test_main.py b/tests/unit/cli/test_main.py
@@ -1,8 +1,5 @@
 """Unit tests for main CLI commands."""
 
-import json
-import shutil
-import tempfile
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
@@ -18,7 +15,6 @@
     load_config,
     research_version,
     run_assessment,
-    show_version,
 )
 from agentready.models.config import Config
 
diff --git a/tests/unit/learners/test_llm_enricher.py b/tests/unit/learners/test_llm_enricher.py
diff --git a/tests/unit/learners/test_skill_generator.py b/tests/unit/learners/test_skill_generator.py
diff --git a/tests/unit/test_assessment_cache.py b/tests/unit/test_assessment_cache.py
diff --git a/tests/unit/test_cli_extract_skills.py b/tests/unit/test_cli_extract_skills.py
diff --git a/tests/unit/test_csv_reporter.py b/tests/unit/test_csv_reporter.py
diff --git a/tests/unit/test_fixer_service.py b/tests/unit/test_fixer_service.py
diff --git a/tests/unit/test_github_scanner.py b/tests/unit/test_github_scanner.py
diff --git a/tests/unit/test_multi_html_reporter.py b/tests/unit/test_multi_html_reporter.py
diff --git a/tests/unit/test_repository_manager.py b/tests/unit/test_repository_manager.py
diff --git a/tests/unit/test_security.py b/tests/unit/test_security.py
diff --git a/tests/unit/test_security_controls.py b/tests/unit/test_security_controls.py
diff --git a/tests/unit/utils/test_privacy.py b/tests/unit/utils/test_privacy.py
diff --git a/tests/unit/utils/test_subprocess_utils.py b/tests/unit/utils/test_subprocess_utils.py
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "generated_at": "2025-11-24T09:11:46.886647",`
	`2`	`+ "generated_at": "2025-11-24T09:52:54.795626",`
`3`	`3`	`"skill_count": 0,`
`4`	`4`	`"min_confidence": 70,`
`5`	`5`	`"discovered_skills": []`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+https://github.com/ambient-code/agentready`
	`2`	`+https://github.com/ambient-code/platform`
	`3`	`+https://github.com/ambient-code/spec-kit-rh`