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