4 If you ask Python programmers what they like most in Python, they will
5 often say its high readability. Indeed, a high level of readability
6 is at the heart of the design of the Python language, following the
7 recognised fact that code is read much more often than it is written.
9 One reason for Python code to be easily read and understood is its relatively
10 complete set of Code Style guidelines and "Pythonic" idioms.
12 Moreover, when a veteran Python developer (a Pythonistas) point to some
13 parts of a code and say it is not "Pythonic", it usually means that these lines
14 of code do not follow the common guidelines and fail to express the intent in
15 what is considered the best (hear: most readable) way.
17 On some border cases, no best way has been agreed upon on how to express
18 an intent in Python code, but these cases are rare.
26 While any kind of black magic is possible with Python, the
27 most explicit and straightforward manner is preferred.
31 .. code-block:: python
33 def make_complex(\*args):
35 return dict(\**locals())
39 .. code-block:: python
41 def make_complex(x, y):
42 return {'x': x, 'y': y}
44 In the good code above, x and y are explicitly received from
45 the caller, and an explicit dictionary is returned. The developer
46 using this function knows exactly what to do by reading the
47 first and last lines, which is not the case with the bad example.
49 One statement per line
50 ~~~~~~~~~~~~~~~~~~~~~~
52 While some compound statements such as list comprehensions are
53 allowed and appreciated for their brevity and their expressiveness,
54 it is bad practice to have two disjoint statements on the same line.
58 .. code-block:: python
60 print 'one'; print 'two'
62 if x == 1: print 'one'
64 if <complex comparison> and <other complex comparison>:
69 .. code-block:: python
77 cond1 = <complex comparison>
78 cond2 = <other complex comparison>
85 Arguments can be passed to functions in four different ways.
87 **Positional arguments** are mandatory and have no default values. They are the
88 simplest form of arguments and they can be used for the few function arguments
89 that are fully part of the functions meaning and their order is natural. For
90 instance, in ``send(message, recipient)`` or ``point(x, y)`` the user of the
91 function has no difficulty to remember that those two function require two
92 arguments, and in which order.
94 In those two cases, it is possible to use argument names when calling the functions
95 and, doing so, it is possible to switch the order of arguments, calling for instance
96 ``send(recipient='World', message='Hello')`` and ``point(y=2, x=1)`` but this
97 reduce readability and is unnecessarily verbose, compared to the more straightforward
98 calls to ``send('Hello', 'World')`` and ``point(1, 2)``.
100 **Keyword arguments** are not mandatory and have default values. They are often
101 used for optional parameters sent to the function. When a function has more than
102 two or three positional parameters, its signature will be more difficult to remember
103 and using keyword argument with default values is helpful. For instance, a more
104 complete ``send`` function could be defined as ``send(message, to, cc=None, bcc=None)``.
105 Here ``cc`` and ``bcc`` are optional, and evaluate to ``None`` when the are not
106 passed another value.
108 Calling a function with keyword arguments can be done in multiple ways in Python,
109 for example it is possible to follow the order of arguments in the definition without
110 explicitly naming the arguments, like in ``send('Hello', 'World', 'Cthulhu`, 'God')``,
111 sending a blank carbon copy to God. It would also be possible to name arguments in
112 another order, like in ``send('Hello again', 'World', bcc='God', cc='Cthulhu')``.
113 Those two possibilities are better avoided without any strong reason to not
114 follow the syntax that is the closest to the function definition: ``send('Hello',
115 'World', cc='Cthulhu', bcc='God')``.
117 As a side note, following YAGNI_ principle, it is often harder to remove an
118 optional argument (and its logic inside the function) that was added "just in
119 case" and is seemingly never used, than to add a new optional argument and its
122 The **arbitrary argument list** is the third way to pass arguments to a
123 function. If the function intention is better expressed by a signature with an
124 extensible number of positional arguments, it can be defined with the ``*args``
125 constructs. In the function body, ``args`` will be a tuple of all the
126 remaining positional arguments. For example, ``send(message, *args)`` can be
127 called with each recipient as an argument: ``send('Hello', 'God', 'Mom',
128 'Cthulhu')``, and in the function body ``args`` will be equal to ``('God',
131 However, this construct has some drawback and should be used with caution. If a
132 function receives a list of arguments of the same nature, it is often more
133 clear to define it as a function of one argument, that argument being a list or
134 any sequence. Here, if ``send`` has multiple recipients, it is better to define
135 it explicitly: ``send(message, recipients)`` and call it with ``send('Hello',
136 ['God', 'Mom', 'Cthulhu'])``. This way, the user of the function can manipulate
137 the recipient list as a list beforehand, and it opens the possibility to pass
138 any sequence, including iterators, that cannot be unpacked as other sequences.
140 The **arbitrary keyword argument dictionary** is the last way to pass arguments
141 to functions. If the function requires an undetermined series of named
142 arguments, it is possible to used the ``**kwargs`` construct. In the function
143 body, ``kwargs`` will be a dictionary of all the passed named arguments that
144 have not been caught be other keyword argument in the function signature.
146 The same caution as in the case of *arbitrary argument list* is necessary, for
147 similar reasons: these powerful techniques are to be used when there is a
148 proven necessity to use them, and they should not be used if the simpler and
149 clearer construct is sufficient to express the function's intention.
151 It is up to the programmer writing the function to determine which arguments
152 are positional arguments and which are optional keyword arguments, and to
153 decide whether to use the advanced techniques of arbitrary argument passing. If
154 the advices above are followed wisely, it is possible and enjoyable to write
155 Python functions that are:
157 * easy to read (the name and arguments need no explanations)
159 * easy to change (adding a new keyword argument do not break other parts of the
162 Avoid the magical wand
163 ~~~~~~~~~~~~~~~~~~~~~~
165 A powerful tool for hackers, Python comes with a very rich set of hooks and
166 tools allowing to do almost any kind of tricky tricks. For instance, it is
167 possible to change how objects are created and instantiated, it is possible to
168 change how the Python interpreter imports modules, it is even possible (and
169 recommended if needed) to embed C routines in Python.
171 However, all these options have many drawbacks and it is always better to use
172 the most straightforward way to achieve your goal. The main drawback is that
173 readability suffers deeply from them. Many code analysis tools, such as pylint
174 or pyflakes, will be unable to parse this "magic" code.
176 We consider that a Python developer should know about these nearly infinite
177 possibilities, because it grows the confidence that no hard-wall will be on the
178 way. However, knowing how to use them and particularly when **not** to use
179 them is the most important.
181 Like a Kungfu master, a pythonistas knows how to kill with a single finger, and
184 We are all consenting adults
185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187 As seen above, Python allows many tricks, and some of them are potentially
188 dangerous. A good example is that any client code can override an object's
189 properties and methods: there is no "private" keyword in Python. This
190 philosophy, very different from highly defensive languages like Java, which
191 give a lot of mechanism to prevent any misuse, is expressed by the saying: "We
192 are consenting adults".
194 This doesn't mean that, for example, no properties are considered private, and
195 that no proper encapsulation is possible in Python. But, instead of relying on
196 concrete walls erected by the developers between their code and other's, the
197 Python community prefers to rely on a set of convention indicating that these
198 elements should not be accessed directly.
200 The main convention for private properties and implementation details is to
201 prefix all "internals" with an underscore. If the client code breaks this rule
202 and access to these marked elements, any misbehavior or problems encountered if
203 the code is modified is the responsibility of the client code.
205 Using this convention generously is encouraged: any method or property that is
206 not intended to be used by client code should be prefixed with an underscore.
207 This will guarantee a better separation of duties and easier modifications of
208 existing code, and it will always be possible to publicize a private property,
209 while privatising a public property might be a much harder operation.
214 Python functions return a value, and you can control this return value with the
215 return statement for all of them but the object constructor `__init__()` and the
216 special case of generators.
218 When a function grows in complexity is not uncommon to use multiple return statements
219 inside the function's body. However, in order to keep a clear intent and a sustainable
220 readability level, it is preferable to avoid returning meaningful values from many
221 output point in the body.
223 There are two main cases for returning values in a function: The result of the function
224 return when it has been processed normally, and the error cases that indicate a wrong
225 input parameter or any other reason for the function to not be able to complete its
228 If you do not wish to raise exceptions for the second case, then returning a value, such
229 as None or False, indicating that the function could not perform correctly might be needed. In this
230 case, it is better to return as early as the incorrect context has been detected. It will
231 help to flatten the structure of the function: all the code after the return-because-of-error
232 statement can assume the condition is met to further compute the function's main result.
233 Having multiple such return statement is often necessary.
235 However, when a function has multiple main exit points for its normal course, it becomes
236 difficult to debug the returned result, and it may be preferable to keep a single exit
237 point. This will also help factoring out some code paths, and the multiple exit point
238 is a probable indication that such a refactoring is needed.
240 .. code-block:: python
242 def complex_function(a, b, c):
244 return None # Raising an exception might be better
246 return None # Raising an exception might be better
247 # Some complex code trying to compute x from a, b and c
248 # Resist temptation to return x if succeeded
250 # Some Plan-B computation of x
251 return x # One single exit point for the returned value x will help
252 # when maintaining the code.
257 Idiomatic Python code is often referred to as being *Pythonic*.
264 If you know the length of a list or tuple, you can assign names to its
265 elements with unpacking:
267 .. code-block:: python
269 for index, item in enumerate(some_list):
270 # do something with index and item
272 You can use this to swap variables, as well:
274 .. code-block:: python
278 Nested unpacking works too:
280 .. code-block:: python
282 a, (b, c) = 1, (2, 3)
284 Create an ignored variable
285 ~~~~~~~~~~~~~~~~~~~~~~~~~~
287 If you need to assign something (for instance, in :ref:`unpacking-ref`) but
288 will not need that variable, use ``__``:
290 .. code-block:: python
292 filename = 'foobar.txt'
293 basename, __, ext = filename.rpartition()
297 Many Python style guides recommend the use of a single underscore "``_``"
298 for throwaway variables rather than the double underscore "``__``"
299 recommended here. The issue is that "``_``" is commonly used as an alias
300 for the :func:`~gettext.gettext` function, and is also used at the
301 interactive prompt to hold the value of the last operation. Using a
302 double underscore instead is just as clear and almost as convenient,
303 and eliminates the risk of accidentally interfering with either of
304 these other use cases.
306 Create a length-N list of the same thing
307 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
309 Use the Python list ``*`` operator:
311 .. code-block:: python
313 four_nones = [None] * 4
315 Create a length-N list of lists
316 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
318 Because lists are mutable, the ``*`` operator (as above) will create a list
319 of N references to the `same` list, which is not likely what you want.
320 Instead, use a list comprehension:
322 .. code-block:: python
324 four_lists = [[] for _ in xrange(4)]
327 A common idiom for creating strings is to use `join <http://docs.python.org/library/string.html#string.join>`_ on an empty string.::
329 letters = ['s', 'p', 'a', 'm']
330 word = ''.join(letters)
332 This will set the value of the variable *word* to 'spam'. This idiom can be applied to lists and tuples.
334 Sometimes we need to search through a collection of things. Let's look at two options: lists and dictionaries.
336 Take the following code for example::
338 d = {'s': [], 'p': [], 'a': [], 'm': []}
339 l = ['s', 'p', 'a', 'm']
347 Even though both functions look identical, because *lookup_dict* is utilizing the fact that dictionaries in python are hashtables, the lookup performance between the two is very different.
348 Python will have to go through each item in the list to find a matching case, which is time consuming. By analysing the hash of the dictionary finding keys in the dict can be done very quickly.
349 For more information see this `StackOverflow <http://stackoverflow.com/questions/513882/python-list-vs-dict-for-look-up-table>`_ page.
354 Also known as PEP 20, the guiding principles for Python's design.
359 The Zen of Python, by Tim Peters
361 Beautiful is better than ugly.
362 Explicit is better than implicit.
363 Simple is better than complex.
364 Complex is better than complicated.
365 Flat is better than nested.
366 Sparse is better than dense.
368 Special cases aren't special enough to break the rules.
369 Although practicality beats purity.
370 Errors should never pass silently.
371 Unless explicitly silenced.
372 In the face of ambiguity, refuse the temptation to guess.
373 There should be one-- and preferably only one --obvious way to do it.
374 Although that way may not be obvious at first unless you're Dutch.
375 Now is better than never.
376 Although never is often better than *right* now.
377 If the implementation is hard to explain, it's a bad idea.
378 If the implementation is easy to explain, it may be a good idea.
379 Namespaces are one honking great idea -- let's do more of those!
381 For some examples of good Python style, see `this Stack Overflow question
382 <http://stackoverflow.com/questions/228181/the-zen-of-python>`_ or `these
383 slides from a Python user group
384 <http://artifex.org/~hblanks/talks/2011/pep20_by_example.pdf>`_.
389 PEP 8 is the de-facto code style guide for Python.
391 `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_
393 Conforming your Python code to PEP 8 is generally a good idea and helps make
394 code more consistent when working on projects with other developers. There
395 exists a command-line program, `pep8 <https://github.com/jcrocholl/pep8>`_,
396 that can check your code for conformance. Install it by running the following
397 command in your Terminal:
404 Then run it on a file or series of files to get a report of any violations.
409 optparse.py:69:11: E401 multiple imports on one line
410 optparse.py:77:1: E302 expected 2 blank lines, found 1
411 optparse.py:88:5: E301 expected 1 blank line, found 0
412 optparse.py:222:34: W602 deprecated form of raising exception
413 optparse.py:347:31: E211 whitespace before '('
414 optparse.py:357:17: E201 whitespace after '{'
415 optparse.py:472:29: E221 multiple spaces before operator
416 optparse.py:544:21: W601 .has_key() is deprecated, use 'in'
421 Here are some conventions you should follow to make your code easier to read.
423 Check if variable equals a constant
424 -----------------------------------
426 You don't need to explicitly compare a value to True, or None, or 0 - you can
427 just add it to the if statement. See `Truth Value Testing
428 <http://docs.python.org/library/stdtypes.html#truth-value-testing>`_ for a
429 list of what is considered false.
433 .. code-block:: python
439 print 'attr is None!'
443 .. code-block:: python
445 # Just check the value
447 print 'attr is truthy!'
449 # or check for the opposite
451 print 'attr is falsey!'
453 # or, since None is considered false, explicity check for it
455 print 'attr is None!'
457 Access a Dictionary Element
458 ---------------------------
460 Don't use the ``has_key`` function. Instead use ``x in d`` syntax, or pass
461 a default argument to ``get``.
465 .. code-block:: python
467 d = {'hello': 'world'}
468 if d.has_key('hello'):
469 print d['hello'] # prints 'world'
471 print 'default_value'
475 .. code-block:: python
477 d = {'hello': 'world'}
479 print d.get('hello', 'default_value') # prints 'world'
480 print d.get('thingy', 'default_value') # prints 'default_value'
486 Short Ways to Manipulate Lists
487 ------------------------------
490 <http://docs.python.org/tutorial/datastructures.html#list-comprehensions>`_
491 provide a powerful, concise way to work with lists. Also, the `map
492 <http://docs.python.org/library/functions.html#map>`_ and `filter
493 <http://docs.python.org/library/functions.html#filter>`_ functions can perform
494 operations on lists using a different concise syntax.
498 .. code-block:: python
500 # Filter elements greater than 4
509 .. code-block:: python
511 b = [i for i in a if i > 4]
512 b = filter(lambda x: x > 4, a)
516 .. code-block:: python
518 # Add three to all list members.
527 .. code-block:: python
530 a = [i + 3 for i in a]
532 a = map(lambda i: i + 3, a)
534 Use `enumerate <http://docs.python.org/library/functions.html#enumerate>`_ to
535 keep a count of your place in the list.
537 .. code-block:: python
539 for i, item in enumerate(a):
540 print i + ", " + item
546 The ``enumerate`` function has better readability than handling a counter
548 it is better optimized for iterators.
553 Use the ``with open`` syntax to read from files. This will automatically close
558 .. code-block:: python
567 .. code-block:: python
569 with open('file.txt') as f:
573 The ``with`` statement is better because it will ensure you always close the
574 file, even if an exception is raised.
576 Returning Multiple Values from a Function
577 -----------------------------------------
579 Python supports returning multiple values from a function as a comma-separated
580 list, so you don't have to create an object or dictionary and pack multiple
581 values in before you return
585 .. code-block:: python
588 return {'square': a ** 2, 'cube': a ** 3}
596 .. code-block:: python
599 return a ** 2, a ** 3
601 square, cube = math_func(3)
606 When a logical line of code is longer than the accepted limit, you need to
607 split it over multiple physical lines. Python interpreter will join consecutive
608 lines if the last character of the line is a backslash. This is helpful
609 sometime but is preferably avoided, because of its fragility: a white space
610 added to the end of the line, after the backslash, will break the code and may
611 have unexpected results.
613 A preferred solution is to use parenthesis around your elements. Left with an
614 unclosed parenthesis on an end-of-line the Python interpreter will join the
615 next line until the parenthesis is closed. The same behavior holds for curly
620 .. code-block:: python
622 my_very_big_string = """For a long time I used to go to bed early. Sometimes, \
623 when I had put out my candle, my eyes would close so quickly that I had not even \
624 time to say “I’m going to sleep.”"""
626 from some.deep.module.inside.a.module import a_nice_function, another_nice_function, \
627 yet_another_nice_function
631 .. code-block:: python
633 my_very_big_string = (
634 "For a long time I used to go to bed early. Sometimes, "
635 "when I had put out my candle, my eyes would close so quickly "
636 "that I had not even time to say “I’m going to sleep.”"
639 from some.deep.module.inside.a.module import (
640 a_nice_function, another_nice_function, yet_another_nice_function)
642 However, more often than not having to split long logical line is a sign that
643 you are trying to do too many things at the same time, which may hinder