The company blog for Sourcery, a Python refactoring tool, covering code quality, project setup, code review, and LLM code generation.
Commenters mention the Sourcery tool as one a team adopted by word of mouth and liked, and link its follow-up post on dependency architecture.
To those that wish to automate a subset of these conventions, there is a tool called Sourcery[1] that I, personally, am a huge fan of! Not only does it have a large set of default rules[2], but it can also allow you to write your own rules that may be specific to your team or organization, and as mentioned it can enable you to follow Google's Python style guide as well[3].
There are some refactorings that Sourcery suggest that I don't agree with myself, namely the usage of 'contextlib.suppress'[4] as I don't like to introduce an additional 'import' statement just to do something so trivial. I wish Sourcery would add the relevance of having possibly too many 'import' statements as a heuristic.
---
[1]: https://sourcery.ai/
[2]: https://docs.sourcery.ai/Reference/Default-Rules/ (expand the sub-pages)
[3]: https://docs.sourcery.ai/Reference/Optional-Rules/gpsg/
[4]: https://docs.sourcery.ai/Reference/Default-Rules/refactorings/use-contextlib-suppress/
> So now I have two different black calls: in the pre-commit hook and in the CI/CD. And they must be of the same version.
> Can the framework run off the venv dir?
It can, but it means not using the hooks from the tool's repo and writing your own. This blog post [0] shows the pipenv version of some common hooks; mine look the same but s/pipenv/poetry.
If there's a way to use the upstream hooks with your local venv, so I can trust the tool maintainers for proper configuration, I'd love to know about it.
[0] https://sourcery.ai/blog/python-best-practices/
This (plus Law of Demeter) is the right way to handle medium-big size projects, though I'm not completely sold on the tooling. I mostly do it manually (yes, it is still doable with dozens of modules since dependency hierarchy doesn't change often).
One recommendation I have is to present the hierarchy as DAG. Existing image (https://sourcery.ai/static/05300f06cb847360719e2aa31dc5a31b/8c857/dependencies.png) doesn't make it very obvious that api is a highest-level module, even though it is clearly stated in the rules.
In my experience, the developer tools that really catch on do so via word of mouth. For example, our whole team recently adopted https://sourcery.ai/ (not an ad) because one developer tried it and hyped it up to everyone else who also liked it. Developers are the best kind of customers if you have PMF - they evangelise and actively enjoy debating toolchains.
The hard part is usually building the actually valuable tool.
I find myself coming back to this guide whenever I set up a new project: https://sourcery.ai/blog/python-best-practices/
A follow-up post:
https://sourcery.ai/blog/dependency-architecture/