Evrone Python code guidelines for unified, streamlined development

In Python programming, there are many things that developers have to consider and keep in mind when writing code. Those issues and practices differ from company to company and from team to team. At Evrone, we created our own collection of guidelines for Python, in order to build a common denominator for writing code within the company.

What do the Evrone Python guidelines help you to do?

Often, many Python developers find themselves in very similar situations in which they need help finding universal and convenient solutions. Our collection of guidelines explains how to navigate certain situations.

About the Code

The About the Code section describes certain principles for how to write code, so that it is: 

• Firstly, simple and readable
• Secondly, maintainable 
• And thirdly, plain and obvious

To achieve these three characteristics, we have listed certain conditions: atomicity of operations, logical blocks, sizes of methods, functions and modules, docstrings, __init__.py files, and imports.

For example, ​​if we talk about imports, the recommended import method is absolute.

Bad ❌ :

# spam.py
from . import foo, bar

Good ✅ :

# spam.py
from some.absolute.path import foo, bar

Why? Because absolute import explicitly defines the location (path) of the module that is being imported. With relative imports, you always need to remember the path and calculate in your mind the location of the modules foo.py, bar.py relative to spam.py

About Pull Requests

The next section describes the practices that are associated with pull requests. Oddly enough, many developers do not know how to make pull requests, while others do not know how to review them. Often, there are a lot of edits suggested in pull requests (from 1,000 lines or more). When this happens, the edits are difficult to read, making it hard to understand how the code works or how it implements a feature.

Another problem is that programmers often mix several tasks in pull requests. This makes the pull request too big and creates a confusing mess. As it turns out, this is a very common problem that many team leads face. We decided that, since it might be difficult to explain the solution every time in speech, we need to formalize these solutions. So this is how a section about pull requests appeared in the guide.

About Tooling

Another problem we found was that we use different tools on different projects. For example, sometimes we cannot implement some regularly used tools in a project because the project is too large. As for linters (tools that help you improve your code), they need to be connected at the start of the project. It is not possible to connect linters later or at the end of the project, since there will be too many edits and no one will sit down to disassemble them, as this would take a huge amount of time. It would also be very difficult to explain such changes to the client, since, from the client's side, it would look like very long and expensive work.

Therefore, we added a section about tooling (tests, package manager, code formatting, etc.). What problem does it solve? Everyone writes code differently. Among Python developers, everyone has their own preferences for how to write code. So, in order to not argue about individual techniques, there are special tools that rewrite all your code, according to certain rules. We have listed the most convenient tools that we suggest using.

For example, for testing we recommend pytest—a code testing framework. Recommended config in pytest.ini : 

[pytest]
DJANGO_SETTINGS_MODULE = settings.local
python_files = tests.py test_*.py *_tests.py

We use poetry—dependency manager and package builder—as a package manager, and for code formatting, we use Black—PEP8 code auto-formatter.

Recommended config in pyproject.toml :

[tool.black]
line-length = 100
target-version = ['py38']
exclude = '''
(
  \.eggs
  |\.git
  |\.hg
  |\.mypy_cache
  |\.nox
  |\.tox
  |\.venv
  |_build
  |buck-out
  |build
  |dist
)
'''

Other

Another issue we’ve found is that some people do not know how to document what they have done. In the Other section, we suggest using one of the most modern documentation formats—OpenAPI. On the projects we work on, we try to implement OpenAPI documentation so that everything can be generated on the fly. This is a very convenient, unified tool that allows you to bring the specification to a single format.

This documentation format is supported by a large number of clients (Swagger, Postman, Insomnia Designer, and many others). Also, handwritten documentation tends to quickly become outdated, and documentation that is generated directly from the code allows you to avoid constantly thinking about updating the documentation.

Conclusion

With these guidelines, we hope to solve the common problems that programmers face while writing Python code.

These guidelines are useful:

• At the stage of hiring a developer. Even before the start of work, they can see the principles by which our code is written.
• Later, when a developer joins a new project, they can read these guidelines and start using them directly in their work.
• Even if a developer has already been on a project for some time, the team leader can send them links to these guidelines if any difficulties arise.
• And, as we know, programmers are always interested in seeing the principles by which code is written within a company. Thus, we can say that by publishing these guidelines, we open the door for a quick look inside our company.

Our work on open-source projects—and the fact that every month we choose several OSS projects to sponsor—shows our initiative and understanding of what developers love and need. Reach out to us via the form below if you need to develop an open-source solution or are looking for a team of professionals to build a project from scratch!