controlflow.rst 23.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
.. _tut-morecontrol:

***********************
More Control Flow Tools
***********************

Besides the :keyword:`while` statement just introduced, Python knows the usual
control flow statements known from other languages, with some twists.


.. _tut-if:

:keyword:`if` Statements
========================

Perhaps the most well-known statement type is the :keyword:`if` statement.  For
example::

19
   >>> x = int(input("Please enter an integer: "))
Georg Brandl's avatar
Georg Brandl committed
20
   Please enter an integer: 42
21 22
   >>> if x < 0:
   ...      x = 0
23
   ...      print('Negative changed to zero')
24
   ... elif x == 0:
25
   ...      print('Zero')
26
   ... elif x == 1:
27
   ...      print('Single')
28
   ... else:
29
   ...      print('More')
Georg Brandl's avatar
Georg Brandl committed
30 31
   ...
   More
32 33 34 35

There can be zero or more :keyword:`elif` parts, and the :keyword:`else` part is
optional.  The keyword ':keyword:`elif`' is short for 'else if', and is useful
to avoid excessive indentation.  An  :keyword:`if` ... :keyword:`elif` ...
36 37
:keyword:`elif` ... sequence is a substitute for the ``switch`` or
``case`` statements found in other languages.
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54


.. _tut-for:

:keyword:`for` Statements
=========================

.. index::
   statement: for

The :keyword:`for` statement in Python differs a bit from what you may be used
to in C or Pascal.  Rather than always iterating over an arithmetic progression
of numbers (like in Pascal), or giving the user the ability to define both the
iteration step and halting condition (as C), Python's :keyword:`for` statement
iterates over the items of any sequence (a list or a string), in the order that
they appear in the sequence.  For example (no pun intended):

55 56
.. One suggestion was to give a real C example here, but that may only serve to
   confuse non-C programmers.
57 58 59 60 61 62

::

   >>> # Measure some strings:
   ... a = ['cat', 'window', 'defenestrate']
   >>> for x in a:
63
   ...     print(x, len(x))
64
   ...
65 66 67 68 69 70 71 72 73 74 75 76
   cat 3
   window 6
   defenestrate 12

It is not safe to modify the sequence being iterated over in the loop (this can
only happen for mutable sequence types, such as lists).  If you need to modify
the list you are iterating over (for example, to duplicate selected items) you
must iterate over a copy.  The slice notation makes this particularly
convenient::

   >>> for x in a[:]: # make a slice copy of the entire list
   ...    if len(x) > 6: a.insert(0, x)
77
   ...
78 79 80 81 82 83 84 85 86 87
   >>> a
   ['defenestrate', 'cat', 'window', 'defenestrate']


.. _tut-range:

The :func:`range` Function
==========================

If you do need to iterate over a sequence of numbers, the built-in function
88 89 90 91 92 93 94 95 96 97
:func:`range` comes in handy.  It generates arithmetic progressions::

    >>> for i in range(5):
    ...     print(i)
    ...
    0
    1
    2
    3
    4
98

Georg Brandl's avatar
Georg Brandl committed
99
The given end point is never part of the generated sequence; ``range(10)`` generates
100
10 values, the legal indices for items of a sequence of length 10.  It
101 102 103
is possible to let the range start at another number, or to specify a different
increment (even negative; sometimes this is called the 'step')::

104
    range(5, 10)
105 106
       5 through 9

107
    range(0, 10, 3)
108 109
       0, 3, 6, 9

110
    range(-10, -100, -30)
111
      -10, -40, -70
112

Georg Brandl's avatar
Georg Brandl committed
113 114
To iterate over the indices of a sequence, you can combine :func:`range` and
:func:`len` as follows::
115 116 117

   >>> a = ['Mary', 'had', 'a', 'little', 'lamb']
   >>> for i in range(len(a)):
118
   ...     print(i, a[i])
119
   ...
120 121 122 123 124 125
   0 Mary
   1 had
   2 a
   3 little
   4 lamb

Georg Brandl's avatar
Georg Brandl committed
126 127 128
In most such cases, however, it is convenient to use the :func:`enumerate`
function, see :ref:`tut-loopidioms`.

129 130 131 132 133 134
A strange thing happens if you just print a range::

   >>> print(range(10))
   range(0, 10)

In many ways the object returned by :func:`range` behaves as if it is a list,
135 136 137
but in fact it isn't. It is an object which returns the successive items of
the desired sequence when you iterate over it, but it doesn't really make
the list, thus saving space.
138

139 140
We say such an object is *iterable*, that is, suitable as a target for
functions and constructs that expect something from which they can
141 142 143 144 145 146 147 148 149
obtain successive items until the supply is exhausted. We have seen that
the :keyword:`for` statement is such an *iterator*. The function :func:`list`
is another; it creates lists from iterables::


   >>> list(range(5))
   [0, 1, 2, 3, 4]

Later we will see more functions that return iterables and take iterables as argument.
150

Georg Brandl's avatar
Georg Brandl committed
151

152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
.. _tut-break:

:keyword:`break` and :keyword:`continue` Statements, and :keyword:`else` Clauses on Loops
=========================================================================================

The :keyword:`break` statement, like in C, breaks out of the smallest enclosing
:keyword:`for` or :keyword:`while` loop.

The :keyword:`continue` statement, also borrowed from C, continues with the next
iteration of the loop.

Loop statements may have an ``else`` clause; it is executed when the loop
terminates through exhaustion of the list (with :keyword:`for`) or when the
condition becomes false (with :keyword:`while`), but not when the loop is
terminated by a :keyword:`break` statement.  This is exemplified by the
following loop, which searches for prime numbers::

   >>> for n in range(2, 10):
   ...     for x in range(2, n):
   ...         if n % x == 0:
172
   ...             print(n, 'equals', x, '*', n//x)
173 174 175
   ...             break
   ...     else:
   ...         # loop fell through without finding a factor
176
   ...         print(n, 'is a prime number')
177
   ...
178 179 180 181 182 183 184 185 186
   2 is a prime number
   3 is a prime number
   4 equals 2 * 2
   5 is a prime number
   6 equals 2 * 3
   7 is a prime number
   8 equals 2 * 4
   9 equals 3 * 3

187 188 189
(Yes, this is the correct code.  Look closely: the ``else`` clause belongs to
the :keyword:`for` loop, **not** the :keyword:`if` statement.)

190 191 192 193 194 195 196 197 198 199

.. _tut-pass:

:keyword:`pass` Statements
==========================

The :keyword:`pass` statement does nothing. It can be used when a statement is
required syntactically but the program requires no action. For example::

   >>> while True:
Georg Brandl's avatar
Georg Brandl committed
200
   ...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
201
   ...
202

Benjamin Peterson's avatar
Benjamin Peterson committed
203
This is commonly used for creating minimal classes::
204

Benjamin Peterson's avatar
Benjamin Peterson committed
205
   >>> class MyEmptyClass:
206
   ...     pass
Benjamin Peterson's avatar
Benjamin Peterson committed
207
   ...
208 209

Another place :keyword:`pass` can be used is as a place-holder for a function or
Benjamin Peterson's avatar
Benjamin Peterson committed
210 211
conditional body when you are working on new code, allowing you to keep thinking
at a more abstract level.  The :keyword:`pass` is silently ignored::
212 213

   >>> def initlog(*args):
Benjamin Peterson's avatar
Benjamin Peterson committed
214
   ...     pass   # Remember to implement this!
215
   ...
216

217 218 219 220 221 222 223 224 225 226 227
.. _tut-functions:

Defining Functions
==================

We can create a function that writes the Fibonacci series to an arbitrary
boundary::

   >>> def fib(n):    # write Fibonacci series up to n
   ...     """Print a Fibonacci series up to n."""
   ...     a, b = 0, 1
228 229
   ...     while a < n:
   ...         print(a, end=' ')
230
   ...         a, b = b, a+b
231
   ...     print()
232
   ...
233 234
   >>> # Now call the function we just defined:
   ... fib(2000)
235
   0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
236 237 238 239 240 241 242 243 244

.. index::
   single: documentation strings
   single: docstrings
   single: strings, documentation

The keyword :keyword:`def` introduces a function *definition*.  It must be
followed by the function name and the parenthesized list of formal parameters.
The statements that form the body of the function start at the next line, and
Georg Brandl's avatar
Georg Brandl committed
245
must be indented.
246

Georg Brandl's avatar
Georg Brandl committed
247 248 249
The first statement of the function body can optionally be a string literal;
this string literal is the function's documentation string, or :dfn:`docstring`.
(More about docstrings can be found in the section :ref:`tut-docstrings`.)
250 251
There are tools which use docstrings to automatically produce online or printed
documentation, or to let the user interactively browse through code; it's good
Georg Brandl's avatar
Georg Brandl committed
252
practice to include docstrings in code that you write, so make a habit of it.
253 254 255 256

The *execution* of a function introduces a new symbol table used for the local
variables of the function.  More precisely, all variable assignments in a
function store the value in the local symbol table; whereas variable references
257 258 259 260 261
first look in the local symbol table, then in the local symbol tables of
enclosing functions, then in the global symbol table, and finally in the table
of built-in names. Thus, global variables cannot be directly assigned a value
within a function (unless named in a :keyword:`global` statement), although they
may be referenced.
262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278

The actual parameters (arguments) to a function call are introduced in the local
symbol table of the called function when it is called; thus, arguments are
passed using *call by value* (where the *value* is always an object *reference*,
not the value of the object). [#]_ When a function calls another function, a new
local symbol table is created for that call.

A function definition introduces the function name in the current symbol table.
The value of the function name has a type that is recognized by the interpreter
as a user-defined function.  This value can be assigned to another name which
can then also be used as a function.  This serves as a general renaming
mechanism::

   >>> fib
   <function fib at 10042ed0>
   >>> f = fib
   >>> f(100)
279
   0 1 1 2 3 5 8 13 21 34 55 89
280

Georg Brandl's avatar
Georg Brandl committed
281 282 283 284 285 286
Coming from other languages, you might object that ``fib`` is not a function but
a procedure since it doesn't return a value.  In fact, even functions without a
:keyword:`return` statement do return a value, albeit a rather boring one.  This
value is called ``None`` (it's a built-in name).  Writing the value ``None`` is
normally suppressed by the interpreter if it would be the only value written.
You can see it if you really want to using :func:`print`::
287

288
   >>> fib(0)
289
   >>> print(fib(0))
290 291 292 293 294 295 296 297 298
   None

It is simple to write a function that returns a list of the numbers of the
Fibonacci series, instead of printing it::

   >>> def fib2(n): # return Fibonacci series up to n
   ...     """Return a list containing the Fibonacci series up to n."""
   ...     result = []
   ...     a, b = 0, 1
299 300
   ...     while a < n:
   ...         result.append(a)    # see below
301 302
   ...         a, b = b, a+b
   ...     return result
303
   ...
304 305
   >>> f100 = fib2(100)    # call it
   >>> f100                # write the result
306
   [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
307 308 309 310 311

This example, as usual, demonstrates some new Python features:

* The :keyword:`return` statement returns with a value from a function.
  :keyword:`return` without an expression argument returns ``None``. Falling off
Georg Brandl's avatar
Georg Brandl committed
312
  the end of a function also returns ``None``.
313

314
* The statement ``result.append(a)`` calls a *method* of the list object
315 316 317 318 319
  ``result``.  A method is a function that 'belongs' to an object and is named
  ``obj.methodname``, where ``obj`` is some object (this may be an expression),
  and ``methodname`` is the name of a method that is defined by the object's type.
  Different types define different methods.  Methods of different types may have
  the same name without causing ambiguity.  (It is possible to define your own
320
  object types and methods, using *classes*, see :ref:`tut-classes`)
321 322
  The method :meth:`append` shown in the example is defined for list objects; it
  adds a new element at the end of the list.  In this example it is equivalent to
323
  ``result = result + [a]``, but more efficient.
324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345


.. _tut-defining:

More on Defining Functions
==========================

It is also possible to define functions with a variable number of arguments.
There are three forms, which can be combined.


.. _tut-defaultargs:

Default Argument Values
-----------------------

The most useful form is to specify a default value for one or more arguments.
This creates a function that can be called with fewer arguments than it is
defined to allow.  For example::

   def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
       while True:
346
           ok = input(prompt)
347 348 349 350
           if ok in ('y', 'ye', 'yes'):
               return True
           if ok in ('n', 'no', 'nop', 'nope'):
               return False
351
           retries = retries - 1
352 353
           if retries < 0:
               raise IOError('refusenik user')
354
           print(complaint)
355

356 357 358 359 360 361 362 363
This function can be called in several ways:

* giving only the mandatory argument:
  ``ask_ok('Do you really want to quit?')``
* giving one of the optional arguments:
  ``ask_ok('OK to overwrite the file?', 2)``
* or even giving all arguments:
  ``ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')``
364 365 366 367 368 369 370 371 372 373

This example also introduces the :keyword:`in` keyword. This tests whether or
not a sequence contains a certain value.

The default values are evaluated at the point of function definition in the
*defining* scope, so that ::

   i = 5

   def f(arg=i):
374
       print(arg)
375 376 377 378 379 380 381 382 383 384 385 386 387 388 389

   i = 6
   f()

will print ``5``.

**Important warning:**  The default value is evaluated only once. This makes a
difference when the default is a mutable object such as a list, dictionary, or
instances of most classes.  For example, the following function accumulates the
arguments passed to it on subsequent calls::

   def f(a, L=[]):
       L.append(a)
       return L

390 391 392
   print(f(1))
   print(f(2))
   print(f(3))
393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414

This will print ::

   [1]
   [1, 2]
   [1, 2, 3]

If you don't want the default to be shared between subsequent calls, you can
write the function like this instead::

   def f(a, L=None):
       if L is None:
           L = []
       L.append(a)
       return L


.. _tut-keywordargs:

Keyword Arguments
-----------------

415 416
Functions can also be called using :term:`keyword arguments <keyword argument>`
of the form ``kwarg=value``.  For instance, the following function::
417 418

   def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
419
       print("-- This parrot wouldn't", action, end=' ')
420 421 422
       print("if you put", voltage, "volts through it.")
       print("-- Lovely plumage, the", type)
       print("-- It's", state, "!")
423

424 425 426
accepts one required argument (``voltage``) and three optional arguments
(``state``, ``action``, and ``type``).  This function can be called in any
of the following ways::
427

428 429 430 431 432 433
   parrot(1000)                                          # 1 positional argument
   parrot(voltage=1000)                                  # 1 keyword argument
   parrot(voltage=1000000, action='VOOOOOM')             # 2 keyword arguments
   parrot(action='VOOOOOM', voltage=1000000)             # 2 keyword arguments
   parrot('a million', 'bereft of life', 'jump')         # 3 positional arguments
   parrot('a thousand', state='pushing up the daisies')  # 1 positional, 1 keyword
434

435
but all the following calls would be invalid::
436 437

   parrot()                     # required argument missing
438 439 440 441 442 443 444 445 446 447 448
   parrot(voltage=5.0, 'dead')  # non-keyword argument after a keyword argument
   parrot(110, voltage=220)     # duplicate value for the same argument
   parrot(actor='John Cleese')  # unknown keyword argument

In a function call, keyword arguments must follow positional arguments.
All the keyword arguments passed must match one of the arguments
accepted by the function (e.g. ``actor`` is not a valid argument for the
``parrot`` function), and their order is not important.  This also includes
non-optional arguments (e.g. ``parrot(voltage=1000)`` is valid too).
No argument may receive a value more than once.
Here's an example that fails due to this restriction::
449 450 451

   >>> def function(a):
   ...     pass
452
   ...
453 454 455 456 457 458 459 460 461 462 463 464 465 466
   >>> function(0, a=0)
   Traceback (most recent call last):
     File "<stdin>", line 1, in ?
   TypeError: function() got multiple values for keyword argument 'a'

When a final formal parameter of the form ``**name`` is present, it receives a
dictionary (see :ref:`typesmapping`) containing all keyword arguments except for
those corresponding to a formal parameter.  This may be combined with a formal
parameter of the form ``*name`` (described in the next subsection) which
receives a tuple containing the positional arguments beyond the formal parameter
list.  (``*name`` must occur before ``**name``.) For example, if we define a
function like this::

   def cheeseshop(kind, *arguments, **keywords):
Georg Brandl's avatar
Georg Brandl committed
467
       print("-- Do you have any", kind, "?")
468
       print("-- I'm sorry, we're all out of", kind)
469 470
       for arg in arguments:
           print(arg)
Georg Brandl's avatar
Georg Brandl committed
471
       print("-" * 40)
472
       keys = sorted(keywords.keys())
473 474
       for kw in keys:
           print(kw, ":", keywords[kw])
475 476 477

It could be called like this::

Georg Brandl's avatar
Georg Brandl committed
478
   cheeseshop("Limburger", "It's very runny, sir.",
479
              "It's really very, VERY runny, sir.",
Georg Brandl's avatar
Georg Brandl committed
480 481 482
              shopkeeper="Michael Palin",
              client="John Cleese",
              sketch="Cheese Shop Sketch")
483 484 485 486 487 488 489 490 491 492 493 494

and of course it would print::

   -- Do you have any Limburger ?
   -- I'm sorry, we're all out of Limburger
   It's very runny, sir.
   It's really very, VERY runny, sir.
   ----------------------------------------
   client : John Cleese
   shopkeeper : Michael Palin
   sketch : Cheese Shop Sketch

495 496 497
Note that the list of keyword argument names is created by sorting the result
of the keywords dictionary's ``keys()`` method before printing its contents;
if this is not done, the order in which the arguments are printed is undefined.
498 499 500 501 502 503

.. _tut-arbitraryargs:

Arbitrary Argument Lists
------------------------

Christian Heimes's avatar
Christian Heimes committed
504
.. index::
505
  statement: *
Christian Heimes's avatar
Christian Heimes committed
506

507 508
Finally, the least frequently used option is to specify that a function can be
called with an arbitrary number of arguments.  These arguments will be wrapped
Georg Brandl's avatar
Georg Brandl committed
509 510
up in a tuple (see :ref:`tut-tuples`).  Before the variable number of arguments,
zero or more normal arguments may occur. ::
511

Georg Brandl's avatar
Georg Brandl committed
512 513
   def write_multiple_items(file, separator, *args):
       file.write(separator.join(args))
514

515

516
Normally, these ``variadic`` arguments will be last in the list of formal
517
parameters, because they scoop up all remaining input arguments that are
518
passed to the function. Any formal parameters which occur after the ``*args``
519
parameter are 'keyword-only' arguments, meaning that they can only be used as
520
keywords rather than positional arguments. ::
521

522 523 524 525 526 527 528
   >>> def concat(*args, sep="/"):
   ...    return sep.join(args)
   ...
   >>> concat("earth", "mars", "venus")
   'earth/mars/venus'
   >>> concat("earth", "mars", "venus", sep=".")
   'earth.mars.venus'
529 530 531 532 533 534 535 536 537 538 539 540 541

.. _tut-unpacking-arguments:

Unpacking Argument Lists
------------------------

The reverse situation occurs when the arguments are already in a list or tuple
but need to be unpacked for a function call requiring separate positional
arguments.  For instance, the built-in :func:`range` function expects separate
*start* and *stop* arguments.  If they are not available separately, write the
function call with the  ``*``\ -operator to unpack the arguments out of a list
or tuple::

542
   >>> list(range(3, 6))            # normal call with separate arguments
543 544
   [3, 4, 5]
   >>> args = [3, 6]
545
   >>> list(range(*args))            # call with arguments unpacked from a list
546 547
   [3, 4, 5]

Christian Heimes's avatar
Christian Heimes committed
548 549 550
.. index::
  statement: **

551 552 553 554
In the same fashion, dictionaries can deliver keyword arguments with the ``**``\
-operator::

   >>> def parrot(voltage, state='a stiff', action='voom'):
555
   ...     print("-- This parrot wouldn't", action, end=' ')
556 557
   ...     print("if you put", voltage, "volts through it.", end=' ')
   ...     print("E's", state, "!")
558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597
   ...
   >>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
   >>> parrot(**d)
   -- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !


.. _tut-lambda:

Lambda Forms
------------

By popular demand, a few features commonly found in functional programming
languages like Lisp have been added to Python.  With the :keyword:`lambda`
keyword, small anonymous functions can be created. Here's a function that
returns the sum of its two arguments: ``lambda a, b: a+b``.  Lambda forms can be
used wherever function objects are required.  They are syntactically restricted
to a single expression.  Semantically, they are just syntactic sugar for a
normal function definition.  Like nested function definitions, lambda forms can
reference variables from the containing scope::

   >>> def make_incrementor(n):
   ...     return lambda x: x + n
   ...
   >>> f = make_incrementor(42)
   >>> f(0)
   42
   >>> f(1)
   43


.. _tut-docstrings:

Documentation Strings
---------------------

.. index::
   single: docstrings
   single: documentation strings
   single: strings, documentation

598
Here are some conventions about the content and formatting of documentation
599
strings.
600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627

The first line should always be a short, concise summary of the object's
purpose.  For brevity, it should not explicitly state the object's name or type,
since these are available by other means (except if the name happens to be a
verb describing a function's operation).  This line should begin with a capital
letter and end with a period.

If there are more lines in the documentation string, the second line should be
blank, visually separating the summary from the rest of the description.  The
following lines should be one or more paragraphs describing the object's calling
conventions, its side effects, etc.

The Python parser does not strip indentation from multi-line string literals in
Python, so tools that process documentation have to strip indentation if
desired.  This is done using the following convention. The first non-blank line
*after* the first line of the string determines the amount of indentation for
the entire documentation string.  (We can't use the first line since it is
generally adjacent to the string's opening quotes so its indentation is not
apparent in the string literal.)  Whitespace "equivalent" to this indentation is
then stripped from the start of all lines of the string.  Lines that are
indented less should not occur, but if they occur all their leading whitespace
should be stripped.  Equivalence of whitespace should be tested after expansion
of tabs (to 8 spaces, normally).

Here is an example of a multi-line docstring::

   >>> def my_function():
   ...     """Do nothing, but document it.
628
   ...
629 630 631
   ...     No, really, it doesn't do anything.
   ...     """
   ...     pass
632
   ...
633
   >>> print(my_function.__doc__)
634 635 636 637 638
   Do nothing, but document it.

       No, really, it doesn't do anything.


639 640 641 642 643 644 645 646 647 648 649 650 651 652
.. _tut-codingstyle:

Intermezzo: Coding Style
========================

.. sectionauthor:: Georg Brandl <georg@python.org>
.. index:: pair: coding; style

Now that you are about to write longer, more complex pieces of Python, it is a
good time to talk about *coding style*.  Most languages can be written (or more
concise, *formatted*) in different styles; some are more readable than others.
Making it easy for others to read your code is always a good idea, and adopting
a nice coding style helps tremendously for that.

Christian Heimes's avatar
Christian Heimes committed
653
For Python, :pep:`8` has emerged as the style guide that most projects adhere to;
654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680
it promotes a very readable and eye-pleasing coding style.  Every Python
developer should read it at some point; here are the most important points
extracted for you:

* Use 4-space indentation, and no tabs.

  4 spaces are a good compromise between small indentation (allows greater
  nesting depth) and large indentation (easier to read).  Tabs introduce
  confusion, and are best left out.

* Wrap lines so that they don't exceed 79 characters.

  This helps users with small displays and makes it possible to have several
  code files side-by-side on larger displays.

* Use blank lines to separate functions and classes, and larger blocks of
  code inside functions.

* When possible, put comments on a line of their own.

* Use docstrings.

* Use spaces around operators and after commas, but not directly inside
  bracketing constructs: ``a = f(1, 2) + g(3, 4)``.

* Name your classes and functions consistently; the convention is to use
  ``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
Georg Brandl's avatar
Georg Brandl committed
681 682
  and methods.  Always use ``self`` as the name for the first method argument
  (see :ref:`tut-firstclasses` for more on classes and methods).
683 684

* Don't use fancy encodings if your code is meant to be used in international
685 686 687 688 689 690
  environments.  Python's default, UTF-8, or even plain ASCII work best in any
  case.

* Likewise, don't use non-ASCII characters in identifiers if there is only the
  slightest chance people speaking a different language will read or maintain
  the code.
691

692 693 694

.. rubric:: Footnotes

695 696 697
.. [#] Actually, *call by object reference* would be a better description,
   since if a mutable object is passed, the caller will see any changes the
   callee makes to it (items inserted into a list).
698