Getting Started with Sourcery for the Command Line¶
Installation¶
Sourcery command line interface can be installed by running:
pip install sourcery
Login¶
If you are working on open source code you don't need to log in - Sourcery will detect if your repo is open source.
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
Create an Initial Config (Optional)¶
You can create a .sourcery.yaml
config file with some sensible defaults:
sourcery init config
The main setting you might want to change is ignore
. This specifies which
files and directories aren't reviewed by Sourcery. Generally, you want to
ignore:
- anything in
.gitignore
- any 3rd party code
Sourcery does by default ignore certain directories, for example venv
and node_modules
.
The full configuration including these defaults is described
here.
Set up Sourcery in pre-commit and CI (Optional)¶
The sourcery init
command also allows you to configure Sourcery as a pre-commit hook.
sourcery init pre-commit
This will either add Sourcery to your existing pre-commit configuration, or create a new pre-commit configuration file for you.
To view instructions on using Sourcery in CI, you can run:
sourcery init ci
For more information on running Sourcery in pre-commit or CI:
- as a pre-commit hook
- in your CI
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
Fixing Code Quality Issues¶
To apply the changes suggested by Sourcery, use the --fix
option:
sourcery review --fix {file_or_directory}
Reviewing Code with the Google Python Style Guide¶
Sourcery contains a rule package based on the Google Python Style Guide. To
review your code with that rule package, you can use the --enable
option:
sourcery review --enable google-python-style-guide .
To use the style guide rules, as well as the default rules, you can run:
sourcery review --enable default --enable google-python-style-guide .
Reviewing Only Changed Code¶
If you want to introduce Sourcery incrementally in your project, a great way to
achieve this is to review only the code you're currently adding. For that, you
can use the --diff
option.
To review only code that hasn't been committed yet:
sourcery review --diff "git diff" .
To review the diff compared to the main branch:
sourcery review --diff "git diff main" .
Only Applying Specific Rules¶
To apply specific Sourcery refactoring rules or tags, you can use the --enable
option multiple times:
sourcery review --fix --enable use-fstring-for-concatenation --enable 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.
Further Info¶
For more about the various features and options of the CLI, check out the reference docs