The thing nobody tells you about style guides is that they mostly exist to keep other humans from hating you.
I've been writing Python long enough that I don't bother arguing with linters anymore. You just conform and move on. PEP 8 is the official style guide, but half the people I work with ignore it in favor of Black or Ruff. That's fine. Pick one and stick with it across your project. Here's what actually matters. Indentation is four spaces, not tabs. Lines should be 79 characters or fewer in regular code, 72 for docstrings. You break long lines by wrapping them inside parentheses, not by using backslashes. Backslashes disappear when you least expect them and cause bugs that take three days to track down. Import order is one of the most consistent friction points. Standard library first, then third-party, then local imports. Each group separated by a blank line. I once spent two hours debugging a circular import that was invisible because my team had no agreed-upon import style. A tool like isort will fix this automatically, so just run it and commit the output.
Spacing around operators is non-negotiable. This is wrong: x=1+y*2 This is right:
x = 1 + y * 2 It's a small thing but it compounds across a codebase. Readable code isn't about cleverness. It's about removing ambiguity so the next person doesn't have to parse your intent.
What happens when the guide contradicts itself
PEP 8 says to use lowercase with underscores for function names. It also says module names should be short and lowercase. Fine. Then it says class names use CapWords. And constants are UPPERCASE. The naming conventions are straightforward until you hit something like dataclasses or typed dictionaries, where the line between a class and a type alias blurs. My workaround for this has been simple: I put naming decisions in a shared pyproject.toml under a [tool.ruff] section and let the linter enforce them. I configure ruff with the same rules Black uses, then add a couple of extra rules for consistency. One rule I always add is preview, which catches things the stable release misses. It's not perfect, but it's better than arguing in code reviews.
Counter-intuitive things I learned the hard way
Line length limits are less important than you think. A lot of teams treat 79 or 88 characters as a hard law. In practice, a well-formatted line of 100 characters is easier to read than a broken one at 79 that splits in the middle of a logical expression. I set my formatter to 100 and my editor to a soft wrap at 120. Nobody reads the physical edge of the screen anyway. Another thing people miss: blank lines between methods in a class. PEP 8 says one blank line between top-level functions and classes, and two between methods inside a class. Most formatters handle this automatically. The exception is when you're mixing property decorators with regular methods. The decorator chain can confuse older formatters into collapsing the blank line. I fix this by adding an explicit fmt: off comment around the property block, then reformatting the rest of the file. String formatting is another area where style guides lag behind practice. f-strings are faster than .format() and more readable than percent formatting. They also introduced a whole new category of style debate. Some people insist on using str.format() for internationalization because it plays nicer with gettext. That's fair. But for everything else, f-strings are the default now. PEP 8 doesn't mention them explicitly because they arrived after the document was finalized. Your codebase will still function if you just pick one approach and don't mix them.
Tools that actually help
Ruff is the fastest option right now. It replaces flake8, isort, and several other linters in a single binary. It's also configurable through pyproject.toml, which means your style rules travel with your repo. Black handles formatting. MyPy catches type errors that style issues don't cover. These three together cover almost everything I need. I keep a copy of my preferred configuration here: pyproject.toml template. It's a starting point, not a final answer. You'll adjust it as your project grows. I've seen people spend weeks debating whether to allow or disallow trailing commas. Just pick a default and move on.
When style guides fail
PEP 8 breaks down when you're working with auto-generated code. Protobuf, GraphQL schemas, and database migration files often produce long lines and unusual naming patterns. I disable linting on generated directories by adding a ruff: noqa comment at the top of generated files. That's a pragmatic call, not a compromise. Fighting an auto-formatter over generated code wastes everyone's time. Another edge case: Jupyter notebooks. The standard tools don't handle them well. nbqa exists as a bridge, but it's slow and inconsistent. If your team uses notebooks heavily, consider keeping them separate from your package code and applying style rules only to the .py files they call. The biggest mistake I see is treating a style guide as a learning objective instead of a maintenance tool. Nobody reads PEP 8 cover to cover. You reference it when something is unclear. The real value is in automation. A good CI pipeline that runs ruff and black on every push saves more time than any amount of manual code review on whitespace.
I still encounter arguments about whether to put opening brackets on the same line or the next. It doesn't matter. What matters is that the whole team agrees on one style and the formatter enforces it without human intervention. The rest is noise.
Get the Full Details
