django-codemod

Django Codemod is a tool designed to automate the upgrading of Django projects to newer versions of the framework. It works by automatically fixing deprecations and rewriting code from old patterns to new ones using AST (Abstract Syntax Tree) analysis.

Key capabilities include:

• Rewriting API usages (e.g., converting url() to re_path() or path()).
• Intelligent decision-making (e.g., determining if a regex can be replaced by a built-in URL converter).
• Managing imports (removing irrelevant imports and adding missing ones).

The djcodemod tool operates on two primary mental models based on the Django release lifecycle:

1. Deprecation Workflow: Used when you have already upgraded to a new Django version and want to resolve the resulting deprecation warnings. You use --deprecated-in <version> to find and fix code that is still functional but marked for future removal.
2. Removal Workflow: Used as a pre-upgrade step. If you are about to upgrade to a version where certain features have been removed, you use --removed-in <version> to apply the necessary fixes to make your code compatible with that version.

When using django-codemod, keep the following constraints in mind:

• Targeting: The tool is best suited for standalone Django sites rather than reusable Django applications. This is because the tool needs to target a specific Django version (e.g., 3.1.x) to perform accurate transformations.
• Installation: You do NOT need to install this tool as part of your project's production dependencies. It is a CLI tool used during the upgrade process, not a Django package that runs within your site.

To see a list of all available codemodders, their deprecation/removal versions, and their descriptions, use the list subcommand.

djcodemod list

To resolve deprecation warnings introduced in a specific Django version, use the run command with the --deprecated-in option. This workflow is intended for cleaning up code that has been marked as deprecated in a version you have already upgraded to.

Run the command from the root of your repository, targeting specific files or directories.

djcodemod run --deprecated-in 3.0 {source_file_or_directory}

You can automate code migrations by running django-codemod via the pre-commit framework. Add the following configuration to your .pre-commit-config.yaml file.

Note that you should use a version tag greater than v1.2.0 and customize the args to match your specific migration needs (e.g., targeting specific Django versions).

- repo: https://github.com/browniebroke/django-codemod
  rev: v1.2.0
  hooks:
    - id: djcodemod
      args: ["run", "--deprecated-in", "3.0"]

The preferred method for installing Django Codemod is using pipx. This installs the latest stable release into an isolated virtual environment, preventing dependency conflicts with your global Python installation.

Prerequisites:

• Python 3.6 or above
• pipx installed on your system

$ pipx install django-codemod

If you do not want to run all applicable transformations, you can target specific codemodders using the --codemod option. This option can be repeated if you want to run a specific subset of transformations.

djcodemod run --codemod URLTransformer urls.py

Starting from version 1.2.0, django-codemod can be configured to run automatically as a pre-commit hook. This allows you to ensure that your codebase adheres to updated Django patterns every time you commit code.

# Refer to version 1.2.0 features for pre-commit integration