Getting Started with Sourcery for VSCode

Installing Sourcery

1. Open the Sourcery extension in VS Code and click the install button

OR

1. Go to the VS Code Preferences menu and select Extensions
2. Search for Sourcery and click Install

Logging In

Login by opening the command palette (Ctrl+Shift+P or Cmd+Shift+P) and running Sourcery: Login.

If you do not have a Sourcery account you can sign up for one here.

Opting Into the Coding Assistant

Sourcery’s Coding Assistant is our AI powered tool that you can chat with and can also use to do things like generate docstrings or tests, explain sections of code, or provide you with code reviews. The Coding Assistant uses third party large language models (LLMs) to handle some of the conversations and analysis, so in order to use it we need to send messages and relevant code snippets to these third parties.

Before starting to use the Coding Assistant you need to opt in to consent to send these messages and code snippets to third parties. To opt-in:

• Click the Sourcery icon on the sidebar (the orange hexagon) or run the Sourcery: Focus on Coding Assistant View command from the VS Code command palette
• If you have not completed the opt-in you’ll be prompted to do so before you use the Coding Assistant. Click the opt-in button and you’re all set.

When you opt in your user level sourcery.yaml config file will be updated to include:

coding_assistant:
  enabled: true

To opt out in the future you can change the enabled status to False.

While the Coding Assistant is disabled you can continue to see Code Quality metrics and the in-line code suggestions based on our hundreds of best practices for Python, JavaScript, and TypeScript. All the analysis for these rules is conducted locally.

Chatting with the Coding Assistant

Once you’ve opted into the Coding Assistant you can start interacting with it. You can ask a question right away - try asking it to write you code for any purpose or ask it a general coding question.

To have it update existing sections of your code or answer a question about a specific piece of your code, highlight that section first in your IDE and then type your question into the Coding Assistant sidebar.

Generate Tests & Docstrings

Sourcery can generate tests and docstrings for your code on demand. The easiest way to start is to click the Generate Test or Generate Docstring code lens above a function. This will immediately start to generate tests or a docstring in the sidebar.

You can then click the “copy” button to copy the generated code, or the “inset at cursor” button to add the code into your open file at your cursor’s current location.

You also can select a section of code, go to the “Recipes” tab of the sidebar and choose the Generate Test or Generate Docstring button to generate tests or a docstring for that selected section of code.

Review Your Code

Click on the Review Code tab in the Sourcery sidebar to bring up the Code Review mode. In this mode Sourcery will review the diff of your uncommitted changes to a branch (typically main) or the diff between two branches and generate a code review based on those changes.

It will try to provide you with a high level summary of the changes, a high level review for those changes, and then specific comments about the changes that you can then choose to apply or not.

Select the two branches you want to compare and click the Review button to start your first review.

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 (Ctrl+. or Cmd+.) 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:

1. Place your cursor on one of the lines Sourcery has highlighted, and press the "Quick Fix" combination (Ctrl+. or 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.

1. 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:

1. 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.

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 (Ctrl+. or Cmd+.) 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:

• Python Rules.

• 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.

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.

Configuring Sourcery

See our section on Configuring Sourcery for details on customizing your Sourcery configuration.