Getting Started with Sourcery for VSCode¶
Installation¶
- Click to open the Sourcery extension in VS Code and click the install button
OR
- Go to the VS Code Preferences menu and select Extensions
- Search for Sourcery and click Install
Login¶
Login by opening the command palette (Ctrl/Cmd+Shift+P
) and running
Sourcery: Login
.
Seeing Your First Suggestions¶
When you first install Sourcery you should see a welcome file open in VS Code. This will include a few instructions for getting started and a demo function with a suggested refactoring.
Any suggestion from Sourcery will be highlighted/underlined. Hover your mouse over the underlined/highlighted section to see a description of the proposed change and a diff of the changes. There are three ways to interact with a Sourcery suggestion:
- Select the highlighted line & open up the
Quick Fix
menu (usually
Cmd .
orCtrl .
) to bring up the menu of Sourcery actions to accept or skip the change. - Click on the lightbulb icon next to the underlined line and then select to accept the refactoring
- Open the Problems pane, right click on the suggested refactoring, and select the suggested change.
You can also try out Sourcery by copying this code into a Python file in VS Code:
def merge_nested_if(a, b):
if a:
if b:
return c
Sourcery will suggest merging together the nested if statements so you get:
def merge_nested_if(a, b):
if a and b:
return c
Accept a Suggestion¶
There are three ways to accept Sourcery's proposed changes in the editor:
- Place your cursor on one of the lines Sourcery has highlighted, and press the
"Quick Fix" combination "
Ctrl/Cmd
+.
". This will bring up a menu. The first menu item contains a brief description of the change that will be made. Press "Enter
" to select it.
- Hover over one of the lines Sourcery has highlighted. Scroll to the bottom of the pop-up window, and select "Quick Fix" from the buttons at the bottom:
This will bring up a menu. The first menu item contains a brief description of the change that will be made. Click to select the first menu item:
- Place your cursor on one of the lines Sourcery has highlighted. A lightbulb icon will appear to the left of the line you've selected. Click on it to bring up a menu. The first menu item contains a brief description of the change that will be made. Click it to apply the change:
Sourcery Hub¶
The Sourcery Hub allows you to quickly configure Sourcery. To open it, find the
section on the status bar which says Sourcery
and click on it. The hub should
then open in a new tab in your editor.
The Project Config
screen allows you to switch Sourcery rules on and off. When
you do so it will edit or create a .sourcery.yaml
file in your project. This
is the configuration file used by Sourcery.
You can also go to the Your Plan
section to get information about your
Sourcery account, and the benefits of upgrading to Pro
and Team
accounts.
Skip a Suggestion¶
You can skip a Sourcery suggestion once by choosing the skip option from the Sourcery action items menu:
- Press the quickfix shortcut (typically
Ctrl .
orCmd .
) when you have selected the underlined line and then choose to skip the refactoring - Click on the lightbulb icon next to the underlined line and then select to skip the refactoring
- Open the Problems pane, right click on the suggested refactoring, and select to skip the refactoring.
You can also tell Sourcery not to suggest anything or a specific type of rule for a function.
-
Add a comment
# sourcery skip
to a function to skip all rules for that function -
Add a comment
# sourcery skip: <rule-id>
to a function to skip the specific rule in that function. A full list of rules and their IDs are available at: - JavaScript Rules.
Permanently Ignore a Type of Refactoring¶
You can choose to never see a certain type of refactoring when it is suggested
to you by Sourcery. Bring up the Quick Fix menu and select the third menu item
Sourcery - Never show me this refactoring
.
Sourcery will then add this refactoring to your list of
excluded refactorings. You can
reverse this by going to your project's sourcery.yaml file and removing the
refactoring from the skip
list.
Another quick way to achieve this is to open the Sourcery Hub and unselect the
rule in the Project Settings
section.
See Code Quality Metrics¶
Sourcery gives each of your functions a quality score on 4 different metrics:
- Complexity
- Method Length
- Working Memory
- Overall Quality
To see the metrics for any function, simply hover your mouse of the line defining the function and the Sourcery metrics will pop up. Each metric will have a numeric score, along with a quick qualitative guide ranging from bad to excellent.
Sourcery will also automatically flag functions with too low of an overall quality score. By default this is set for functions with a quality score under 25%, but you can adjust this threshold.
Create Custom Rules¶
Sourcery allows you to create your own rules. These are defined in your Sourcery configuration file.
As a shortcut to creating rules you can select any piece of Python code,
right-click and choose the Sourcery
> Create custom rule
option. This will
create or open your project's Sourcery configuration file, with a rule defined
which has that piece of selected code as a pattern to match against. Sourcery
will then start flagging occurences of this code, showing the description
provided.
You can then generalise this pattern by using captures, add replacement code, or specify which paths this rule should apply to.
Advanced Features¶
There are more advanced ways you can improve your code with a Sourcery Pro or Sourcery Team subscription:
Detect Duplicate (and Near Duplicate) Code¶
Sourcery can help you find duplicate sections of code across your project.
- Right click on files or folders in the Explorer window
- Hover over the Sourcery menu item and select "Detect clones"
- A list of duplicate and near duplicate sections of code will appear in the Problems pane.
By default Sourcery will flag exact duplicates as well as near duplicates (sections of code that almost match, except for some altered parameters).
Extract Duplicate Code Into Methods¶
Sourcery will automatically detect opportunities for repeated or nearly repeated sections of code within a function to be extracted out into their own methods. When these refactorings are suggested, the new methods will be given a generic name based on the function it was extracted from and you can easily rename it.
Full Project or Multi-File Code Review¶
You can have Sourcery review multiple files, a folder, or an entire project at once:
- Right click on the folder or file you're interested in.
- Hover over the Sourcery menu item and select "Scan with Sourcery"
- Suggestions will appear in the Problems pane
Configuring Sourcery¶
See our section on Configuring Sourcery for details on customizing your Sourcery configuration.