The Sourcery Coding Assistant¶
Sourcery is an AI pair programmer that saves you time, helps you write better code, and makes programming more fun 🥳
We are focused on helping you understand, review, fix, and improve code. You can also chat with our Coding Assistant at any time to help write new code, explain concepts, or work through problems you’re facing.
Chatting with the Coding Assistant¶
You can ask a question right away - try asking it to write you code for any purpose or ask it a general coding question.
By default the Coding Assistant knows about the context of your current file. You can also select a section of code to ask questions about it or ask it to make edits.
Recipes¶
Recipes are customised prompts that let you quickly perform common tasks in the Chat. These are accessed either through the 'Recipes' button in the Chat tab, or through the code lenses in the editor. You can customise these recipes by configuring custom prompts that will be appended when calling the recipe.
Click on the 'Recipes' button and then click the settings cog next to one of the
recipes to add a custom prompt. These are saved in your user sourcery.yaml
file.
If you would like to set up repo-level custom prompts, you can do so by editing
your project's .sourcery.yaml
file - see
Customising Recipes
for more details.
Generate Diagrams¶
You can use Sourcery to generate diagrams based on the code context available, which is by default the open file.
When you click 'Generate Diagram' a modal will appear with the options to select one of the 3 diagram types:
- Sequence Diagram: A sequence diagram used to visualize the interactions between different components or actors in a system. A good example might be showing the how authentication flow works, with the interactions between front-end, back-end, and database.
- Class Diagram: A class diagram is a type of diagram that is used to visualize the hierarch of classes.
- Flow Chart: A flow chart is a type of diagram that shows the flow of events in a system. A good example might showing the execution flow of a function.
You can also add a text description, to help Sourcery understand what you want to visualize. Both the type and description are optional, but can help Sourcery generate a more accurate diagram.
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.
For tests you can then click the “copy” button to copy the generated code, or the “insert at cursor” button to add the code into your open file at your cursor’s current location. For docstrings you can apply them directly with the "Apply Changes" button.
You also can select a section of code, click the “Recipes” button in the "Chat"
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.
Explain Code¶
Explain Code provides a summary of what the selected code does, how it does it, and any additional important information about the code selection.
Review Your Code¶
Click on the Review Code tab in the Sourcery sidebar to bring up the Code Review mode. Sourcery can review either the current file, your uncommitted changes, or the diff between two branches you choose, 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 what you want to review and click the Review button to start your first review.
Real Time Refactoring Suggestions¶
In Python, JavaScript, and TypeScript Sourcery will also provide real time refactoring suggestions as you write code.
When you first install Sourcery you should see a welcome file open. 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:
- 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.
- 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:
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: - 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 settings of the coding
assistant and unselect the rule in the Rule 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.
Getting Started:¶
Sourcery, including the Coding Assistant, is available in VS Code & JetBrains IDEs.
See our Integrations section for a list of other places you can use Sourcery
Quick Links¶
New to Sourcery? Have a look at one of our Getting Started Guides.
Keen to learn more? Check out how you can use Sourcery to write tests, review code, and write rules for your team’s coding style.
Got a problem? See our FAQs or Troubleshooting guides.
Find all of the above and much more using the navigation menu.
External Resources¶
- Sourcery's Website - for plans, pricing, and the admin dashboard
- GitHub Repository - to report issues or suggest enhancements
- Contact Email - to get in touch