Code Quality Assistance Tips and Tricks, or How to Make Your Code Look Pretty?
This tutorial aims to walk you step by step through creating source code in a Python project, with the use of PyCharm's code intelligence features. You will see how PyCharm helps keep your source code in perfect shape, with proper indentations, spaces, imports etc. - actually, you'll see that PyCharm itself is a code quality tool.
Python programming is out of scope of this tutorial. For more information about the Python language, please refer to the official website.
Make sure that:
You are working with PyCharm version 5.0 or later. If you still do not have PyCharm, download it from this page. To install PyCharm, follow the instructions, depending on your platform. For more information, refer to the product documentation.
You have created a Python project (File|New Project...). For more information, refer to product documentation.
You have created two directories src and test_dir (File|New or AltInsert).
You have added Python files to the src and test_dir directories of your project(File|New or AltInsert). For more information about creating files, refer to the section Populate projects.
Create a new Python file src/Solver.py AltInsert. The created file immediately opens for editing. The file by default has no contents - this is because the file Solver.py is created by a file template that (in the case of Python files) contains just nothing.
Next, start typing the keyword class
. When you just start typing, PyCharm immediately shows the suggestion list to complete your code:
![py_code1.png py_code1.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_code1.png)
For more information, refer to Code Completion page of the product documentation.
The red curve marks the next expected entry - in this case, this is the expected identifier. Enter the class name Solver
. The red curve moves after the class name. If you hover over this curve, you see the error description ("Colon expected"). Also, mind the red error stripe in the right gutter - it also marks the same error:
![py_colon_expected.png py_colon_expected.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_colon_expected.png)
OK, type the colon, and press Enter. According to the Python code style, the next statement is indented. If by chance you press space after Enter, you will thus violate the code style settings.
However, by default these violation are but weak warnings, and as such, are not visible. So, at first, let's raise their importance. Click on the main toolbar, on the Inspections page of the Settings dialog, type PEP8 to find all PEP8-related inspections, and from the Severity drop-down list, choose Warning:
![py_inspection_severity.png py_inspection_severity.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_inspection_severity.png)
Apply the changes and close the dialog. Now let's return to our source code.
Now PyCharm shows its best! It stands on guard to protect your code style integrity. You immediately note that indented space is highlighted, and, when you type the next statement, for example, def demo(self,a,b,c):
, PyCharm will show the message from the PEP8 inspection:
![py_inspection_pep8.png py_inspection_pep8.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_inspection_pep8.png)
So, as you can see, PyCharm supports PEP8 as the official Python style guide. If you explore the list of inspections (CtrlAlt0S - Inspections), you will see that PyCharm launches the pep8.py tool on your code, and pinpoints the code style violations.
Btw, look at the Inspections more attentively. If you have just opened this page, you refer to the default inspection profile with the default settings: it means that the inspections apply to all the sources of the current project.
Let's try to customize this profile for two different scopes:
In the Test scope, the spelling errors should be marked as typos (green)
In the Production scope, the spelling errors should be marked as errors (red) - can we actually produce code with typos?
This is how it's done...
First, let's define the two scopes. To do that, click on the main toolbar, in the Settings dialog expand the node Appearance and Behavior, open the page Scopes. Then click
and choose scope type Local.
In the Add New Scope dialog, type the scope name (Test), and then, in the project tree, choose the directory to be included in the Test scope, test_dir. Note that the Pattern field is filled in automatically, as you include the directory:
![py_scope_test.png py_scope_test.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_scope_test.png)
Repeat this process to create the Production scope.
Next, let's create a copy of the default profile (though this profile is editable... just to be on the safe side):
![py_copy_profile.png py_copy_profile.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_copy_profile.png)
and give it a new name, for example, MyProjectProfile. This new profile is a copy of the default one, and has the same set of inspections.
With this new profile selected, let's locate the Spelling inspection and change it. To find the Spelling inspection (we've already done it before), just type spel
in the search area.
What's next? Click In All Scopes button and select the Test scope from the list; repeat same for the Production scope
![py_spel_test_scope.png py_spel_test_scope.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_spel_test_scope.png)
In the scope "Test", the inspection severity is left as-is (a typo); however, the scope "Production" we'll choose "Error" from the list of severities:
![py_spel_production_scope.png py_spel_production_scope.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_spel_production_scope.png)
Mind the color code of inspections. They are shown black if unchanged. If they are blue, then it means that they have been changed.
Apply the changes and close the dialog.
So, the modified inspection profile is ready. Its name is Project Default (copy), and it has different settings for the Spelling inspection in the Test and Production scopes. Next, let's inspect code against this profile. To do that, go to Code | Inspect Code in the main menu, and in the dialog, choose the desired profile and scope:
![py_inspect_code_against_scope.png py_inspect_code_against_scope.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_inspect_code_against_scope.png)
Do it twice - for Test and Production scopes (if you want to preserve inspection results for further examination and sharing, you can export them). Explore results:
![py_spel_inspection.png py_spel_inspection.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_spel_inspection.png)
Besides coding style violations, PyCharm highlights the other errors too, depending on the selected profile.
For example, if your inspection profile includes Python inspection Unresolved references, and you use a symbol that not yet has been imported, PyCharm underlines the unresolved reference and suggests to add import statement:
![py_import.png py_import.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_import.png)
For more information, refer to this article.
PyCharm provides lots of possibilities to automatically generate code. You can explore the auto-generation features in the product documentation. Let's explore the main code generation procedures. To do that, just delete all contents of the file Solver.py, and start from scratch.
First, create an instance of a class:
![py_create_instance_of_a _class.png py_create_instance_of_a _class.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_create_instance_of_a%20_class.png)
Next, press AltEnter and choose the intention action Create class 'Solver':
![py_create_class_intention_action.png py_create_class_intention_action.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_create_class_intention_action.png)
Great! PyCharm has stubbed out a class:
![py_create_class_stub.png py_create_class_stub.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_create_class_stub.png)
Next, let's add a method to the class instance. To do that, type a dot after class instance, and then type the method name. This method does not yet exist, and PyCharm suggests to create one:
![py_create_method_in_class.png py_create_method_in_class.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_create_method_in_class.png)
Let's do some manual work - type the source code. When it comes to calculate the discriminant, we have to extract a square root. There is a dedicated function sqrt
in the library math
, but it is not yet imported. OK, let's type it anyway, and see how PyCharm copes with it. Press AltEnter and choose Import 'math':
![py_create_import.png py_create_import.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_create_import.png)
So, we've come to the source code like this:
import math
class Solver(object):
def demo(self,a,b,c):
d = b ** 2 - 4 * a * c
disc = math.sqrt(d)
root1 = (- b + disc) / (2 * a)
root2 = (- b - disc) / (2 * a)
print (root1, root2)
return root1, root2
However, it lacks some significant analysis. We'd like to analyze the radicand d
. If it is zero or positive, then the discriminant and the equation roots will be calculated; when the radicand is negative, let's raise an exception. How PyCharm will help complete this task?
Let's surround a block of code with if
construct. Select the statements to be completed, when d
is non-negative, and press CtrlAlt0T (or select Code | Surround with from the main menu):
![py_surround_code.png py_surround_code.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_surround_code.png)
Select if
option from the suggestion list. As you see, PyCharm automatically adds if True:
and indents the selected lines:
![py_surround_added.png py_surround_added.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_surround_added.png)
We are not at all interested in a boolean expression, so let's change the selected True
to d >= 0
. Next, place the caret at the end of the last line, and press Enter. The caret rests on the next line, with the same indentation as the if
statement; type the else: clause here
, and see PyCharm reporting about the expected indentation:
![py_else_indent_expected.png py_else_indent_expected.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_else_indent_expected.png)
When you press Enter again, the caret rests at the indented position. Here you can type the exception expression, using PyCharm's powerful automatic code completion:
![py_completing_code.png py_completing_code.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_completing_code.png)
Let's look again at our Solver.py file. Its right gutter shows yellow stripes. When you hover over a stripe, PyCharm shows the description of the corresponding problem in the code:
![py_warnings.png py_warnings.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_warnings.png)
The good news is that they are but warnings, and won't affect the results. Bad news is they are too numerous to fix each one by one. Is it possible to make the source code nice and pretty without much fuss?
PyCharm says - yes. This is the code reformatting feature. So let's try to change formatting of the entire file. To do that, press CtrlAlt0L (or select Code | Reformat Code from the main menu):
![py_reformat_code_done.png py_reformat_code_done.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_reformat_code_done.png)
Look at the code now - the PEP8-related drawbacks are all gone.
Note that you can define formatting rules yourself. To do that, open the code style settings, select language (in this case, Python), and make the necessary changes:
![py_reformat_code_settings.png py_reformat_code_settings.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_reformat_code_settings.png)
OK, formatting is fixed now, but there are still some stripes left. The inevitable yellow light bulb shows the possibility to add a docstring comment:
![py_intention_docstrings.png py_intention_docstrings.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_intention_docstrings.png)
Choose this suggestion and see the docstring comment for a certain parameter added:
![py_intention_docstrings_done.png py_intention_docstrings_done.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_intention_docstrings_done.png)
Note that you have to select the checkbox Insert type placeholders in documentation comment strings in the Smart Keys page of the Editor settings:
![py_insert_type_placeholder_setting.png py_insert_type_placeholder_setting.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_insert_type_placeholder_setting.png)
There are several docstring formats, and the documentation comments are created in the format, which you have selected in the Python Integrated Tools page. If you so wish, you can change the docstring format to, say, Epytext or plain text.
The documentation comments can be used to define the expected types of parameters, return values, or local variables. Why do we need it all? For example, we'd like to keep under control the types of parameters we pass to the demo()
method. To do that, let's add the corresponding information to the documentation comment (By the way, mind code completion in the documentation comments!):
![py_docstrings_completion.png py_docstrings_completion.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_docstrings_completion.png)
Next, when you look at the method invocation, you see that the wrong parameter is highlighted by the PyCharm's inspection Type Checker:
![py_type_checker.png py_type_checker.png](https://resources.jetbrains.com/help/img/idea/2023.3/py_type_checker.png)
Learn more about type hinting in the PyCharm documentation.
Thanks for your feedback!