dissolve 0.1.0__tar.gz → 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of dissolve might be problematic. Click here for more details.
- dissolve-0.2.0/.github/workflows/disperse.yml +15 -0
- dissolve-0.2.0/.github/workflows/test.yml +42 -0
- dissolve-0.2.0/.gitignore +7 -0
- dissolve-0.2.0/CONTRIBUTING.md +70 -0
- dissolve-0.2.0/DESIGN.md +247 -0
- dissolve-0.2.0/PKG-INFO +467 -0
- dissolve-0.2.0/README.rst +437 -0
- dissolve-0.2.0/TODO +1 -0
- dissolve-0.2.0/disperse.conf +7 -0
- {dissolve-0.1.0 → dissolve-0.2.0}/dissolve/__init__.py +2 -4
- dissolve-0.2.0/dissolve/__main__.py +538 -0
- {dissolve-0.1.0 → dissolve-0.2.0}/dissolve/ast_utils.py +0 -32
- dissolve-0.2.0/dissolve/check.py +123 -0
- dissolve-0.2.0/dissolve/collector.py +624 -0
- dissolve-0.2.0/dissolve/decorators.py +249 -0
- dissolve-0.1.0/dissolve/types.py → dissolve-0.2.0/dissolve/import_utils.py +1 -15
- dissolve-0.2.0/dissolve/migrate.py +235 -0
- dissolve-0.2.0/dissolve/remove.py +256 -0
- dissolve-0.2.0/dissolve/replacer.py +451 -0
- dissolve-0.2.0/dissolve/types.py +64 -0
- dissolve-0.2.0/dissolve.egg-info/PKG-INFO +467 -0
- dissolve-0.2.0/dissolve.egg-info/SOURCES.txt +44 -0
- {dissolve-0.1.0 → dissolve-0.2.0}/dissolve.egg-info/requires.txt +4 -1
- {dissolve-0.1.0 → dissolve-0.2.0}/pyproject.toml +2 -1
- dissolve-0.2.0/tests/test_ast_utils.py +30 -0
- dissolve-0.2.0/tests/test_attribute_deprecation.py +139 -0
- dissolve-0.2.0/tests/test_check.py +143 -0
- dissolve-0.2.0/tests/test_class_methods.py +315 -0
- dissolve-0.2.0/tests/test_class_wrapper_deprecation.py +154 -0
- dissolve-0.2.0/tests/test_cli.py +863 -0
- dissolve-0.2.0/tests/test_comprehensive_replacements.py +555 -0
- dissolve-0.2.0/tests/test_decorator.py +183 -0
- dissolve-0.2.0/tests/test_decorator_dependencies.py +119 -0
- dissolve-0.2.0/tests/test_docstring_extension.py +149 -0
- dissolve-0.2.0/tests/test_edge_cases.py +345 -0
- dissolve-0.2.0/tests/test_formatting_edge_cases.py +357 -0
- dissolve-0.2.0/tests/test_formatting_preservation.py +570 -0
- dissolve-0.2.0/tests/test_migrate.py +775 -0
- dissolve-0.2.0/tests/test_remove.py +372 -0
- dissolve-0.2.0/tox.ini +8 -0
- dissolve-0.1.0/PKG-INFO +0 -165
- dissolve-0.1.0/README.rst +0 -138
- dissolve-0.1.0/dissolve/__main__.py +0 -203
- dissolve-0.1.0/dissolve/decorators.py +0 -150
- dissolve-0.1.0/dissolve/migrate.py +0 -430
- dissolve-0.1.0/dissolve/remove.py +0 -272
- dissolve-0.1.0/dissolve.egg-info/PKG-INFO +0 -165
- dissolve-0.1.0/dissolve.egg-info/SOURCES.txt +0 -22
- dissolve-0.1.0/tests/test_ast_utils.py +0 -127
- dissolve-0.1.0/tests/test_cli.py +0 -317
- dissolve-0.1.0/tests/test_decorator.py +0 -62
- dissolve-0.1.0/tests/test_migrate.py +0 -238
- dissolve-0.1.0/tests/test_remove.py +0 -186
- {dissolve-0.1.0 → dissolve-0.2.0}/COPYING +0 -0
- {dissolve-0.1.0 → dissolve-0.2.0}/dissolve.egg-info/dependency_links.txt +0 -0
- {dissolve-0.1.0 → dissolve-0.2.0}/dissolve.egg-info/entry_points.txt +0 -0
- {dissolve-0.1.0 → dissolve-0.2.0}/dissolve.egg-info/top_level.txt +0 -0
- {dissolve-0.1.0 → dissolve-0.2.0}/setup.cfg +0 -0
- {dissolve-0.1.0 → dissolve-0.2.0}/setup.py +0 -0
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Python tests
|
|
3
|
+
|
|
4
|
+
"on":
|
|
5
|
+
- push
|
|
6
|
+
- pull_request
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
pythontests:
|
|
10
|
+
|
|
11
|
+
runs-on: ${{ matrix.os }}
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
os: [ubuntu-latest, macos-latest, windows-latest]
|
|
15
|
+
python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
|
|
16
|
+
fail-fast: false
|
|
17
|
+
|
|
18
|
+
steps:
|
|
19
|
+
- uses: actions/checkout@v2
|
|
20
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
21
|
+
uses: actions/setup-python@v2
|
|
22
|
+
with:
|
|
23
|
+
python-version: ${{ matrix.python-version }}
|
|
24
|
+
- name: Install dependencies
|
|
25
|
+
run: |
|
|
26
|
+
python -m pip install --upgrade pip
|
|
27
|
+
python -m pip install -U ".[migrate]"
|
|
28
|
+
- name: Style checks
|
|
29
|
+
run: |
|
|
30
|
+
python -m pip install ruff
|
|
31
|
+
python -m ruff check .
|
|
32
|
+
python -m ruff format --check .
|
|
33
|
+
- name: Typing checks
|
|
34
|
+
run: |
|
|
35
|
+
python -m pip install -U mypy
|
|
36
|
+
python -m mypy dissolve
|
|
37
|
+
- name: Test suite run
|
|
38
|
+
run: |
|
|
39
|
+
python -m pip install tox
|
|
40
|
+
tox
|
|
41
|
+
env:
|
|
42
|
+
PYTHONHASHSEED: random
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Contributing to Dissolve
|
|
2
|
+
|
|
3
|
+
Thank you for your interest in contributing to Dissolve! This document provides guidelines for contributing to the project.
|
|
4
|
+
|
|
5
|
+
## Development Setup
|
|
6
|
+
|
|
7
|
+
1. Clone the repository and install dependencies:
|
|
8
|
+
```bash
|
|
9
|
+
pip install -e .[dev]
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
2. Install pre-commit hooks (optional but recommended):
|
|
13
|
+
```bash
|
|
14
|
+
pre-commit install
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Code Quality
|
|
18
|
+
|
|
19
|
+
We maintain high code quality standards using several tools:
|
|
20
|
+
|
|
21
|
+
### Linting and Formatting
|
|
22
|
+
- **Ruff**: Used for linting and code formatting
|
|
23
|
+
```bash
|
|
24
|
+
ruff check .
|
|
25
|
+
ruff format .
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### Type Checking
|
|
29
|
+
- **MyPy**: Used for static type checking
|
|
30
|
+
```bash
|
|
31
|
+
mypy dissolve/
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Testing
|
|
35
|
+
- **Pytest**: Used for running tests
|
|
36
|
+
```bash
|
|
37
|
+
pytest
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**All new code should include comprehensive unit tests.** Tests should cover:
|
|
41
|
+
- Normal operation and expected behavior
|
|
42
|
+
- Edge cases and error conditions
|
|
43
|
+
- Different input combinations and scenarios
|
|
44
|
+
|
|
45
|
+
Place tests in the `tests/` directory following the naming convention `test_<module_name>.py`.
|
|
46
|
+
|
|
47
|
+
## Before Submitting a Pull Request
|
|
48
|
+
|
|
49
|
+
Please ensure your code passes all quality checks:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
ruff check .
|
|
53
|
+
ruff format .
|
|
54
|
+
mypy dissolve/
|
|
55
|
+
pytest
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Design Guidelines
|
|
59
|
+
|
|
60
|
+
Please read [DESIGN.md](DESIGN.md) to understand the project's architecture and design principles before making significant changes.
|
|
61
|
+
|
|
62
|
+
## Submitting Changes
|
|
63
|
+
|
|
64
|
+
1. Fork the repository
|
|
65
|
+
2. Create a feature branch
|
|
66
|
+
3. Make your changes
|
|
67
|
+
4. Ensure all tests pass and code quality checks succeed
|
|
68
|
+
5. Submit a pull request with a clear description of your changes
|
|
69
|
+
|
|
70
|
+
Thank you for contributing!
|
dissolve-0.2.0/DESIGN.md
ADDED
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# Dissolve Design Document
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
Dissolve is a Python library that helps developers migrate from deprecated APIs to their replacements. It provides a comprehensive solution for managing API deprecations through runtime warnings and automated code migration tools.
|
|
6
|
+
|
|
7
|
+
## Core Purpose
|
|
8
|
+
|
|
9
|
+
The library addresses the common problem of API deprecation by providing:
|
|
10
|
+
- A decorator to mark deprecated functions with suggested replacements
|
|
11
|
+
- Command-line tools to automatically migrate codebases
|
|
12
|
+
- Validation tools to ensure deprecations can be properly migrated
|
|
13
|
+
- Utilities to clean up deprecated decorators after migration
|
|
14
|
+
|
|
15
|
+
## Architecture
|
|
16
|
+
|
|
17
|
+
### High-Level Components
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
21
|
+
│ CLI Interface │ │ CST Processing │ │ Decorator System│
|
|
22
|
+
│ (__main__.py) │ │ Pipeline │ │ (decorators.py) │
|
|
23
|
+
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
24
|
+
│ │ │
|
|
25
|
+
└───────────────────────┼───────────────────────┘
|
|
26
|
+
│
|
|
27
|
+
┌─────────────────────────────────────────────────┐
|
|
28
|
+
│ Migration Engine │
|
|
29
|
+
│ (migrate.py) │
|
|
30
|
+
└─────────────────────────────────────────────────┘
|
|
31
|
+
│
|
|
32
|
+
┌────────────────────────────┼────────────────────────────┐
|
|
33
|
+
│ │ │
|
|
34
|
+
┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
35
|
+
│ Validation │ │ CST Utils │ │ Import Utils │
|
|
36
|
+
│ (check.py) │ │ (libcst-based) │ │(import_utils.py)│
|
|
37
|
+
└─────────────┘ └─────────────────┘ └─────────────────┘
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### Core Components
|
|
41
|
+
|
|
42
|
+
#### 1. Decorator System (`decorators.py`)
|
|
43
|
+
The `@replace_me` decorator marks deprecated functions and provides runtime warnings:
|
|
44
|
+
```python
|
|
45
|
+
@replace_me(since="1.0.0", remove_in="2.0.0")
|
|
46
|
+
def deprecated_function(x, y):
|
|
47
|
+
return new_function(x, y=y)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**Responsibilities:**
|
|
51
|
+
- Runtime deprecation warnings
|
|
52
|
+
- Metadata storage for migration tools
|
|
53
|
+
- AST-based analysis to extract replacement expressions (still uses ast for runtime warnings)
|
|
54
|
+
|
|
55
|
+
#### 2. CST Processing Pipeline
|
|
56
|
+
A collection of modules that parse, analyze, and transform Python code using libcst (Concrete Syntax Tree):
|
|
57
|
+
|
|
58
|
+
- **Collector** (`collector.py`): Discovers `@replace_me` decorated functions and extracts replacement information using CST visitors
|
|
59
|
+
- **Replacer** (`replacer.py`): Transforms function calls to use replacement expressions while preserving formatting
|
|
60
|
+
- **CST-based processing**: Leverages libcst for format-preserving transformations
|
|
61
|
+
- **Legacy AST Utilities** (`ast_utils.py`): Retained for backward compatibility but no longer actively used
|
|
62
|
+
|
|
63
|
+
#### 3. Migration Engine (`migrate.py`)
|
|
64
|
+
The core migration logic that orchestrates the transformation process:
|
|
65
|
+
- Cross-file migration with import resolution using libcst
|
|
66
|
+
- Interactive mode for user confirmation with position tracking via CST metadata
|
|
67
|
+
- Module resolver system for handling dependencies
|
|
68
|
+
- Format-preserving transformations to maintain code style
|
|
69
|
+
|
|
70
|
+
#### 4. Command-Line Interface (`__main__.py`)
|
|
71
|
+
Four main commands:
|
|
72
|
+
- `dissolve migrate`: Automatically replace deprecated calls (for library users)
|
|
73
|
+
- `dissolve cleanup`: Remove deprecated functions entirely (for library maintainers)
|
|
74
|
+
- `dissolve check`: Validate that decorators can be migrated
|
|
75
|
+
- `dissolve info`: List all deprecated functions and replacements
|
|
76
|
+
|
|
77
|
+
#### 5. Validation and Analysis
|
|
78
|
+
- **Check** (`check.py`): Validates that `@replace_me` functions can be processed using libcst
|
|
79
|
+
- **Context Analyzer** (`context_analyzer.py`): Analyzes local definitions and imports (libcst-based)
|
|
80
|
+
- **Import Utils** (`import_utils.py`): Manages import requirements and dependencies using CST visitors
|
|
81
|
+
|
|
82
|
+
## Key Data Structures
|
|
83
|
+
|
|
84
|
+
### Core Types (`types.py`)
|
|
85
|
+
```python
|
|
86
|
+
class Replacement(Protocol):
|
|
87
|
+
"""Protocol for replacement information"""
|
|
88
|
+
name: str
|
|
89
|
+
replacement: str
|
|
90
|
+
|
|
91
|
+
class ReplaceInfo:
|
|
92
|
+
"""Contains function name and replacement expression template"""
|
|
93
|
+
name: str
|
|
94
|
+
replacement: str
|
|
95
|
+
|
|
96
|
+
class ImportRequirement:
|
|
97
|
+
"""Represents needed imports for replacements"""
|
|
98
|
+
module: str
|
|
99
|
+
names: list[str]
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Error Handling
|
|
103
|
+
```python
|
|
104
|
+
class ReplacementExtractionError(Exception):
|
|
105
|
+
"""Raised when a function body can't be processed"""
|
|
106
|
+
|
|
107
|
+
class ReplacementFailureReason(Enum):
|
|
108
|
+
"""Categorizes why extraction failed"""
|
|
109
|
+
COMPLEX_BODY = "complex_body"
|
|
110
|
+
RECURSIVE_CALL = "recursive_call"
|
|
111
|
+
NO_RETURN = "no_return"
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Workflows
|
|
115
|
+
|
|
116
|
+
### 1. Migration Workflow
|
|
117
|
+
```
|
|
118
|
+
Source Code Input
|
|
119
|
+
↓
|
|
120
|
+
Parse CST (libcst) → Collect @replace_me functions → Extract replacement expressions
|
|
121
|
+
↓
|
|
122
|
+
Find function calls → Match with replacements → Substitute arguments
|
|
123
|
+
↓
|
|
124
|
+
Transform CST nodes → Generate format-preserving code → Output migrated code
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### 2. Validation Workflow
|
|
128
|
+
```
|
|
129
|
+
Source Code Input
|
|
130
|
+
↓
|
|
131
|
+
Parse CST → Find @replace_me functions → Validate function bodies
|
|
132
|
+
↓
|
|
133
|
+
Check for complex bodies/recursive calls → Report errors/success
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### 3. Function Cleanup Workflow (for library maintainers)
|
|
137
|
+
```
|
|
138
|
+
Source Code Input
|
|
139
|
+
↓
|
|
140
|
+
Parse CST → Find @replace_me functions → Check version constraints
|
|
141
|
+
↓
|
|
142
|
+
Remove matching functions entirely → Output cleaned code
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Design Patterns
|
|
146
|
+
|
|
147
|
+
### CST Visitor Pattern
|
|
148
|
+
Extensive use of libcst visitors and transformers:
|
|
149
|
+
- `DeprecatedFunctionCollector` (cst.CSTVisitor): Collects deprecated function information
|
|
150
|
+
- `FunctionCallReplacer` (cst.CSTTransformer): Transforms function calls while preserving formatting
|
|
151
|
+
- `ReplaceRemover` (cst.CSTTransformer): Removes deprecated functions cleanly
|
|
152
|
+
- `ContextAnalyzer` (cst.CSTVisitor): Analyzes module context with metadata support
|
|
153
|
+
|
|
154
|
+
### Strategy Pattern
|
|
155
|
+
Different migration strategies:
|
|
156
|
+
- `FunctionCallReplacer`: Automatic replacement
|
|
157
|
+
- `InteractiveFunctionCallReplacer`: User-confirmed replacement
|
|
158
|
+
|
|
159
|
+
### Template Method Pattern
|
|
160
|
+
Common file processing logic in `_process_files_common()` with shared:
|
|
161
|
+
- Validation patterns
|
|
162
|
+
- Output formatting
|
|
163
|
+
- Error handling
|
|
164
|
+
|
|
165
|
+
## Advanced Features
|
|
166
|
+
|
|
167
|
+
### Cross-Module Migration
|
|
168
|
+
Resolves imports to find deprecated functions in other modules:
|
|
169
|
+
```python
|
|
170
|
+
# Can migrate calls to deprecated functions in imported modules
|
|
171
|
+
from other_module import deprecated_func
|
|
172
|
+
result = deprecated_func(x, y) # Will be replaced
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Version-Aware Removal
|
|
176
|
+
Uses semantic versioning to determine when to remove decorators:
|
|
177
|
+
```python
|
|
178
|
+
@replace_me(since="1.0.0", remove_in="2.0.0") # Removed when version >= 2.0.0
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Interactive Mode
|
|
182
|
+
Allows selective migration with user confirmation:
|
|
183
|
+
```bash
|
|
184
|
+
dissolve migrate --interactive mycode.py
|
|
185
|
+
# Prompts: Replace deprecated_func(x, y) with new_func(x, y=y)? [y/N]
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Context-Aware Analysis
|
|
189
|
+
Understands the difference between local definitions and imports:
|
|
190
|
+
- Analyzes local variable scope
|
|
191
|
+
- Tracks import statements
|
|
192
|
+
- Resolves naming conflicts
|
|
193
|
+
|
|
194
|
+
## Error Handling Philosophy
|
|
195
|
+
|
|
196
|
+
### Graceful Degradation
|
|
197
|
+
- Falls back to original code when replacement fails
|
|
198
|
+
- Preserves functionality even when migration isn't possible
|
|
199
|
+
- Provides detailed error messages for debugging
|
|
200
|
+
|
|
201
|
+
### Comprehensive Validation
|
|
202
|
+
- Checks for complex function bodies that can't be automatically migrated
|
|
203
|
+
- Detects recursive calls that would cause infinite loops
|
|
204
|
+
- Validates that replacement expressions are syntactically correct
|
|
205
|
+
|
|
206
|
+
### Preview-First Design
|
|
207
|
+
- Default behavior shows changes without applying them
|
|
208
|
+
- Requires explicit `--write` flag to modify files
|
|
209
|
+
- Provides diff output for review
|
|
210
|
+
|
|
211
|
+
## CLI Design Philosophy
|
|
212
|
+
|
|
213
|
+
### Safety First
|
|
214
|
+
- Preview mode by default
|
|
215
|
+
- Explicit write operations
|
|
216
|
+
- Comprehensive validation before changes
|
|
217
|
+
|
|
218
|
+
### Developer Experience
|
|
219
|
+
- Rich help text and examples
|
|
220
|
+
- Multiple output formats (diff, summary, detailed)
|
|
221
|
+
- Interactive mode for complex migrations
|
|
222
|
+
- Batch processing for large codebases
|
|
223
|
+
|
|
224
|
+
### Integration Friendly
|
|
225
|
+
- Exit codes for CI/CD integration
|
|
226
|
+
- Machine-readable output options
|
|
227
|
+
- Configurable behavior through command-line flags
|
|
228
|
+
|
|
229
|
+
## Testing Strategy
|
|
230
|
+
|
|
231
|
+
The test suite covers:
|
|
232
|
+
- CST transformation correctness
|
|
233
|
+
- CLI interface behavior
|
|
234
|
+
- Error handling scenarios
|
|
235
|
+
- Edge cases in Python syntax
|
|
236
|
+
- Cross-module dependency resolution
|
|
237
|
+
- Format preservation validation
|
|
238
|
+
|
|
239
|
+
## Migration to libcst
|
|
240
|
+
|
|
241
|
+
The library now uses libcst (Concrete Syntax Tree) instead of Python's built-in ast module for all transformation operations. Key changes:
|
|
242
|
+
|
|
243
|
+
- **Format Preservation**: libcst preserves comments, whitespace, and original formatting
|
|
244
|
+
- **Metadata Support**: Position tracking for interactive mode via `cst.MetadataWrapper`
|
|
245
|
+
- **Cleaner Transformations**: Uses `cst.RemovalSentinel.REMOVE` for node removal
|
|
246
|
+
- **Hybrid Architecture**: libcst for migrations, ast still used in decorators.py for runtime warnings
|
|
247
|
+
- **Optional Dependency**: libcst is only required for migration features (`migrate` extra)
|