4 If you ask to Python programmers what they like the most in Python, they will
5 often say it is its high readability. Indeed, a high level of readability of
6 the code 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 On the opposite, when a veteran Python developper (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 explicitely 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 expressivity,
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 explicitely 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 whitout 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 explicitely: ``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 beforhand, and it opens the possibility to pass
138 any sequence, inculding 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 serie 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 argmuents and which are optional keyword arguments, and to
153 decide wheter 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 instanciated, 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 Idiomatic Python code is often referred to as being *Pythonic*.
221 If you know the length of a list or tuple, you can assign names to its
222 elements with unpacking:
224 .. code-block:: python
226 for index, item in enumerate(some_list):
227 # do something with index and item
229 You can use this to swap variables, as well:
231 .. code-block:: python
235 Create an ignored variable
236 ~~~~~~~~~~~~~~~~~~~~~~~~~~
238 If you need to assign something (for instance, in :ref:`unpacking-ref`) but
239 will not need that variable, use ``_``:
241 .. code-block:: python
243 filename = 'foobar.txt'
244 basename, _, ext = filename.rpartition()
248 "``_``" is commonly used as an alias for the :func:`~gettext.gettext`
249 function. If your application uses (or may someday use) :mod:`gettext`,
250 you may want to avoid using ``_`` for ignored variables, as you may
251 accidentally shadow :func:`~gettext.gettext`.
253 Create a length-N list of the same thing
254 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
256 Use the Python list ``*`` operator:
258 .. code-block:: python
260 four_nones = [None] * 4
262 Create a length-N list of lists
263 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
265 Because lists are mutable, the ``*`` operator (as above) will create a list
266 of N references to the `same` list, which is not likely what you want.
267 Instead, use a list comprehension:
269 .. code-block:: python
271 four_lists = [[] for _ in xrange(4)]
274 A common idiom for creating strings is to use `join <http://docs.python.org/library/string.html#string.join>`_ on an empty string.::
276 letters = ['s', 'p', 'a', 'm']
277 word = ''.join(letters)
279 This will set the value of the variable *word* to 'spam'. This idiom can be applied to lists and tuples.
281 Sometimes we need to search through a collection of things. Let's look at two options: lists and dictionaries.
283 Take the following code for example::
285 d = {'s': [], 'p': [], 'a': [], 'm': []}
286 l = ['s', 'p', 'a', 'm']
294 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.
295 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.
296 For more information see this `StackOverflow <http://stackoverflow.com/questions/513882/python-list-vs-dict-for-look-up-table>`_ page.
301 Also known as PEP 20, the guiding principles for Python's design.
306 The Zen of Python, by Tim Peters
308 Beautiful is better than ugly.
309 Explicit is better than implicit.
310 Simple is better than complex.
311 Complex is better than complicated.
312 Flat is better than nested.
313 Sparse is better than dense.
315 Special cases aren't special enough to break the rules.
316 Although practicality beats purity.
317 Errors should never pass silently.
318 Unless explicitly silenced.
319 In the face of ambiguity, refuse the temptation to guess.
320 There should be one-- and preferably only one --obvious way to do it.
321 Although that way may not be obvious at first unless you're Dutch.
322 Now is better than never.
323 Although never is often better than *right* now.
324 If the implementation is hard to explain, it's a bad idea.
325 If the implementation is easy to explain, it may be a good idea.
326 Namespaces are one honking great idea -- let's do more of those!
328 For some examples of good Python style, see `this Stack Overflow question
329 <http://stackoverflow.com/questions/228181/the-zen-of-python>`_ or `these
330 slides from a Python user group
331 <http://artifex.org/~hblanks/talks/2011/pep20_by_example.pdf>`_.
336 PEP 8 is the de-facto code style guide for Python.
338 `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_
340 Conforming your Python code to PEP 8 is generally a good idea and helps make
341 code more consistent when working on projects with other developers. There
342 exists a command-line program, `pep8 <https://github.com/jcrocholl/pep8>`_,
343 that can check your code for conformance. Install it by running the following
344 command in your Terminal:
351 Then run it on a file or series of files to get a report of any violations.
356 optparse.py:69:11: E401 multiple imports on one line
357 optparse.py:77:1: E302 expected 2 blank lines, found 1
358 optparse.py:88:5: E301 expected 1 blank line, found 0
359 optparse.py:222:34: W602 deprecated form of raising exception
360 optparse.py:347:31: E211 whitespace before '('
361 optparse.py:357:17: E201 whitespace after '{'
362 optparse.py:472:29: E221 multiple spaces before operator
363 optparse.py:544:21: W601 .has_key() is deprecated, use 'in'
368 Here are some conventions you should follow to make your code easier to read.
370 Check if variable equals a constant
371 -----------------------------------
373 You don't need to explicitly compare a value to True, or None, or 0 - you can
374 just add it to the if statement. See `Truth Value Testing
375 <http://docs.python.org/library/stdtypes.html#truth-value-testing>`_ for a
376 list of what is considered false.
380 .. code-block:: python
386 print 'attr is None!'
390 .. code-block:: python
392 # Just check the value
394 print 'attr is truthy!'
396 # or check for the opposite
398 print 'attr is falsey!'
400 # or, since None is considered false, explicity check for it
402 print 'attr is None!'
404 Access a Dictionary Element
405 ---------------------------
407 Don't use the ``has_key`` function. Instead use ``x in d`` syntax, or pass
408 a default argument to ``get``.
412 .. code-block:: python
414 d = {'hello': 'world'}
415 if d.has_key('hello'):
416 print d['hello'] # prints 'world'
418 print 'default_value'
422 .. code-block:: python
424 d = {'hello': 'world'}
426 print d.get('hello', 'default_value') # prints 'world'
427 print d.get('thingy', 'default_value') # prints 'default_value'
433 Short Ways to Manipulate Lists
434 ------------------------------
437 <http://docs.python.org/tutorial/datastructures.html#list-comprehensions>`_
438 provide a powerful, concise way to work with lists. Also, the `map
439 <http://docs.python.org/library/functions.html#map>`_ and `filter
440 <http://docs.python.org/library/functions.html#filter>`_ functions can perform
441 operations on lists using a different concise syntax.
445 .. code-block:: python
447 # Filter elements greater than 4
456 .. code-block:: python
458 b = [i for i in a if i > 4]
459 b = filter(lambda x: x > 4, a)
463 .. code-block:: python
465 # Add three to all list members.
474 .. code-block:: python
477 a = [i + 3 for i in a]
479 a = map(lambda i: i + 3, a)
481 Use `enumerate <http://docs.python.org/library/functions.html#enumerate>`_ to
482 keep a count of your place in the list.
484 .. code-block:: python
486 for i, item in enumerate(a):
487 print i + ", " + item
493 The ``enumerate`` function has better readability than handling a counter
495 it is better optimized for iterators.
500 Use the ``with open`` syntax to read from files. This will automatically close
505 .. code-block:: python
514 .. code-block:: python
516 with open('file.txt') as f:
520 The ``with`` statement is better because it will ensure you always close the
521 file, even if an exception is raised.
523 Returning Multiple Values from a Function
524 -----------------------------------------
526 Python supports returning multiple values from a function as a comma-separated
527 list, so you don't have to create an object or dictionary and pack multiple
528 values in before you return
532 .. code-block:: python
535 return {'square': a ** 2, 'cube': a ** 3}
543 .. code-block:: python
546 return a ** 2, a ** 3
548 square, cube = math_func(3)
553 When a logical line of code is longer than the accepted limit, you need to
554 split it over multiple physical lines. Python interpreter will join consecutive
555 lines if the last character of the line is a backslash. This is helpful
556 sometime but is preferably avoided, because of its fragility: a white space
557 added to the end of the line, after the backslash, will break the code and may
558 have unexpected results.
560 A prefered solution is to use parenthesis around your elements. Left with an
561 unclosed parenthesis on an end-of-line the Python interpreter will join the
562 next line until the parenthesis is closed. The same behavior holds for curly
567 .. code-block:: python
569 my_very_big_string = """For a long time I used to go to bed early. Sometimes, \
570 when I had put out my candle, my eyes would close so quickly that I had not even \
571 time to say “I’m going to sleep.”"""
573 from some.deep.module.inside.a.module import a_nice_function, another_nice_function, \
574 yet_another_nice_functio
578 .. code-block:: python
580 my_very_big_string = ("For a long time I used to go to bed early. Sometimes, "
581 "when I had put out my candle, my eyes would close so quickly that I had not even "
582 "time to say “I’m going to sleep.”")
584 from some.deep.module.inside.a.module import (a_nice_function, another_nice_function,
585 yet_another_nice_functio)
587 However, more often than not having to split long logical line is a sign that
588 you are trying to do too many things at the same time, which may hinder