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.

Files changed (59) hide show
  1. dissolve-0.2.0/.github/workflows/disperse.yml +15 -0
  2. dissolve-0.2.0/.github/workflows/test.yml +42 -0
  3. dissolve-0.2.0/.gitignore +7 -0
  4. dissolve-0.2.0/CONTRIBUTING.md +70 -0
  5. dissolve-0.2.0/DESIGN.md +247 -0
  6. dissolve-0.2.0/PKG-INFO +467 -0
  7. dissolve-0.2.0/README.rst +437 -0
  8. dissolve-0.2.0/TODO +1 -0
  9. dissolve-0.2.0/disperse.conf +7 -0
  10. {dissolve-0.1.0 → dissolve-0.2.0}/dissolve/__init__.py +2 -4
  11. dissolve-0.2.0/dissolve/__main__.py +538 -0
  12. {dissolve-0.1.0 → dissolve-0.2.0}/dissolve/ast_utils.py +0 -32
  13. dissolve-0.2.0/dissolve/check.py +123 -0
  14. dissolve-0.2.0/dissolve/collector.py +624 -0
  15. dissolve-0.2.0/dissolve/decorators.py +249 -0
  16. dissolve-0.1.0/dissolve/types.py → dissolve-0.2.0/dissolve/import_utils.py +1 -15
  17. dissolve-0.2.0/dissolve/migrate.py +235 -0
  18. dissolve-0.2.0/dissolve/remove.py +256 -0
  19. dissolve-0.2.0/dissolve/replacer.py +451 -0
  20. dissolve-0.2.0/dissolve/types.py +64 -0
  21. dissolve-0.2.0/dissolve.egg-info/PKG-INFO +467 -0
  22. dissolve-0.2.0/dissolve.egg-info/SOURCES.txt +44 -0
  23. {dissolve-0.1.0 → dissolve-0.2.0}/dissolve.egg-info/requires.txt +4 -1
  24. {dissolve-0.1.0 → dissolve-0.2.0}/pyproject.toml +2 -1
  25. dissolve-0.2.0/tests/test_ast_utils.py +30 -0
  26. dissolve-0.2.0/tests/test_attribute_deprecation.py +139 -0
  27. dissolve-0.2.0/tests/test_check.py +143 -0
  28. dissolve-0.2.0/tests/test_class_methods.py +315 -0
  29. dissolve-0.2.0/tests/test_class_wrapper_deprecation.py +154 -0
  30. dissolve-0.2.0/tests/test_cli.py +863 -0
  31. dissolve-0.2.0/tests/test_comprehensive_replacements.py +555 -0
  32. dissolve-0.2.0/tests/test_decorator.py +183 -0
  33. dissolve-0.2.0/tests/test_decorator_dependencies.py +119 -0
  34. dissolve-0.2.0/tests/test_docstring_extension.py +149 -0
  35. dissolve-0.2.0/tests/test_edge_cases.py +345 -0
  36. dissolve-0.2.0/tests/test_formatting_edge_cases.py +357 -0
  37. dissolve-0.2.0/tests/test_formatting_preservation.py +570 -0
  38. dissolve-0.2.0/tests/test_migrate.py +775 -0
  39. dissolve-0.2.0/tests/test_remove.py +372 -0
  40. dissolve-0.2.0/tox.ini +8 -0
  41. dissolve-0.1.0/PKG-INFO +0 -165
  42. dissolve-0.1.0/README.rst +0 -138
  43. dissolve-0.1.0/dissolve/__main__.py +0 -203
  44. dissolve-0.1.0/dissolve/decorators.py +0 -150
  45. dissolve-0.1.0/dissolve/migrate.py +0 -430
  46. dissolve-0.1.0/dissolve/remove.py +0 -272
  47. dissolve-0.1.0/dissolve.egg-info/PKG-INFO +0 -165
  48. dissolve-0.1.0/dissolve.egg-info/SOURCES.txt +0 -22
  49. dissolve-0.1.0/tests/test_ast_utils.py +0 -127
  50. dissolve-0.1.0/tests/test_cli.py +0 -317
  51. dissolve-0.1.0/tests/test_decorator.py +0 -62
  52. dissolve-0.1.0/tests/test_migrate.py +0 -238
  53. dissolve-0.1.0/tests/test_remove.py +0 -186
  54. {dissolve-0.1.0 → dissolve-0.2.0}/COPYING +0 -0
  55. {dissolve-0.1.0 → dissolve-0.2.0}/dissolve.egg-info/dependency_links.txt +0 -0
  56. {dissolve-0.1.0 → dissolve-0.2.0}/dissolve.egg-info/entry_points.txt +0 -0
  57. {dissolve-0.1.0 → dissolve-0.2.0}/dissolve.egg-info/top_level.txt +0 -0
  58. {dissolve-0.1.0 → dissolve-0.2.0}/setup.cfg +0 -0
  59. {dissolve-0.1.0 → dissolve-0.2.0}/setup.py +0 -0
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: Disperse configuration
3
+
4
+ "on":
5
+ push:
6
+ branches: [ main, master ]
7
+
8
+ jobs:
9
+ build:
10
+
11
+ runs-on: ubuntu-latest
12
+
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+ - uses: jelmer/action-disperse-validate@v2
@@ -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,7 @@
1
+ dist
2
+ __pycache__
3
+ *.egg-info
4
+ .tox
5
+ *~
6
+ *.swp
7
+ build/
@@ -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!
@@ -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)