Skip to content

Getting Started with Sourcery for the Command Line

Info

The Sourcery CLI is now available for all registered users, incl. the Free Plan. Try it out and give us some feedback.

Installation

Sourcery command line interface can be installed by running:

pip install sourcery-cli

Login

Once installed you need to log in with:

sourcery login

which will open up a browser tab and ask for confirmation. This is only needed once per computer.

You can also log in via providing your token:

sourcery login --token YOUR_TOKEN

Reviewing Code with the CLI

To review a file or a directory (recursively) with Sourcery, use the sourcery review command:

sourcery review example_file.py

To apply the changes suggested by Sourcery, use the --in-place option:

sourcery review --in-place {file_or_directory}

Running Sourcery in the Command Line

Only Applying Specific Rules

To apply specific Sourcery refactoring rules, you can use the --include (or -i) option multiple times:

sourcery review --in-place -i use-fstring-for-concatenation -i use-named-expression {file_or_directory}

Note that this will override the skip refactorings configuration in your sourcery.yaml project and user configuration. It will respect the source code skip comments, as well as the python version you have configured.

Command Line Options

Sourcery provides a few options for running. You can list them by running sourcery review --help

sourcery review --help


Usage: sourcery review [OPTIONS] [SRC]...

  Review SRC files/directories. Reads from stdin when SRC is -

Options:
  -c, --code TEXT     Refactor the code passed in as a string.
  -i, --include TEXT  Only run the specified rule. This option can be used
                      multiple times.
  --exclude TEXT      Do not run the specified rule. This option can be used
                      multiple times.
  --check             Return exit code 1 if unsolved issues found.
  --in-place          Make changes to files in place
  --config-path FILE  Path of the custom project config YAML file
  --csv               Output in CSV format
  -h, --help          Show this message and exit.

Pre-Commit Hook

Sourcery works great with pre-commit. Once you have it installed, add this to the .pre-commit-config.yaml in your repository:

repos:
  - repo: https://github.com/sourcery-ai/sourcery
    rev: v0.12.9
    hooks:
      - id: sourcery
        # If you want Sourcery to automatically apply the suggested changes,
        # add the `--in-place` option:
        args: [--in-place]

If Sourcery is the first pre-commit hook that you've added to your project, you'll also need to run pre-commit install.

Notes
  • Initializing the environment for the Sourcery pre-commit hook might take some minutes.
  • When the Sourcery pre-commit hook runs for the first time, you might be prompted to log in to Sourcery. Run the sourcery login command as described above. For further runs of the Sourcery pre-commit hook, this login step isn't necessary .

Continuous Integration

Here's a script to run Sourcery in CI that will fail the job if any refactorings are found:

# Install sourcery
pip install sourcery-cli
# Login - store SOURCERY_TOKEN in a secret/masked environment variable
sourcery login --token $SOURCERY_TOKEN
# Find changed files and pass them to Sourcery
git diff main --diff-filter=AMR --name-only | xargs sourcery refactor --check

Configuring Sourcery

Sourcery reads configuration settings from .sourcery.yaml in the project directory. Full details are described here.