Deprecated API Updater

Identify and replace deprecated API usage with modern alternatives automatically.

Quick Start

Detect Deprecated APIs

Scan code to identify deprecated API usage:

# Scan a single file
python scripts/detect_deprecated_apis.py src/app.py

# Scan entire directory
python scripts/detect_deprecated_apis.py src/

# Specify language explicitly
python scripts/detect_deprecated_apis.py legacy/ --language python

# Output as JSON
python scripts/detect_deprecated_apis.py src/ --format json

Replace Deprecated APIs

Automatically replace deprecated APIs:

# Dry run (preview changes)
python scripts/replace_deprecated_apis.py src/ --dry-run

# Apply replacements (creates .bak backups)
python scripts/replace_deprecated_apis.py src/

# Replace in specific language
python scripts/replace_deprecated_apis.py src/ --language javascript

Supported Languages

Python

• Standard library (collections, time, os, platform, imp)
• Django (URL routing, encoding, translation, models)
• Flask (JSON handling, send_file)
• SQLAlchemy, Pandas, NumPy, Requests

See python_deprecations.md for complete reference.

JavaScript/TypeScript

• Node.js core (Buffer, url, crypto, fs, util)
• React (lifecycle methods, createClass, PropTypes, Context)
• Express.js (body-parser)
• Webpack, Moment.js alternatives

See javascript_deprecations.md for complete reference.

Java

• Java core (Date/Calendar, Thread methods, finalize)
• Spring Framework (WebMvcConfigurerAdapter, RestTemplate)
• Hibernate (Criteria API)
• JUnit 4 → JUnit 5
• Android (AsyncTask, ProgressDialog, startActivityForResult)

See java_deprecations.md for complete reference.

Other Languages

• Ruby: URI.escape, Dir.exists?, File.exists?
• Go: ioutil package functions

Detection Methods

AST-Based Detection (Precise)

For Python and JavaScript, the skill uses Abstract Syntax Tree parsing for accurate detection:

• Advantages: Precise, understands code structure, fewer false positives
• Limitations: Requires parseable code, language-specific implementation

Example: Detects os.popen() by analyzing the AST node structure, not just string matching.

Pattern Matching (Fast)

For all languages, regex-based pattern matching provides fast detection:

• Advantages: Works across all languages, fast, handles unparseable code
• Limitations: May have false positives, less precise

Both methods are used together for comprehensive detection.

Workflow

1. Scan for Deprecations

Run detection to identify deprecated APIs:

python scripts/detect_deprecated_apis.py src/

Output example:

Found 3 deprecated API usage(s):

📍 src/utils.py:5:0
   Deprecated: collections.Mapping
   Replacement: collections.abc.Mapping
   Context: from collections import Mapping
   Detection: ast

📍 src/legacy.py:12:9
   Deprecated: os.popen()
   Replacement: subprocess.run() or subprocess.Popen()
   Context: result = os.popen('ls')
   Detection: ast

2. Review Suggestions

Examine the detected deprecations and suggested replacements. Check the reference documentation for detailed migration guides.

3. Test Replacements (Dry Run)

Preview changes before applying:

python scripts/replace_deprecated_apis.py src/ --dry-run

Output shows:

• What will be replaced
• Line-by-line changes
• Deprecated API → Replacement API mapping

4. Apply Replacements

Apply changes with automatic backups:

python scripts/replace_deprecated_apis.py src/

Creates:

• .bak backup files for all modified files
• Updated source files with modern APIs

5. Validate Changes

Critical: Always validate after replacement:

# Run tests
npm test  # JavaScript
pytest    # Python
mvn test  # Java

# Run linters
eslint src/     # JavaScript
flake8 src/     # Python
mvn checkstyle  # Java

# Manual testing
# Test critical functionality

6. Commit Changes

Once validated:

# Review changes
git diff

# Commit
git add .
git commit -m "Replace deprecated APIs with modern alternatives"

# Remove backup files
find . -name "*.bak" -delete

Best Practices

Before Replacement

1. Create a branch: git checkout -b fix/deprecated-apis
2. Commit current state: Ensure working directory is clean
3. Run tests: Verify tests pass before changes
4. Review deprecation docs: Check reference files for context

During Replacement

1. Start with dry run: Always preview changes first
2. Replace incrementally: Process one module/directory at a time
3. Keep backups: Don't delete .bak files until validated
4. Check imports: Some replacements require new imports

After Replacement

1. Run full test suite: Catch any breaking changes
2. Check build output: Look for new warnings
3. Manual testing: Test critical user flows
4. Update dependencies: Install any newly required packages
5. Code review: Have team members review changes

Common Scenarios

Scenario 1: Upgrading Django 2.x → 3.x

Deprecations:

• django.conf.urls.url → django.urls.path
• force_text() → force_str()
• ugettext → gettext

Process:

# Detect Django-specific deprecations
python scripts/detect_deprecated_apis.py myproject/ --language python

# Preview replacements
python scripts/replace_deprecated_apis.py myproject/ --dry-run

# Apply
python scripts/replace_deprecated_apis.py myproject/

# Test
python manage.py test

Scenario 2: Upgrading React 17 → 18

Deprecations:

• ReactDOM.render() → ReactDOM.createRoot()
• Unsafe lifecycle methods → Modern alternatives

Process:

# Detect React deprecations
python scripts/detect_deprecated_apis.py src/ --language javascript

# Manual review needed for complex cases
# Some React upgrades require structural changes

# Apply simple replacements
python scripts/replace_deprecated_apis.py src/ --dry-run
python scripts/replace_deprecated_apis.py src/

# Test
npm test
npm start  # Manual testing

Scenario 3: Modernizing Python Standard Library Usage

Deprecations:

• collections.Mapping → collections.abc.Mapping
• time.clock() → time.perf_counter()
• os.popen() → subprocess.run()

Process:

# Scan codebase
python scripts/detect_deprecated_apis.py . --language python --format json > deprecations.json

# Review JSON output
cat deprecations.json

# Apply replacements
python scripts/replace_deprecated_apis.py . --dry-run
python scripts/replace_deprecated_apis.py .

# Run tests
pytest

Limitations and Caveats

Automatic Replacement Limitations

1. Context-dependent changes: Some deprecations require understanding business logic
2. Complex refactoring: Major API redesigns may need manual intervention
3. Imports: New imports may need to be added manually
4. Breaking changes: Some replacements change behavior subtly

Manual Review Required

Always manually review replacements for:

• Security-sensitive code (authentication, encryption)
• Performance-critical sections (may need optimization)
• Complex logic (ensure semantics unchanged)
• Public APIs (breaking changes for consumers)

Known Edge Cases

1. Dynamic imports: May not detect importlib.import_module('collections').Mapping
2. Aliased imports: May not detect import collections as c; c.Mapping
3. Conditional code: Replacements in dead code paths
4. Comments: May replace deprecated API mentions in comments

Troubleshooting

Detection Issues

Problem: Deprecations not detected

Solutions:

• Check file extension matches language
• Use --language flag explicitly
• Verify file is parseable (no syntax errors)
• Check if pattern exists in deprecation database

Problem: False positives

Solutions:

• Review AST vs pattern detection method
• Check if it's actually deprecated in your version
• Report false positives for pattern refinement

Replacement Issues

Problem: Replacement breaks code

Solutions:

• Restore from .bak files
• Review reference documentation for proper usage
• Check if imports need updating
• Manually refactor complex cases

Problem: Tests fail after replacement

Solutions:

• Check test expectations (mocking, assertions)
• Update test fixtures if API signatures changed
• Review behavior changes in reference docs
• Consider phased replacement approach

Reference Documentation

Language-Specific Guides

• python_deprecations.md: Python standard library, Django, Flask, SQLAlchemy, Pandas, NumPy
• javascript_deprecations.md: Node.js, React, Express, Webpack, Moment.js
• java_deprecations.md: Java core, Spring, Hibernate, JUnit, Android

Each guide includes:

• Deprecated API examples
• Modern replacement examples
• Migration rationale
• Code samples (before/after)

Advanced Usage

Custom Detection Patterns

To add custom deprecation patterns, edit the scripts:

scripts/detect_deprecated_apis.py:

DEPRECATION_PATTERNS = {
    'python': [
        # Add your patterns
        (r'your\.deprecated\.api\(', 'your.deprecated.api()', 'modern.api()'),
    ]
}

scripts/replace_deprecated_apis.py:

REPLACEMENT_RULES = {
    'python': [
        # Add your replacements
        (r'your\.deprecated\.api\(', r'modern.api(', 'deprecated', 'modern'),
    ]
}

Integration with CI/CD

Detect deprecations in CI:

# .github/workflows/deprecation-check.yml
name: Check Deprecations
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check for deprecated APIs
        run: |
          python scripts/detect_deprecated_apis.py src/ --format json > deprecations.json
          if [ -s deprecations.json ]; then
            echo "Deprecated APIs found!"
            cat deprecations.json
            exit 1
          fi

Batch Processing

Process multiple projects:

#!/bin/bash
for project in project1 project2 project3; do
    echo "Processing $project..."
    python scripts/detect_deprecated_apis.py "$project/src" > "$project-report.txt"
    python scripts/replace_deprecated_apis.py "$project/src" --dry-run
done