Python style conventions are described in PEPs.

Learning Python Style

If you're anything like me, you probably can't just read PEP 8 & 257, and start writing perfect Python style.

I've had a lot of success learning (and applying) the document in steps. Start with your line width, spacings. Then work on imports, white space, ... Continue learning and applying the style in steps.

It is probably unrealistic to believe that you can get the whole thing at once.


I wish there were good examples of well-styled Python code! (Most Python modules do not follow Python style guidelines!)

I intend to write some examples here, and comment on the features of the formatting. Hopefully, people who understand the format better will correct the examples.

-- LionKimbro 2005-02-19 08:10:35

Example Module

This is my understanding of how a Python module by PEP-8 might look:

   1 """Short description of module.
   3 Blah blah blah. This is the long description of the module. More brief
   4 explanations.
   6 ClassNameA --  short description
   7 function_a --  short description
   8 function_b --  short description
   9 """
  11 import sys  # standard library imports
  12 import os
  14 import optparse  # related major package imports
  16 import eggs  # application specific imports
  17 import spam
  20 class ClassNameA:
  22     """What it is.
  24     Notes on what it is and how it does it.
  26     Lots to say, lots to say.  I'm unclear on whether we need two spaces
  27     between sentences or not.  72 characters wide.  Blah blah blah.
  29     Document methods in here, with a short explanation.
  31     eat_eggs --  does X
  32     eat_spam --  does Y
  33     """
  35     def __init__(self, green_eggs, green_spam):
  36         """Init ClassNameA with some eggs and spam."""
  37         foo()
  38         bar()
  39         baz()
  41     def eat_eggs(self):
  42         """One line documentation is like this."""
  43         foo()
  44         bar()
  46     def eat_spam(self):
  47         """Short explanation.
  49         Multi-line spam has a one line description at top, seperated by
  50         a space, and then more multi-line spam afterwards.  Note that
  51         the final triple-quote appears beneath.
  52         """
  53         baz()
  55     def _internal_use(self):
  56         # Eat eggs and spam.
  57         #
  58         # Docstrings are not necessary for non-public methods, but you
  59         # should have a comment that describes what the method does.
  60         # This comment should appear after the "def" line.
  62         self.eat_eggs()
  63         self.eat_spam()
  66 def function_a(eggs, ham):
  67     """A function_a is a foobar.
  69     Again, multi-line rules apply in here as well, the same way.  Note
  70     that we have two spaces between module-level class and function
  71     definitions.  That's PEP-8 at work.
  72     """
  73     foo()
  74     bar()
  75     baz()
  78 def function_b(eggs, ham):
  79     """A function_b is a foobar.
  81     Another one.  Still two spaces separating functions and classes.
  82     """
  83     foo()
  84     bar()
  85     baz()

This may be incorrect; please correct it if you know better.

In particular, I'm not sure if there are zero, one, or two spaces between the module docstring, and the import lines.

-- LionKimbro 2005-02-21 04:44:51

I know these PEPs make no mention of DocTest code in docstrings. However, some of them might be nice in this example.

(-- JimD)

Wow, I didn't even know about DocTest.

That's really interesting.

Do you know of good example uses of doctest that I can look at?

This is the first I heard about it, even though I can see that it's been there for a while.

-- LionKimbro 2005-02-22 08:57:33


PythonStyle (last edited 2016-07-07 00:41:00 by bignose)

Unable to edit the page? See the FrontPage for instructions.