refactor: migrate to Python 3.13 and enhance type safety#14
Closed
ethan-wickstrom wants to merge 27 commits into
Closed
refactor: migrate to Python 3.13 and enhance type safety#14ethan-wickstrom wants to merge 27 commits into
ethan-wickstrom wants to merge 27 commits into
Conversation
Rewrite the README generation script using Pydantic and a multi-stage DSPy pipeline for a more robust, context-aware process. The README.md is regenerated with the new script, providing more comprehensive documentation.
Adds comprehensive .pyi type stub files for the DSPy library (version 2.6.19), including all core modules, adapters, clients, datasets, evaluation, experimental features, prediction modules, primitives, propose, retrieve, retrievers, signatures, streaming, teleprompt, and utility modules. These stubs enable static type checking and improved IDE support for DSPy-based projects. The stubs were generated by pyright and cover all public APIs, class methods, and function signatures, facilitating better integration and type safety for downstream users.
Replaces mypy and pyright with basedpyright for type checking, and updates the project's target Python version from 3.12 to 3.13. This includes updating pyproject.toml, .python-version, and adding VS Code settings for basedpyright integration.
Adds a new documentation page detailing a `TypeError: Name 'X' defined twice` issue encountered with Typer 0.16.0 when using `Annotated` with `typer.Option()` and specifying the default value as the first argument to `Option()`. The document provides a root cause analysis, explains why the issue occurs due to Typer/Click's parameter processing, and offers best practices and alternative patterns to avoid it.
Extracted shared models (TestCase, CodeQualityScores) into a dedicated models.py module to reduce circular dependencies. Created json and training subpackages to better organize related functionality. Replaced list type annotations with Sequence throughout for improved immutability guarantees. Added explicit type annotations for JSON data handling and module attributes. Removed redundant module docstrings and cleaned up imports across all affected files. The changes improve code organization by grouping related functionality, enhance type safety with more precise annotations, and establish clearer module boundaries without altering any external behavior.
Establishes project-wide development guidelines covering type system usage, CLI patterns, error handling, function design, data structures, testing, architecture, performance, async patterns, documentation, security, logging, database practices, API design, and refactoring standards. The .windsurfrules file provides detailed best practices with GOOD/BAD examples for consistent code quality across the robofactor project.
Introduces create_diffs.py for displaying staged/unstaged git diffs in Markdown format with flexible output options. Also adds utility script for automated list-to-Sequence refactoring and applies consistent code style formatting to the README generator. The diff tool supports multiple modes (staged/unstaged/both), output formats (stat/patch), and customizable context lines with word-level diff capabilities.
…cture Split monolithic modules into focused packages with clear responsibilities: - Created app package for CLI and UI components - Established evaluation package for code quality and correctness checks - Introduced parsing package for AST operations and code analysis - Added refactoring package for AI-powered transformation logic Migrated from relative to absolute imports throughout the codebase for better maintainability. Updated entry point in pyproject.toml to reflect new app.main module location.
…tices for Python 3.13
…ta loading Restructures the configuration system to enforce immutability and single source of truth (SSoT) principles. Replaces manual JSON parsing in the training loader with Pydantic models for compile-time type safety. Configuration changes: - All config values now use `Final` type annotations - Added explicit `__all__` exports to prevent external mutation - Centralized file paths using ROOT_DIR base path - Enhanced module docstring to clarify SSoT requirements Training data changes: - Created Pydantic models (TrainingEntry, TrainingSetAdapter) for JSON schema - Eliminated runtime type guards in favor of Pydantic validation - Simplified error handling with structured ValidationError - Pre-compiled TypeAdapter for performance optimization Also includes minor formatting improvements across evaluation modules to maintain consistency with updated import paths.
Extracts duplicated functionality across modules into a centralized common package to enforce DRY principles and establish single sources of truth. Moves core utilities to common package: - AST manipulation (ast_node_to_source) from parsing.ast_parser - Python code extraction from parsing.analysis - JSON validation functions from json package and training loader Updates all import paths to reference the new common package location. Removes redundant implementations and the now-empty json.is_json_list module. This structural reorganization improves maintainability by eliminating code duplication while preserving all existing functionality and APIs.
Establishes project-wide Python coding standards and best practices to ensure consistency across the codebase. Documents conventions for project structure, code style, type hints, documentation, workflow, and dependency management. Provides clear guidance for: - Source layout and directory organization - Black/isort formatting and PEP 8 compliance - Type annotation requirements and patterns - Google-style docstring conventions - Virtual environment and CI/CD workflows - Dependency pinning and security practices
There was a problem hiding this comment.
Pull Request Overview
This pull request upgrades the codebase to Python 3.13, strengthens type safety across modules with Pydantic models and richer annotations, refreshes IDE/type-checker configurations, and enriches documentation with modern Python patterns, coding guidelines, and README updates.
- Bump Python version to 3.13 and update related tooling (pyproject.toml, .python-version, VS Code settings).
- Introduce or refine Pydantic-based models and TypeGuards in parsing, training, refactoring, and evaluation pipelines.
- Add comprehensive docs: coding guidelines (.windsurfrules), modern Python cheat sheet, Typer issue fix, and update README for new workflows.
Reviewed Changes
Copilot reviewed 31 out of 35 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| .python-version | Updated Python version to 3.13. |
| .vscode/settings.json | Configured basedPyright analysis, formatter, and inlay hints. |
| src/robofactor/parsing/models.py | Defined Pydantic models for parsing context; type-safe JSON schemas. |
| src/robofactor/parsing/ast_parser.py | Streamlined AST parser imports, type aliases, and context classes. |
| docs/modern_python_patterns.md | Added cheat sheet for Python 3.13 features (type aliases, guards). |
| docs/issues-in-typer.md | Documented quick fix for Typer/Annotated default argument issue. |
| .windsurfrules | Introduced coding best practices and style guidelines. |
| README.md | Rewritten to reflect new installation, usage, and architecture. |
| complexity_score: float | ||
| typing_score: float | ||
| docstring_score: float | ||
| linting_issues: Sequence[str] = Field(default_factory=Sequence) |
There was a problem hiding this comment.
Using Sequence as the default_factory will fail because Sequence is abstract and not callable. Consider using default_factory=list to produce an empty list of issues.
Suggested change
| linting_issues: Sequence[str] = Field(default_factory=Sequence) | |
| linting_issues: Sequence[str] = Field(default_factory=list) |
Replaces mypy with basedpyright for type checking with explicit Python 3.13 version specification. Consolidates code formatting under ruff, removing separate isort command. Simplifies test execution with graceful handling for empty test directories. Removes unused targets and enhances the clean target for more comprehensive artifact removal.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces several updates to enhance compatibility, improve tooling, and provide comprehensive documentation for modern Python development practices. Key changes include updating the Python version, adding new configurations for VS Code and Pyright, introducing coding guidelines, and expanding documentation with cheat sheets and fixes for common issues.
Compatibility and Tooling Updates:
.python-versionto use Python 3.13 for compatibility with the latest features..vscode/settings.jsonwith Pyright type-checking settings, formatter options, and other Python development preferences.Documentation Enhancements:
.windsurfrulesto define best practices for Python development, emphasizing pure functions, type systems, CLI design, error handling, and testing strategies.docs/issues-in-typer.mdto address a common issue withAnnotatedandtyper.Option, providing a quick fix for developers.docs/modern_python_patterns.mdto highlight Python 3.13 features like type aliases, safe null handling, and type guards.