Getting Along with Python

Apply community style conventions

Most of the Python community’s standards for code formatting and style are encapsulated in two documents, PEP 8 and PEP 257. If you are ever going to share code or work on projects in the Python community, please learn to format code according to PEP 8, and incorporate docstrings according to PEP 257. Think of it as good manners.

If you don’t fully understand this advice, arguments are provided in later sections of this document: Why use PEP 8? and Why use PEP 257? In the end, you can write your own code the way you want to. But there are advantages to the community style, particularly for collaboration.

Note

A few Python subcommunities (like Zope, Plone, Twisted and Google) decided long ago to stick to their own conventions rather than PEP 8. When working on projects aimed at those communities, don’t argue about PEP 8 but “Do as the Romans Do.” Otherwise, please stick to PEP 8 yourself.

A few key points

If you are writing (or want to write) much Python code, scan over PEP 8 and PEP 257 sometime. The following points exclude many useful details, but hopefully are good enough as a starting point:

  • Indent with 4 spaces, no hard tab characters.
  • Maximum 79 characters in each line of code.
  • class names look like ClassName. function names look like function_name. modules look like module_name. Package names shouldn’t have underscores.
  • Avoid putting multiple statements on the same line, like if True: stuff. Usually if there is a colon, just put the rest on the next line at the appropriate indent level. Don’t use semicolons.
  • Separate function and class definitions with two blank lines. Methods, one blank line.
  • Put imports at the top of the file, on separate lines for each one.
  • Never use from somewhere import *.
  • Put spaces around operators like +, like 2 + 3. Also put a space after a comma in a list. NOT: [2,4] but rather: [2, 4]
  • When passing keyword arguments, omit spaces around the =, as in f(foo=2, bar=4).
  • Don’t put spaces inside parentheses, brackets, etc. NOT: [ 2, 4 ], but rather [2, 4].
  • Avoid except: (without any exception classes).

Tools like flake8 exist to help you find many problems like these automatically (see also Run syntax and style checkers).

Why use PEP 8?

How many spaces to use obviously isn’t vital to how the code runs. So why is this important?

  1. Insofar as questions like the number of spaces are not important, there is no reason not to follow the convention.
  2. Code isn’t just for machines to run, it’s for other people to read. PEP8 contains some valuable insights about how to make your code readable, and often the alternative suggestions have been less wise. In any case, simply applying one consistent style also makes your code more readable.
  3. Using a standard convention reduces the time wasted on a bunch of silly arguments about things like tabs, for every single new job or project.
  4. It helps you get along with most of the Python community. If you ever collaborate with others on a project, or ask for a review or help with your code, not using something close to PEP 8 is likely to annoy others. Similarly, there are tons of projects out there using something close to PEP 8, so learning to live with this style will make your life more pleasant as well.
  5. Because PEP 8 is the Python community’s default style, you can get more help from Python tools which help enforce a style (or assume a certain style in order to work optimally).

Most of the individual details, like tabs vs. spaces, are arguable issues discussed in PEP 8 itself. Of course, everyone has the right to form his or her own opinions; but even if you disagree with these and do not wish to apply PEP 8 yourself, please learn not to argue against PEP 8 in the context of Python projects (like in meetings or issue trackers). It’s a waste of attention and it’s rude. If you have a strongly felt opinion about tab characters, publish it on your personal blog.

Why use PEP 257?

PEP 257 gives some basic guidelines on how to write docstrings in your code.

The basic reason to use docstrings is so that people (including yourself in six months) can understand what your functions and classes are supposed to be doing and how to use them. The basic reason to use PEP 257 docstrings is, basically, that it’s the standard and everyone knows how to read it.

Besides that, following PEP 257 makes it pleasant to generate documentation for your project using Sphinx, so you can publish generated docs that easily stay in sync with the documentation you provide inline in your code. Sphinx is a really good tool. Using Sphinx, you also have the option to host your project documentation free on Read the Docs, which also automates doc deploys for you.

Idiomatic Python

How you write your code is outside of the scope of “Hello Python,” but it’s obviously a big part of the craft, and there’s a lot of good guidance to draw from. Developing better style is a lifelong project, but following these guides can give a Python beginner a good head start.

Although Google has published a few attractive documents about Python, I don’t advise starting with them unless you are working there, because I have found that these materials contain additional opinions and subtle variations. For example, Google’s docs sometimes recommend 2-space indents, dwell on comparisons to Java, etc.