cpython-lru_cache-weakref: Doc/faq/programming.rst annotate

annotate Doc/faq/programming.rst @ 78069:a8aa77458e12 3.2

Add c_size_t and c_ssize_t to the ctypes summary table.

author	Antoine Pitrou <solipsis@pitrou.net>
date	Thu, 12 Jul 2012 20:31:50 +0200
parents	0092ab03fdd5
children	69d5d834c5cb

rev	line source
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1 :tocdepth: 2
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	2
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	3 ===============
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	4 Programming FAQ
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	5 ===============
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	6
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	7 .. contents::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	8
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	9 General Questions
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	10 =================
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	11
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	12 Is there a source code level debugger with breakpoints, single-stepping, etc.?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	13 ------------------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	14
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	15 Yes.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	16
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	17 The pdb module is a simple but adequate console-mode debugger for Python. It is
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	18 part of the standard Python library, and is :mod:`documented in the Library
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	19 Reference Manual <pdb>`. You can also write your own debugger by using the code
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	20 for pdb as an example.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	21
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	22 The IDLE interactive development environment, which is part of the standard
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	23 Python distribution (normally available as Tools/scripts/idle), includes a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	24 graphical debugger. There is documentation for the IDLE debugger at
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	25 http://www.python.org/idle/doc/idle2.html#Debugger.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	26
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	27 PythonWin is a Python IDE that includes a GUI debugger based on pdb. The
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	28 Pythonwin debugger colors breakpoints and has quite a few cool features such as
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	29 debugging non-Pythonwin programs. Pythonwin is available as part of the `Python
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	30 for Windows Extensions <http://sourceforge.net/projects/pywin32/>`__ project and
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	31 as a part of the ActivePython distribution (see
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	32 http://www.activestate.com/Products/ActivePython/index.html).
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	33
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	34 `Boa Constructor <http://boa-constructor.sourceforge.net/>`_ is an IDE and GUI
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	35 builder that uses wxWidgets. It offers visual frame creation and manipulation,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	36 an object inspector, many views on the source like object browsers, inheritance
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	37 hierarchies, doc string generated html documentation, an advanced debugger,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	38 integrated help, and Zope support.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	39
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	40 `Eric <http://www.die-offenbachs.de/eric/index.html>`_ is an IDE built on PyQt
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	41 and the Scintilla editing component.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	42
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	43 Pydb is a version of the standard Python debugger pdb, modified for use with DDD
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	44 (Data Display Debugger), a popular graphical debugger front end. Pydb can be
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	45 found at http://bashdb.sourceforge.net/pydb/ and DDD can be found at
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	46 http://www.gnu.org/software/ddd.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	47
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	48 There are a number of commercial Python IDEs that include graphical debuggers.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	49 They include:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	50
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	51 * Wing IDE (http://wingware.com/)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	52 * Komodo IDE (http://www.activestate.com/Products/Komodo)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	53
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	54
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	55 Is there a tool to help find bugs or perform static analysis?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	56 -------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	57
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	58 Yes.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	59
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	60 PyChecker is a static analysis tool that finds bugs in Python source code and
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	61 warns about code complexity and style. You can get PyChecker from
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	62 http://pychecker.sf.net.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	63
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	64 `Pylint <http://www.logilab.org/projects/pylint>`_ is another tool that checks
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	65 if a module satisfies a coding standard, and also makes it possible to write
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	66 plug-ins to add a custom feature. In addition to the bug checking that
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	67 PyChecker performs, Pylint offers some additional features such as checking line
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	68 length, whether variable names are well-formed according to your coding
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	69 standard, whether declared interfaces are fully implemented, and more.
56894 b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56893 diff changeset	70 http://www.logilab.org/card/pylint_manual provides a full list of Pylint's
b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56893 diff changeset	71 features.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	72
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	73
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	74 How can I create a stand-alone binary from a Python script?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	75 -----------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	76
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	77 You don't need the ability to compile Python to C code if all you want is a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	78 stand-alone program that users can download and run without having to install
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	79 the Python distribution first. There are a number of tools that determine the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	80 set of modules required by a program and bind these modules together with a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	81 Python binary to produce a single executable.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	82
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	83 One is to use the freeze tool, which is included in the Python source tree as
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	84 ``Tools/freeze``. It converts Python byte code to C arrays; a C compiler you can
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	85 embed all your modules into a new program, which is then linked with the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	86 standard Python modules.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	87
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	88 It works by scanning your source recursively for import statements (in both
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	89 forms) and looking for the modules in the standard Python path as well as in the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	90 source directory (for built-in modules). It then turns the bytecode for modules
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	91 written in Python into C code (array initializers that can be turned into code
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	92 objects using the marshal module) and creates a custom-made config file that
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	93 only contains those built-in modules which are actually used in the program. It
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	94 then compiles the generated C code and links it with the rest of the Python
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	95 interpreter to form a self-contained binary which acts exactly like your script.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	96
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	97 Obviously, freeze requires a C compiler. There are several other utilities
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	98 which don't. One is Thomas Heller's py2exe (Windows only) at
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	99
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	100 http://www.py2exe.org/
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	101
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	102 Another is Christian Tismer's `SQFREEZE <http://starship.python.net/crew/pirx>`_
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	103 which appends the byte code to a specially-prepared Python interpreter that can
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	104 find the byte code in the executable.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	105
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	106 Other tools include Fredrik Lundh's `Squeeze
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	107 <http://www.pythonware.com/products/python/squeeze>`_ and Anthony Tuininga's
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	108 `cx_Freeze <http://starship.python.net/crew/atuining/cx_Freeze/index.html>`_.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	109
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	110
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	111 Are there coding standards or a style guide for Python programs?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	112 ----------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	113
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	114 Yes. The coding style required for standard library modules is documented as
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	115 :pep:`8`.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	116
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	117
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	118 Core Language
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	119 =============
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	120
57242 3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	121 Why am I getting an UnboundLocalError when the variable has a value?
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	122 --------------------------------------------------------------------
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	123
57242 3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	124 It can be a surprise to get the UnboundLocalError in previously working
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	125 code when it is modified by adding an assignment statement somewhere in
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	126 the body of a function.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	127
57242 3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	128 This code:
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	129
57242 3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	130 >>> x = 10
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	131 >>> def bar():
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	132 ... print(x)
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	133 >>> bar()
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	134 10
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	135
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	136 works, but this code:
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	137
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	138 >>> x = 10
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	139 >>> def foo():
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	140 ... print(x)
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	141 ... x += 1
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	142
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	143 results in an UnboundLocalError:
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	144
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	145 >>> foo()
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	146 Traceback (most recent call last):
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	147 ...
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	148 UnboundLocalError: local variable 'x' referenced before assignment
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	149
57242 3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	150 This is because when you make an assignment to a variable in a scope, that
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	151 variable becomes local to that scope and shadows any similarly named variable
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	152 in the outer scope. Since the last statement in foo assigns a new value to
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	153 ``x``, the compiler recognizes it as a local variable. Consequently when the
57244 7d6bad5c2d64 Merged revisions 76272 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 57242 diff changeset	154 earlier ``print(x)`` attempts to print the uninitialized local variable and
57242 3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	155 an error results.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	156
57242 3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	157 In the example above you can access the outer scope variable by declaring it
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	158 global:
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	159
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	160 >>> x = 10
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	161 >>> def foobar():
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	162 ... global x
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	163 ... print(x)
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	164 ... x += 1
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	165 >>> foobar()
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	166 10
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	167
57242 3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	168 This explicit declaration is required in order to remind you that (unlike the
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	169 superficially analogous situation with class and instance variables) you are
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	170 actually modifying the value of the variable in the outer scope:
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	171
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	172 >>> print(x)
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	173 11
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	174
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	175 You can do a similar thing in a nested scope using the :keyword:`nonlocal`
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	176 keyword:
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	177
57242 3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	178 >>> def foo():
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	179 ... x = 10
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	180 ... def bar():
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	181 ... nonlocal x
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	182 ... print(x)
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	183 ... x += 1
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	184 ... bar()
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	185 ... print(x)
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	186 >>> foo()
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	187 10
3d902d67af9c Merged revisions 76270 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56894 diff changeset	188 11
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	189
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	190
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	191 What are the rules for local and global variables in Python?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	192 ------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	193
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	194 In Python, variables that are only referenced inside a function are implicitly
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	195 global. If a variable is assigned a new value anywhere within the function's
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	196 body, it's assumed to be a local. If a variable is ever assigned a new value
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	197 inside the function, the variable is implicitly local, and you need to
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	198 explicitly declare it as 'global'.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	199
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	200 Though a bit surprising at first, a moment's consideration explains this. On
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	201 one hand, requiring :keyword:`global` for assigned variables provides a bar
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	202 against unintended side-effects. On the other hand, if ``global`` was required
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	203 for all global references, you'd be using ``global`` all the time. You'd have
58749 63b3a65aff52 Recorded merge of revisions 78024 via svnmerge from Georg Brandl <georg@python.org> parents: 57813 diff changeset	204 to declare as global every reference to a built-in function or to a component of
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	205 an imported module. This clutter would defeat the usefulness of the ``global``
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	206 declaration for identifying side-effects.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	207
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	208
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	209 How do I share global variables across modules?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	210 ------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	211
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	212 The canonical way to share information across modules within a single program is
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	213 to create a special module (often called config or cfg). Just import the config
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	214 module in all modules of your application; the module then becomes available as
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	215 a global name. Because there is only one instance of each module, any changes
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	216 made to the module object get reflected everywhere. For example:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	217
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	218 config.py::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	219
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	220 x = 0 # Default value of the 'x' configuration setting
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	221
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	222 mod.py::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	223
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	224 import config
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	225 config.x = 1
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	226
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	227 main.py::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	228
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	229 import config
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	230 import mod
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	231 print(config.x)
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	232
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	233 Note that using a module is also the basis for implementing the Singleton design
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	234 pattern, for the same reason.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	235
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	236
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	237 What are the "best practices" for using import in a module?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	238 -----------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	239
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	240 In general, don't use ``from modulename import *``. Doing so clutters the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	241 importer's namespace. Some people avoid this idiom even with the few modules
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	242 that were designed to be imported in this manner. Modules designed in this
56893 70eb6a13abcd Merged revisions 75393,75416,75581,75609,75615 via svnmerge from Georg Brandl <georg@python.org> parents: 56890 diff changeset	243 manner include :mod:`tkinter`, and :mod:`threading`.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	244
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	245 Import modules at the top of a file. Doing so makes it clear what other modules
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	246 your code requires and avoids questions of whether the module name is in scope.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	247 Using one import per line makes it easy to add and delete module imports, but
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	248 using multiple imports per line uses less screen space.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	249
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	250 It's good practice if you import modules in the following order:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	251
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	252 1. standard library modules -- e.g. ``sys``, ``os``, ``getopt``, ``re``
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	253 2. third-party library modules (anything installed in Python's site-packages
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	254 directory) -- e.g. mx.DateTime, ZODB, PIL.Image, etc.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	255 3. locally-developed modules
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	256
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	257 Never use relative package imports. If you're writing code that's in the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	258 ``package.sub.m1`` module and want to import ``package.sub.m2``, do not just
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	259 write ``from . import m2``, even though it's legal. Write ``from package.sub
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	260 import m2`` instead. See :pep:`328` for details.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	261
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	262 It is sometimes necessary to move imports to a function or class to avoid
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	263 problems with circular imports. Gordon McMillan says:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	264
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	265 Circular imports are fine where both modules use the "import <module>" form
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	266 of import. They fail when the 2nd module wants to grab a name out of the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	267 first ("from module import name") and the import is at the top level. That's
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	268 because names in the 1st are not yet available, because the first module is
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	269 busy importing the 2nd.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	270
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	271 In this case, if the second module is only used in one function, then the import
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	272 can easily be moved into that function. By the time the import is called, the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	273 first module will have finished initializing, and the second module can do its
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	274 import.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	275
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	276 It may also be necessary to move imports out of the top level of code if some of
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	277 the modules are platform-specific. In that case, it may not even be possible to
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	278 import all of the modules at the top of the file. In this case, importing the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	279 correct modules in the corresponding platform-specific code is a good option.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	280
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	281 Only move imports into a local scope, such as inside a function definition, if
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	282 it's necessary to solve a problem such as avoiding a circular import or are
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	283 trying to reduce the initialization time of a module. This technique is
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	284 especially helpful if many of the imports are unnecessary depending on how the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	285 program executes. You may also want to move imports into a function if the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	286 modules are only ever used in that function. Note that loading a module the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	287 first time may be expensive because of the one time initialization of the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	288 module, but loading a module multiple times is virtually free, costing only a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	289 couple of dictionary lookups. Even if the module name has gone out of scope,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	290 the module is probably available in :data:`sys.modules`.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	291
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	292 If only instances of a specific class use a module, then it is reasonable to
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	293 import the module in the class's ``__init__`` method and then assign the module
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	294 to an instance variable so that the module is always available (via that
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	295 instance variable) during the life of the object. Note that to delay an import
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	296 until the class is instantiated, the import must be inside a method. Putting
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	297 the import inside the class but outside of any method still causes the import to
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	298 occur when the module is initialized.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	299
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	300
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	301 How can I pass optional or keyword parameters from one function to another?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	302 ---------------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	303
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	304 Collect the arguments using the ```` and ``*`` specifiers in the function's
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	305 parameter list; this gives you the positional arguments as a tuple and the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	306 keyword arguments as a dictionary. You can then pass these arguments when
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	307 calling another function by using ```` and ``*``::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	308
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	309 def f(x, args, *kwargs):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	310 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	311 kwargs['width'] = '14.3c'
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	312 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	313 g(x, args, *kwargs)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	314
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	315
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	316 How do I write a function with output parameters (call by reference)?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	317 ---------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	318
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	319 Remember that arguments are passed by assignment in Python. Since assignment
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	320 just creates references to objects, there's no alias between an argument name in
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	321 the caller and callee, and so no call-by-reference per se. You can achieve the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	322 desired effect in a number of ways.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	323
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	324 1) By returning a tuple of the results::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	325
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	326 def func2(a, b):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	327 a = 'new-value' # a and b are local names
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	328 b = b + 1 # assigned to new objects
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	329 return a, b # return new values
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	330
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	331 x, y = 'old-value', 99
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	332 x, y = func2(x, y)
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	333 print(x, y) # output: new-value 100
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	334
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	335 This is almost always the clearest solution.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	336
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	337 2) By using global variables. This isn't thread-safe, and is not recommended.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	338
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	339 3) By passing a mutable (changeable in-place) object::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	340
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	341 def func1(a):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	342 a[0] = 'new-value' # 'a' references a mutable list
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	343 a[1] = a[1] + 1 # changes a shared object
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	344
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	345 args = ['old-value', 99]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	346 func1(args)
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	347 print(args[0], args[1]) # output: new-value 100
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	348
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	349 4) By passing in a dictionary that gets mutated::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	350
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	351 def func3(args):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	352 args['a'] = 'new-value' # args is a mutable dictionary
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	353 args['b'] = args['b'] + 1 # change it in-place
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	354
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	355 args = {'a':' old-value', 'b': 99}
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	356 func3(args)
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	357 print(args['a'], args['b'])
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	358
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	359 5) Or bundle up values in a class instance::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	360
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	361 class callByRef:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	362 def __init__(self, **args):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	363 for (key, value) in args.items():
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	364 setattr(self, key, value)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	365
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	366 def func4(args):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	367 args.a = 'new-value' # args is a mutable callByRef
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	368 args.b = args.b + 1 # change object in-place
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	369
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	370 args = callByRef(a='old-value', b=99)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	371 func4(args)
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	372 print(args.a, args.b)
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	373
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	374
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	375 There's almost never a good reason to get this complicated.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	376
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	377 Your best choice is to return a tuple containing the multiple results.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	378
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	379
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	380 How do you make a higher order function in Python?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	381 --------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	382
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	383 You have two choices: you can use nested scopes or you can use callable objects.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	384 For example, suppose you wanted to define ``linear(a,b)`` which returns a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	385 function ``f(x)`` that computes the value ``a*x+b``. Using nested scopes::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	386
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	387 def linear(a, b):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	388 def result(x):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	389 return a * x + b
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	390 return result
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	391
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	392 Or using a callable object::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	393
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	394 class linear:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	395
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	396 def __init__(self, a, b):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	397 self.a, self.b = a, b
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	398
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	399 def __call__(self, x):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	400 return self.a * x + self.b
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	401
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	402 In both cases, ::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	403
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	404 taxes = linear(0.3, 2)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	405
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	406 gives a callable object where ``taxes(10e6) == 0.3 * 10e6 + 2``.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	407
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	408 The callable object approach has the disadvantage that it is a bit slower and
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	409 results in slightly longer code. However, note that a collection of callables
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	410 can share their signature via inheritance::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	411
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	412 class exponential(linear):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	413 # __init__ inherited
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	414 def __call__(self, x):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	415 return self.a * (x ** self.b)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	416
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	417 Object can encapsulate state for several methods::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	418
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	419 class counter:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	420
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	421 value = 0
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	422
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	423 def set(self, x):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	424 self.value = x
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	425
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	426 def up(self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	427 self.value = self.value + 1
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	428
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	429 def down(self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	430 self.value = self.value - 1
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	431
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	432 count = counter()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	433 inc, dec, reset = count.up, count.down, count.set
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	434
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	435 Here ``inc()``, ``dec()`` and ``reset()`` act like functions which share the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	436 same counting variable.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	437
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	438
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	439 How do I copy an object in Python?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	440 ----------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	441
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	442 In general, try :func:`copy.copy` or :func:`copy.deepcopy` for the general case.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	443 Not all objects can be copied, but most can.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	444
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	445 Some objects can be copied more easily. Dictionaries have a :meth:`~dict.copy`
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	446 method::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	447
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	448 newdict = olddict.copy()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	449
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	450 Sequences can be copied by slicing::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	451
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	452 new_l = l[:]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	453
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	454
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	455 How can I find the methods or attributes of an object?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	456 ------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	457
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	458 For an instance x of a user-defined class, ``dir(x)`` returns an alphabetized
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	459 list of the names containing the instance attributes and methods and attributes
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	460 defined by its class.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	461
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	462
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	463 How can my code discover the name of an object?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	464 -----------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	465
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	466 Generally speaking, it can't, because objects don't really have names.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	467 Essentially, assignment always binds a name to a value; The same is true of
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	468 ``def`` and ``class`` statements, but in that case the value is a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	469 callable. Consider the following code::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	470
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	471 class A:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	472 pass
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	473
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	474 B = A
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	475
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	476 a = B()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	477 b = a
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	478 print(b)
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	479 <__main__.A object at 0x16D07CC>
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	480 print(a)
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	481 <__main__.A object at 0x16D07CC>
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	482
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	483 Arguably the class has a name: even though it is bound to two names and invoked
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	484 through the name B the created instance is still reported as an instance of
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	485 class A. However, it is impossible to say whether the instance's name is a or
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	486 b, since both names are bound to the same value.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	487
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	488 Generally speaking it should not be necessary for your code to "know the names"
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	489 of particular values. Unless you are deliberately writing introspective
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	490 programs, this is usually an indication that a change of approach might be
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	491 beneficial.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	492
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	493 In comp.lang.python, Fredrik Lundh once gave an excellent analogy in answer to
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	494 this question:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	495
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	496 The same way as you get the name of that cat you found on your porch: the cat
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	497 (object) itself cannot tell you its name, and it doesn't really care -- so
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	498 the only way to find out what it's called is to ask all your neighbours
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	499 (namespaces) if it's their cat (object)...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	500
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	501 ....and don't be surprised if you'll find that it's known by many names, or
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	502 no name at all!
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	503
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	504
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	505 What's up with the comma operator's precedence?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	506 -----------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	507
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	508 Comma is not an operator in Python. Consider this session::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	509
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	510 >>> "a" in "b", "a"
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	511 (False, 'a')
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	512
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	513 Since the comma is not an operator, but a separator between expressions the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	514 above is evaluated as if you had entered::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	515
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	516 >>> ("a" in "b"), "a"
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	517
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	518 not::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	519
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	520 >>> "a" in ("b", "a")
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	521
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	522 The same is true of the various assignment operators (``=``, ``+=`` etc). They
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	523 are not truly operators but syntactic delimiters in assignment statements.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	524
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	525
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	526 Is there an equivalent of C's "?:" ternary operator?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	527 ----------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	528
73834 140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	529 Yes, there is. The syntax is as follows::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	530
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	531 [on_true] if [expression] else [on_false]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	532
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	533 x, y = 50, 25
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	534 small = x if x < y else y
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	535
73834 140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	536 Before this syntax was introduced in Python 2.5, a common idiom was to use
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	537 logical operators::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	538
73834 140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	539 [expression] and [on_true] or [on_false]
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	540
73834 140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	541 However, this idiom is unsafe, as it can give wrong results when on_true
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	542 has a false boolean value. Therefore, it is always better to use
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	543 the ``... if ... else ...`` form.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	544
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	545
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	546 Is it possible to write obfuscated one-liners in Python?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	547 --------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	548
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	549 Yes. Usually this is done by nesting :keyword:`lambda` within
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	550 :keyword:`lambda`. See the following three examples, due to Ulf Bartelt::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	551
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	552 from functools import reduce
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	553
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	554 # Primes < 1000
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	555 print(list(filter(None,map(lambda y:yreduce(lambda x,y:xy!=0,
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	556 map(lambda x,y=y:y%x,range(2,int(pow(y,0.5)+1))),1),range(2,1000)))))
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	557
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	558 # First 10 Fibonacci numbers
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	559 print(list(map(lambda x,f=lambda x,f:(f(x-1,f)+f(x-2,f)) if x>1 else 1:
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	560 f(x,f), range(10))))
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	561
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	562 # Mandelbrot set
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	563 print((lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+y,map(lambda y,
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	564 Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	565 Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	566 i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (xx+yy
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	567 >=4.0) or 1+f(xc,yc,xx-yy+xc,2.0xy+yc,k-1,f):f(xc,yc,x,y,k,f):chr(
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	568 64+F(Ru+x(Ro-Ru)/Sx,yc,0,0,i)),range(Sx))):L(Iu+y(Io-Iu)/Sy),range(Sy
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	569 ))))(-2.1, 0.7, -1.2, 1.2, 30, 80, 24))
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	570 # \___ ___/ \___ ___/ \| \| \|__ lines on screen
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	571 # V V \| \|______ columns on screen
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	572 # \| \| \|__________ maximum of "iterations"
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	573 # \| \|_________________ range on y axis
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	574 # \|____________________________ range on x axis
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	575
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	576 Don't try this at home, kids!
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	577
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	578
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	579 Numbers and strings
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	580 ===================
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	581
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	582 How do I specify hexadecimal and octal integers?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	583 ------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	584
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	585 To specify an octal digit, precede the octal value with a zero, and then a lower
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	586 or uppercase "o". For example, to set the variable "a" to the octal value "10"
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	587 (8 in decimal), type::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	588
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	589 >>> a = 0o10
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	590 >>> a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	591 8
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	592
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	593 Hexadecimal is just as easy. Simply precede the hexadecimal number with a zero,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	594 and then a lower or uppercase "x". Hexadecimal digits can be specified in lower
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	595 or uppercase. For example, in the Python interpreter::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	596
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	597 >>> a = 0xa5
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	598 >>> a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	599 165
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	600 >>> b = 0XB2
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	601 >>> b
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	602 178
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	603
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	604
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	605 Why does -22 // 10 return -3?
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	606 -----------------------------
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	607
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	608 It's primarily driven by the desire that ``i % j`` have the same sign as ``j``.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	609 If you want that, and also want::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	610
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	611 i == (i // j) * j + (i % j)
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	612
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	613 then integer division has to return the floor. C also requires that identity to
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	614 hold, and then compilers that truncate ``i // j`` need to make ``i % j`` have
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	615 the same sign as ``i``.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	616
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	617 There are few real use cases for ``i % j`` when ``j`` is negative. When ``j``
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	618 is positive, there are many, and in virtually all of them it's more useful for
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	619 ``i % j`` to be ``>= 0``. If the clock says 10 now, what did it say 200 hours
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	620 ago? ``-190 % 12 == 2`` is useful; ``-190 % 12 == -10`` is a bug waiting to
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	621 bite.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	622
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	623
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	624 How do I convert a string to a number?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	625 --------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	626
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	627 For integers, use the built-in :func:`int` type constructor, e.g. ``int('144')
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	628 == 144``. Similarly, :func:`float` converts to floating-point,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	629 e.g. ``float('144') == 144.0``.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	630
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	631 By default, these interpret the number as decimal, so that ``int('0144') ==
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	632 144`` and ``int('0x144')`` raises :exc:`ValueError`. ``int(string, base)`` takes
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	633 the base to convert from as a second optional argument, so ``int('0x144', 16) ==
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	634 324``. If the base is specified as 0, the number is interpreted using Python's
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	635 rules: a leading '0' indicates octal, and '0x' indicates a hex number.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	636
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	637 Do not use the built-in function :func:`eval` if all you need is to convert
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	638 strings to numbers. :func:`eval` will be significantly slower and it presents a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	639 security risk: someone could pass you a Python expression that might have
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	640 unwanted side effects. For example, someone could pass
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	641 ``__import__('os').system("rm -rf $HOME")`` which would erase your home
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	642 directory.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	643
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	644 :func:`eval` also has the effect of interpreting numbers as Python expressions,
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	645 so that e.g. ``eval('09')`` gives a syntax error because Python does not allow
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	646 leading '0' in a decimal number (except '0').
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	647
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	648
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	649 How do I convert a number to a string?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	650 --------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	651
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	652 To convert, e.g., the number 144 to the string '144', use the built-in type
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	653 constructor :func:`str`. If you want a hexadecimal or octal representation, use
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	654 the built-in functions :func:`hex` or :func:`oct`. For fancy formatting, see
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	655 the :ref:`string-formatting` section, e.g. ``"{:04d}".format(144)`` yields
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	656 ``'0144'`` and ``"{:.3f}".format(1/3)`` yields ``'0.333'``.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	657
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	658
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	659 How do I modify a string in place?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	660 ----------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	661
73834 140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	662 You can't, because strings are immutable. In most situations, you should
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	663 simply construct a new string from the various parts you want to assemble
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	664 it from. However, if you need an object with the ability to modify in-place
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	665 unicode data, try using a :class:`io.StringIO` object or the :mod:`array`
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	666 module::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	667
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	668 >>> s = "Hello, world"
73834 140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	669 >>> sio = io.StringIO(s)
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	670 >>> sio.getvalue()
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	671 'Hello, world'
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	672 >>> sio.seek(7)
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	673 7
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	674 >>> sio.write("there!")
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	675 6
140b8c98c7b9 Streamline FAQ entry about the ternary operator, and suggest using io.StringIO for a mutable unicode container. Antoine Pitrou <solipsis@pitrou.net> parents: 73832 diff changeset	676 >>> sio.getvalue()
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	677 'Hello, there!'
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	678
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	679 >>> import array
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	680 >>> a = array.array('u', s)
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	681 >>> print(a)
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	682 array('u', 'Hello, world')
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	683 >>> a[0] = 'y'
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	684 >>> print(a)
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	685 array('u', 'yello world')
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	686 >>> a.tounicode()
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	687 'yello, world'
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	688
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	689
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	690 How do I use strings to call functions/methods?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	691 -----------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	692
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	693 There are various techniques.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	694
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	695 * The best is to use a dictionary that maps strings to functions. The primary
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	696 advantage of this technique is that the strings do not need to match the names
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	697 of the functions. This is also the primary technique used to emulate a case
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	698 construct::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	699
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	700 def a():
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	701 pass
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	702
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	703 def b():
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	704 pass
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	705
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	706 dispatch = {'go': a, 'stop': b} # Note lack of parens for funcs
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	707
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	708 dispatch[get_input()]() # Note trailing parens to call function
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	709
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	710 * Use the built-in function :func:`getattr`::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	711
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	712 import foo
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	713 getattr(foo, 'bar')()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	714
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	715 Note that :func:`getattr` works on any object, including classes, class
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	716 instances, modules, and so on.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	717
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	718 This is used in several places in the standard library, like this::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	719
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	720 class Foo:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	721 def do_foo(self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	722 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	723
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	724 def do_bar(self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	725 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	726
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	727 f = getattr(foo_instance, 'do_' + opname)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	728 f()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	729
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	730
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	731 * Use :func:`locals` or :func:`eval` to resolve the function name::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	732
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	733 def myFunc():
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	734 print("hello")
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	735
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	736 fname = "myFunc"
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	737
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	738 f = locals()[fname]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	739 f()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	740
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	741 f = eval(fname)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	742 f()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	743
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	744 Note: Using :func:`eval` is slow and dangerous. If you don't have absolute
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	745 control over the contents of the string, someone could pass a string that
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	746 resulted in an arbitrary function being executed.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	747
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	748 Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	749 -------------------------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	750
73836 93f64ae51fff Remove outdate FAQ content Antoine Pitrou <solipsis@pitrou.net> parents: 73834 diff changeset	751 You can use ``S.rstrip("\r\n")`` to remove all occurrences of any line
93f64ae51fff Remove outdate FAQ content Antoine Pitrou <solipsis@pitrou.net> parents: 73834 diff changeset	752 terminator from the end of the string ``S`` without removing other trailing
93f64ae51fff Remove outdate FAQ content Antoine Pitrou <solipsis@pitrou.net> parents: 73834 diff changeset	753 whitespace. If the string ``S`` represents more than one line, with several
93f64ae51fff Remove outdate FAQ content Antoine Pitrou <solipsis@pitrou.net> parents: 73834 diff changeset	754 empty lines at the end, the line terminators for all the blank lines will
93f64ae51fff Remove outdate FAQ content Antoine Pitrou <solipsis@pitrou.net> parents: 73834 diff changeset	755 be removed::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	756
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	757 >>> lines = ("line 1 \r\n"
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	758 ... "\r\n"
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	759 ... "\r\n")
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	760 >>> lines.rstrip("\n\r")
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	761 'line 1 '
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	762
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	763 Since this is typically only desired when reading text one line at a time, using
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	764 ``S.rstrip()`` this way works well.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	765
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	766
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	767 Is there a scanf() or sscanf() equivalent?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	768 ------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	769
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	770 Not as such.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	771
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	772 For simple input parsing, the easiest approach is usually to split the line into
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	773 whitespace-delimited words using the :meth:`~str.split` method of string objects
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	774 and then convert decimal strings to numeric values using :func:`int` or
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	775 :func:`float`. ``split()`` supports an optional "sep" parameter which is useful
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	776 if the line uses something other than whitespace as a separator.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	777
64901 96e7ee232abf #9582 - add a missing "are" and reflow the line. Brian Curtin <brian.curtin@gmail.com> parents: 64875 diff changeset	778 For more complicated input parsing, regular expressions are more powerful
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 64901 diff changeset	779 than C's :c:func:`sscanf` and better suited for the task.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	780
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	781
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	782 What does 'UnicodeDecodeError' or 'UnicodeEncodeError' error mean?
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	783 -------------------------------------------------------------------
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	784
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	785 See the :ref:`unicode-howto`.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	786
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	787
73908 eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	788 Performance
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	789 ===========
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	790
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	791 My program is too slow. How do I speed it up?
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	792 ---------------------------------------------
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	793
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	794 That's a tough one, in general. First, here are a list of things to
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	795 remember before diving further:
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	796
75647 0092ab03fdd5 Closes #14305: fix typo. Georg Brandl <georg@python.org> parents: 73908 diff changeset	797 * Performance characteristics vary across Python implementations. This FAQ
73908 eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	798 focusses on :term:`CPython`.
75647 0092ab03fdd5 Closes #14305: fix typo. Georg Brandl <georg@python.org> parents: 73908 diff changeset	799 * Behaviour can vary across operating systems, especially when talking about
73908 eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	800 I/O or multi-threading.
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	801 * You should always find the hot spots in your program before attempting to
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	802 optimize any code (see the :mod:`profile` module).
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	803 * Writing benchmark scripts will allow you to iterate quickly when searching
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	804 for improvements (see the :mod:`timeit` module).
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	805 * It is highly recommended to have good code coverage (through unit testing
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	806 or any other technique) before potentially introducing regressions hidden
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	807 in sophisticated optimizations.
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	808
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	809 That being said, there are many tricks to speed up Python code. Here are
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	810 some general principles which go a long way towards reaching acceptable
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	811 performance levels:
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	812
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	813 * Making your algorithms faster (or changing to faster ones) can yield
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	814 much larger benefits than trying to sprinkle micro-optimization tricks
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	815 all over your code.
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	816
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	817 * Use the right data structures. Study documentation for the :ref:`bltin-types`
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	818 and the :mod:`collections` module.
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	819
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	820 * When the standard library provides a primitive for doing something, it is
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	821 likely (although not guaranteed) to be faster than any alternative you
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	822 may come up with. This is doubly true for primitives written in C, such
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	823 as builtins and some extension types. For example, be sure to use
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	824 either the :meth:`list.sort` built-in method or the related :func:`sorted`
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	825 function to do sorting (and see the
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	826 `sorting mini-HOWTO <http://wiki.python.org/moin/HowTo/Sorting>`_ for examples
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	827 of moderately advanced usage).
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	828
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	829 * Abstractions tend to create indirections and force the interpreter to work
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	830 more. If the levels of indirection outweigh the amount of useful work
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	831 done, your program will be slower. You should avoid excessive abstraction,
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	832 especially under the form of tiny functions or methods (which are also often
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	833 detrimental to readability).
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	834
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	835 If you have reached the limit of what pure Python can allow, there are tools
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	836 to take you further away. For example, `Cython <http://cython.org>`_ can
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	837 compile a slightly modified version of Python code into a C extension, and
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	838 can be used on many different platforms. Cython can take advantage of
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	839 compilation (and optional type annotations) to make your code significantly
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	840 faster than when interpreted. If you are confident in your C programming
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	841 skills, you can also :ref:`write a C extension module <extending-index>`
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	842 yourself.
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	843
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	844 .. seealso::
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	845 The wiki page devoted to `performance tips
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	846 <http://wiki.python.org/moin/PythonSpeed/PerformanceTips>`_.
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	847
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	848 .. _efficient_string_concatenation:
eb30f2becb79 Issue #13528: rework the performance question in the programming FAQ Antoine Pitrou <solipsis@pitrou.net> parents: 73836 diff changeset	849
73735 2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	850 What is the most efficient way to concatenate many strings together?
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	851 --------------------------------------------------------------------
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	852
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	853 :class:`str` and :class:`bytes` objects are immutable, therefore concatenating
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	854 many strings together is inefficient as each concatenation creates a new
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	855 object. In the general case, the total runtime cost is quadratic in the
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	856 total string length.
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	857
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	858 To accumulate many :class:`str` objects, the recommended idiom is to place
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	859 them into a list and call :meth:`str.join` at the end::
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	860
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	861 chunks = []
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	862 for s in my_strings:
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	863 chunks.append(s)
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	864 result = ''.join(chunks)
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	865
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	866 (another reasonably efficient idiom is to use :class:`io.StringIO`)
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	867
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	868 To accumulate many :class:`bytes` objects, the recommended idiom is to extend
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	869 a :class:`bytearray` object using in-place concatenation (the ``+=`` operator)::
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	870
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	871 result = bytearray()
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	872 for b in my_bytes_objects:
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	873 result += b
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	874
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 72177 diff changeset	875
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	876 Sequences (Tuples/Lists)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	877 ========================
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	878
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	879 How do I convert between tuples and lists?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	880 ------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	881
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	882 The type constructor ``tuple(seq)`` converts any sequence (actually, any
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	883 iterable) into a tuple with the same items in the same order.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	884
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	885 For example, ``tuple([1, 2, 3])`` yields ``(1, 2, 3)`` and ``tuple('abc')``
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	886 yields ``('a', 'b', 'c')``. If the argument is a tuple, it does not make a copy
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	887 but returns the same object, so it is cheap to call :func:`tuple` when you
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	888 aren't sure that an object is already a tuple.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	889
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	890 The type constructor ``list(seq)`` converts any sequence or iterable into a list
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	891 with the same items in the same order. For example, ``list((1, 2, 3))`` yields
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	892 ``[1, 2, 3]`` and ``list('abc')`` yields ``['a', 'b', 'c']``. If the argument
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	893 is a list, it makes a copy just like ``seq[:]`` would.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	894
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	895
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	896 What's a negative index?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	897 ------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	898
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	899 Python sequences are indexed with positive numbers and negative numbers. For
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	900 positive numbers 0 is the first index 1 is the second index and so forth. For
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	901 negative indices -1 is the last index and -2 is the penultimate (next to last)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	902 index and so forth. Think of ``seq[-n]`` as the same as ``seq[len(seq)-n]``.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	903
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	904 Using negative indices can be very convenient. For example ``S[:-1]`` is all of
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	905 the string except for its last character, which is useful for removing the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	906 trailing newline from a string.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	907
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	908
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	909 How do I iterate over a sequence in reverse order?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	910 --------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	911
58749 63b3a65aff52 Recorded merge of revisions 78024 via svnmerge from Georg Brandl <georg@python.org> parents: 57813 diff changeset	912 Use the :func:`reversed` built-in function, which is new in Python 2.4::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	913
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	914 for x in reversed(sequence):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	915 ... # do something with x...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	916
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	917 This won't touch your original sequence, but build a new copy with reversed
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	918 order to iterate over.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	919
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	920 With Python 2.3, you can use an extended slice syntax::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	921
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	922 for x in sequence[::-1]:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	923 ... # do something with x...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	924
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	925
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	926 How do you remove duplicates from a list?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	927 -----------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	928
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	929 See the Python Cookbook for a long discussion of many ways to do this:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	930
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	931 http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52560
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	932
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	933 If you don't mind reordering the list, sort it and then scan from the end of the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	934 list, deleting duplicates as you go::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	935
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	936 if mylist:
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	937 mylist.sort()
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	938 last = mylist[-1]
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	939 for i in range(len(mylist)-2, -1, -1):
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	940 if last == mylist[i]:
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	941 del mylist[i]
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	942 else:
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	943 last = mylist[i]
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	944
73836 93f64ae51fff Remove outdate FAQ content Antoine Pitrou <solipsis@pitrou.net> parents: 73834 diff changeset	945 If all elements of the list may be used as set keys (i.e. they are all
93f64ae51fff Remove outdate FAQ content Antoine Pitrou <solipsis@pitrou.net> parents: 73834 diff changeset	946 :term:`hashable`) this is often faster ::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	947
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	948 mylist = list(set(mylist))
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	949
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	950 This converts the list into a set, thereby removing duplicates, and then back
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	951 into a list.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	952
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	953
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	954 How do you make an array in Python?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	955 -----------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	956
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	957 Use a list::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	958
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	959 ["this", 1, "is", "an", "array"]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	960
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	961 Lists are equivalent to C or Pascal arrays in their time complexity; the primary
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	962 difference is that a Python list can contain objects of many different types.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	963
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	964 The ``array`` module also provides methods for creating arrays of fixed types
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	965 with compact representations, but they are slower to index than lists. Also
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	966 note that the Numeric extensions and others define array-like structures with
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	967 various characteristics as well.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	968
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	969 To get Lisp-style linked lists, you can emulate cons cells using tuples::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	970
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	971 lisp_list = ("like", ("this", ("example", None) ) )
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	972
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	973 If mutability is desired, you could use lists instead of tuples. Here the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	974 analogue of lisp car is ``lisp_list[0]`` and the analogue of cdr is
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	975 ``lisp_list[1]``. Only do this if you're sure you really need to, because it's
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	976 usually a lot slower than using Python lists.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	977
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	978
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	979 How do I create a multidimensional list?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	980 ----------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	981
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	982 You probably tried to make a multidimensional array like this::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	983
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	984 A = [[None] * 2] * 3
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	985
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	986 This looks correct if you print it::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	987
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	988 >>> A
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	989 [[None, None], [None, None], [None, None]]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	990
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	991 But when you assign a value, it shows up in multiple places:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	992
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	993 >>> A[0][0] = 5
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	994 >>> A
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	995 [[5, None], [5, None], [5, None]]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	996
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	997 The reason is that replicating a list with ``*`` doesn't create copies, it only
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	998 creates references to the existing objects. The ``*3`` creates a list
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	999 containing 3 references to the same list of length two. Changes to one row will
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1000 show in all rows, which is almost certainly not what you want.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1001
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1002 The suggested approach is to create a list of the desired length first and then
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1003 fill in each element with a newly created list::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1004
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1005 A = [None] * 3
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1006 for i in range(3):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1007 A[i] = [None] * 2
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1008
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1009 This generates a list containing 3 different lists of length two. You can also
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1010 use a list comprehension::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1011
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1012 w, h = 2, 3
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1013 A = [[None] * w for i in range(h)]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1014
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1015 Or, you can use an extension that provides a matrix datatype; `Numeric Python
56894 b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56893 diff changeset	1016 <http://numpy.scipy.org/>`_ is the best known.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1017
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1018
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1019 How do I apply a method to a sequence of objects?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1020 -------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1021
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1022 Use a list comprehension::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1023
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1024 result = [obj.method() for obj in mylist]
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1025
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1026
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1027 Dictionaries
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1028 ============
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1029
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1030 How can I get a dictionary to display its keys in a consistent order?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1031 ---------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1032
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1033 You can't. Dictionaries store their keys in an unpredictable order, so the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1034 display order of a dictionary's elements will be similarly unpredictable.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1035
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1036 This can be frustrating if you want to save a printable version to a file, make
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1037 some changes and then compare it with some other printed dictionary. In this
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1038 case, use the ``pprint`` module to pretty-print the dictionary; the items will
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1039 be presented in order sorted by the key.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1040
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1041 A more complicated solution is to subclass ``dict`` to create a
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1042 ``SortedDict`` class that prints itself in a predictable order. Here's one
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1043 simpleminded implementation of such a class::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1044
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1045 class SortedDict(dict):
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1046 def __repr__(self):
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1047 keys = sorted(self.keys())
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1048 result = ("{!r}: {!r}".format(k, self[k]) for k in keys)
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1049 return "{{{}}}".format(", ".join(result))
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1050
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1051 __str__ = __repr__
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1052
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1053 This will work for many common situations you might encounter, though it's far
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1054 from a perfect solution. The largest flaw is that if some values in the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1055 dictionary are also dictionaries, their values won't be presented in any
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1056 particular order.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1057
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1058
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1059 I want to do a complicated sort: can you do a Schwartzian Transform in Python?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1060 ------------------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1061
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1062 The technique, attributed to Randal Schwartz of the Perl community, sorts the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1063 elements of a list by a metric which maps each element to its "sort value". In
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1064 Python, just use the ``key`` argument for the ``sort()`` method::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1065
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1066 Isorted = L[:]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1067 Isorted.sort(key=lambda s: int(s[10:15]))
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1068
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1069 The ``key`` argument is new in Python 2.4, for older versions this kind of
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1070 sorting is quite simple to do with list comprehensions. To sort a list of
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1071 strings by their uppercase values::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1072
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1073 tmp1 = [(x.upper(), x) for x in L] # Schwartzian transform
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1074 tmp1.sort()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1075 Usorted = [x[1] for x in tmp1]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1076
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1077 To sort by the integer value of a subfield extending from positions 10-15 in
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1078 each string::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1079
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1080 tmp2 = [(int(s[10:15]), s) for s in L] # Schwartzian transform
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1081 tmp2.sort()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1082 Isorted = [x[1] for x in tmp2]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1083
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1084 For versions prior to 3.0, Isorted may also be computed by ::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1085
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1086 def intfield(s):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1087 return int(s[10:15])
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1088
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1089 def Icmp(s1, s2):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1090 return cmp(intfield(s1), intfield(s2))
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1091
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1092 Isorted = L[:]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1093 Isorted.sort(Icmp)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1094
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1095 but since this method calls ``intfield()`` many times for each element of L, it
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1096 is slower than the Schwartzian Transform.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1097
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1098
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1099 How can I sort one list by values from another list?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1100 ----------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1101
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1102 Merge them into an iterator of tuples, sort the resulting list, and then pick
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1103 out the element you want. ::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1104
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1105 >>> list1 = ["what", "I'm", "sorting", "by"]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1106 >>> list2 = ["something", "else", "to", "sort"]
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1107 >>> pairs = zip(list1, list2)
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1108 >>> pairs = sorted(pairs)
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1109 >>> pairs
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1110 [("I'm", 'else'), ('by', 'sort'), ('sorting', 'to'), ('what', 'something')]
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1111 >>> result = [x[1] for x in pairs]
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1112 >>> result
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1113 ['else', 'sort', 'to', 'something']
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1114
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1115
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1116 An alternative for the last step is::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1117
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1118 >>> result = []
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1119 >>> for p in pairs: result.append(p[1])
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1120
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1121 If you find this more legible, you might prefer to use this instead of the final
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1122 list comprehension. However, it is almost twice as slow for long lists. Why?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1123 First, the ``append()`` operation has to reallocate memory, and while it uses
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1124 some tricks to avoid doing that each time, it still has to do it occasionally,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1125 and that costs quite a bit. Second, the expression "result.append" requires an
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1126 extra attribute lookup, and third, there's a speed reduction from having to make
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1127 all those function calls.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1128
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1129
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1130 Objects
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1131 =======
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1132
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1133 What is a class?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1134 ----------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1135
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1136 A class is the particular object type created by executing a class statement.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1137 Class objects are used as templates to create instance objects, which embody
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1138 both the data (attributes) and code (methods) specific to a datatype.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1139
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1140 A class can be based on one or more other classes, called its base class(es). It
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1141 then inherits the attributes and methods of its base classes. This allows an
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1142 object model to be successively refined by inheritance. You might have a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1143 generic ``Mailbox`` class that provides basic accessor methods for a mailbox,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1144 and subclasses such as ``MboxMailbox``, ``MaildirMailbox``, ``OutlookMailbox``
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1145 that handle various specific mailbox formats.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1146
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1147
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1148 What is a method?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1149 -----------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1150
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1151 A method is a function on some object ``x`` that you normally call as
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1152 ``x.name(arguments...)``. Methods are defined as functions inside the class
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1153 definition::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1154
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1155 class C:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1156 def meth (self, arg):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1157 return arg * 2 + self.attribute
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1158
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1159
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1160 What is self?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1161 -------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1162
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1163 Self is merely a conventional name for the first argument of a method. A method
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1164 defined as ``meth(self, a, b, c)`` should be called as ``x.meth(a, b, c)`` for
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1165 some instance ``x`` of the class in which the definition occurs; the called
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1166 method will think it is called as ``meth(x, a, b, c)``.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1167
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1168 See also :ref:`why-self`.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1169
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1170
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1171 How do I check if an object is an instance of a given class or of a subclass of it?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1172 -----------------------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1173
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1174 Use the built-in function ``isinstance(obj, cls)``. You can check if an object
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1175 is an instance of any of a number of classes by providing a tuple instead of a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1176 single class, e.g. ``isinstance(obj, (class1, class2, ...))``, and can also
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1177 check whether an object is one of Python's built-in types, e.g.
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1178 ``isinstance(obj, str)`` or ``isinstance(obj, (int, float, complex))``.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1179
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1180 Note that most programs do not use :func:`isinstance` on user-defined classes
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1181 very often. If you are developing the classes yourself, a more proper
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1182 object-oriented style is to define methods on the classes that encapsulate a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1183 particular behaviour, instead of checking the object's class and doing a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1184 different thing based on what class it is. For example, if you have a function
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1185 that does something::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1186
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1187 def search(obj):
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1188 if isinstance(obj, Mailbox):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1189 # ... code to search a mailbox
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1190 elif isinstance(obj, Document):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1191 # ... code to search a document
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1192 elif ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1193
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1194 A better approach is to define a ``search()`` method on all the classes and just
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1195 call it::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1196
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1197 class Mailbox:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1198 def search(self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1199 # ... code to search a mailbox
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1200
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1201 class Document:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1202 def search(self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1203 # ... code to search a document
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1204
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1205 obj.search()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1206
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1207
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1208 What is delegation?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1209 -------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1210
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1211 Delegation is an object oriented technique (also called a design pattern).
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1212 Let's say you have an object ``x`` and want to change the behaviour of just one
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1213 of its methods. You can create a new class that provides a new implementation
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1214 of the method you're interested in changing and delegates all other methods to
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1215 the corresponding method of ``x``.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1216
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1217 Python programmers can easily implement delegation. For example, the following
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1218 class implements a class that behaves like a file but converts all written data
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1219 to uppercase::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1220
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1221 class UpperOut:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1222
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1223 def __init__(self, outfile):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1224 self._outfile = outfile
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1225
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1226 def write(self, s):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1227 self._outfile.write(s.upper())
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1228
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1229 def __getattr__(self, name):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1230 return getattr(self._outfile, name)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1231
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1232 Here the ``UpperOut`` class redefines the ``write()`` method to convert the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1233 argument string to uppercase before calling the underlying
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1234 ``self.__outfile.write()`` method. All other methods are delegated to the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1235 underlying ``self.__outfile`` object. The delegation is accomplished via the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1236 ``__getattr__`` method; consult :ref:`the language reference <attribute-access>`
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1237 for more information about controlling attribute access.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1238
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1239 Note that for more general cases delegation can get trickier. When attributes
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1240 must be set as well as retrieved, the class must define a :meth:`__setattr__`
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1241 method too, and it must do so carefully. The basic implementation of
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1242 :meth:`__setattr__` is roughly equivalent to the following::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1243
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1244 class X:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1245 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1246 def __setattr__(self, name, value):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1247 self.__dict__[name] = value
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1248 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1249
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1250 Most :meth:`__setattr__` implementations must modify ``self.__dict__`` to store
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1251 local state for self without causing an infinite recursion.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1252
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1253
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1254 How do I call a method defined in a base class from a derived class that overrides it?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1255 --------------------------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1256
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1257 Use the built-in :func:`super` function::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1258
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1259 class Derived(Base):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1260 def meth (self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1261 super(Derived, self).meth()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1262
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1263 For version prior to 3.0, you may be using classic classes: For a class
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1264 definition such as ``class Derived(Base): ...`` you can call method ``meth()``
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1265 defined in ``Base`` (or one of ``Base``'s base classes) as ``Base.meth(self,
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1266 arguments...)``. Here, ``Base.meth`` is an unbound method, so you need to
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1267 provide the ``self`` argument.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1268
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1269
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1270 How can I organize my code to make it easier to change the base class?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1271 ----------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1272
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1273 You could define an alias for the base class, assign the real base class to it
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1274 before your class definition, and use the alias throughout your class. Then all
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1275 you have to change is the value assigned to the alias. Incidentally, this trick
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1276 is also handy if you want to decide dynamically (e.g. depending on availability
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1277 of resources) which base class to use. Example::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1278
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1279 BaseAlias = <real base class>
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1280
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1281 class Derived(BaseAlias):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1282 def meth(self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1283 BaseAlias.meth(self)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1284 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1285
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1286
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1287 How do I create static class data and static class methods?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1288 -----------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1289
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1290 Both static data and static methods (in the sense of C++ or Java) are supported
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1291 in Python.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1292
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1293 For static data, simply define a class attribute. To assign a new value to the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1294 attribute, you have to explicitly use the class name in the assignment::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1295
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1296 class C:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1297 count = 0 # number of times C.__init__ called
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1298
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1299 def __init__(self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1300 C.count = C.count + 1
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1301
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1302 def getcount(self):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1303 return C.count # or return self.count
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1304
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1305 ``c.count`` also refers to ``C.count`` for any ``c`` such that ``isinstance(c,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1306 C)`` holds, unless overridden by ``c`` itself or by some class on the base-class
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1307 search path from ``c.__class__`` back to ``C``.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1308
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1309 Caution: within a method of C, an assignment like ``self.count = 42`` creates a
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1310 new and unrelated instance named "count" in ``self``'s own dict. Rebinding of a
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1311 class-static data name must always specify the class whether inside a method or
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1312 not::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1313
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1314 C.count = 314
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1315
73836 93f64ae51fff Remove outdate FAQ content Antoine Pitrou <solipsis@pitrou.net> parents: 73834 diff changeset	1316 Static methods are possible::
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1317
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1318 class C:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1319 @staticmethod
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1320 def static(arg1, arg2, arg3):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1321 # No 'self' parameter!
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1322 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1323
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1324 However, a far more straightforward way to get the effect of a static method is
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1325 via a simple module-level function::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1326
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1327 def getcount():
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1328 return C.count
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1329
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1330 If your code is structured so as to define one class (or tightly related class
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1331 hierarchy) per module, this supplies the desired encapsulation.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1332
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1333
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1334 How can I overload constructors (or methods) in Python?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1335 -------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1336
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1337 This answer actually applies to all methods, but the question usually comes up
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1338 first in the context of constructors.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1339
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1340 In C++ you'd write
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1341
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1342 .. code-block:: c
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1343
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1344 class C {
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1345 C() { cout << "No arguments\n"; }
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1346 C(int i) { cout << "Argument is " << i << "\n"; }
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1347 }
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1348
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1349 In Python you have to write a single constructor that catches all cases using
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1350 default arguments. For example::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1351
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1352 class C:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1353 def __init__(self, i=None):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1354 if i is None:
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1355 print("No arguments")
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1356 else:
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1357 print("Argument is", i)
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1358
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1359 This is not entirely equivalent, but close enough in practice.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1360
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1361 You could also try a variable-length argument list, e.g. ::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1362
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1363 def __init__(self, *args):
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1364 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1365
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1366 The same approach works for all method definitions.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1367
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1368
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1369 I try to use __spam and I get an error about _SomeClassName__spam.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1370 ------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1371
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1372 Variable names with double leading underscores are "mangled" to provide a simple
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1373 but effective way to define class private variables. Any identifier of the form
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1374 ``__spam`` (at least two leading underscores, at most one trailing underscore)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1375 is textually replaced with ``_classname__spam``, where ``classname`` is the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1376 current class name with any leading underscores stripped.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1377
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1378 This doesn't guarantee privacy: an outside user can still deliberately access
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1379 the "_classname__spam" attribute, and private values are visible in the object's
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1380 ``__dict__``. Many Python programmers never bother to use private variable
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1381 names at all.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1382
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1383
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1384 My class defines __del__ but it is not called when I delete the object.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1385 -----------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1386
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1387 There are several possible reasons for this.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1388
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1389 The del statement does not necessarily call :meth:`__del__` -- it simply
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1390 decrements the object's reference count, and if this reaches zero
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1391 :meth:`__del__` is called.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1392
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1393 If your data structures contain circular links (e.g. a tree where each child has
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1394 a parent reference and each parent has a list of children) the reference counts
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1395 will never go back to zero. Once in a while Python runs an algorithm to detect
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1396 such cycles, but the garbage collector might run some time after the last
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1397 reference to your data structure vanishes, so your :meth:`__del__` method may be
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1398 called at an inconvenient and random time. This is inconvenient if you're trying
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1399 to reproduce a problem. Worse, the order in which object's :meth:`__del__`
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1400 methods are executed is arbitrary. You can run :func:`gc.collect` to force a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1401 collection, but there are pathological cases where objects will never be
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1402 collected.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1403
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1404 Despite the cycle collector, it's still a good idea to define an explicit
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1405 ``close()`` method on objects to be called whenever you're done with them. The
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1406 ``close()`` method can then remove attributes that refer to subobjecs. Don't
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1407 call :meth:`__del__` directly -- :meth:`__del__` should call ``close()`` and
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1408 ``close()`` should make sure that it can be called more than once for the same
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1409 object.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1410
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1411 Another way to avoid cyclical references is to use the :mod:`weakref` module,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1412 which allows you to point to objects without incrementing their reference count.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1413 Tree data structures, for instance, should use weak references for their parent
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1414 and sibling references (if they need them!).
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1415
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1416 .. XXX relevant for Python 3?
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1417
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1418 If the object has ever been a local variable in a function that caught an
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1419 expression in an except clause, chances are that a reference to the object
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1420 still exists in that function's stack frame as contained in the stack trace.
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1421 Normally, calling :func:`sys.exc_clear` will take care of this by clearing
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1422 the last recorded exception.
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1423
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1424 Finally, if your :meth:`__del__` method raises an exception, a warning message
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1425 is printed to :data:`sys.stderr`.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1426
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1427
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1428 How do I get a list of all instances of a given class?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1429 ------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1430
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1431 Python does not keep track of all instances of a class (or of a built-in type).
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1432 You can program the class's constructor to keep track of all instances by
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1433 keeping a list of weak references to each instance.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1434
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1435
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1436 Modules
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1437 =======
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1438
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1439 How do I create a .pyc file?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1440 ----------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1441
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1442 When a module is imported for the first time (or when the source is more recent
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1443 than the current compiled file) a ``.pyc`` file containing the compiled code
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1444 should be created in the same directory as the ``.py`` file.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1445
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1446 One reason that a ``.pyc`` file may not be created is permissions problems with
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1447 the directory. This can happen, for example, if you develop as one user but run
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1448 as another, such as if you are testing with a web server. Creation of a .pyc
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1449 file is automatic if you're importing a module and Python has the ability
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1450 (permissions, free space, etc...) to write the compiled module back to the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1451 directory.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1452
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1453 Running Python on a top level script is not considered an import and no ``.pyc``
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1454 will be created. For example, if you have a top-level module ``abc.py`` that
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1455 imports another module ``xyz.py``, when you run abc, ``xyz.pyc`` will be created
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1456 since xyz is imported, but no ``abc.pyc`` file will be created since ``abc.py``
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1457 isn't being imported.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1458
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1459 If you need to create abc.pyc -- that is, to create a .pyc file for a module
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1460 that is not imported -- you can, using the :mod:`py_compile` and
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1461 :mod:`compileall` modules.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1462
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1463 The :mod:`py_compile` module can manually compile any module. One way is to use
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1464 the ``compile()`` function in that module interactively::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1465
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1466 >>> import py_compile
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1467 >>> py_compile.compile('abc.py')
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1468
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1469 This will write the ``.pyc`` to the same location as ``abc.py`` (or you can
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1470 override that with the optional parameter ``cfile``).
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1471
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1472 You can also automatically compile all files in a directory or directories using
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1473 the :mod:`compileall` module. You can do it from the shell prompt by running
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1474 ``compileall.py`` and providing the path of a directory containing Python files
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1475 to compile::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1476
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1477 python -m compileall .
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1478
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1479
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1480 How do I find the current module name?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1481 --------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1482
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1483 A module can find out its own module name by looking at the predefined global
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1484 variable ``__name__``. If this has the value ``'__main__'``, the program is
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1485 running as a script. Many modules that are usually used by importing them also
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1486 provide a command-line interface or a self-test, and only execute this code
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1487 after checking ``__name__``::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1488
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1489 def main():
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1490 print('Running test...')
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1491 ...
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1492
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1493 if __name__ == '__main__':
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1494 main()
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1495
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1496
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1497 How can I have modules that mutually import each other?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1498 -------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1499
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1500 Suppose you have the following modules:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1501
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1502 foo.py::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1503
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1504 from bar import bar_var
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1505 foo_var = 1
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1506
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1507 bar.py::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1508
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1509 from foo import foo_var
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1510 bar_var = 2
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1511
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1512 The problem is that the interpreter will perform the following steps:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1513
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1514 * main imports foo
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1515 * Empty globals for foo are created
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1516 * foo is compiled and starts executing
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1517 * foo imports bar
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1518 * Empty globals for bar are created
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1519 * bar is compiled and starts executing
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1520 * bar imports foo (which is a no-op since there already is a module named foo)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1521 * bar.foo_var = foo.foo_var
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1522
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1523 The last step fails, because Python isn't done with interpreting ``foo`` yet and
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1524 the global symbol dictionary for ``foo`` is still empty.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1525
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1526 The same thing happens when you use ``import foo``, and then try to access
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1527 ``foo.foo_var`` in global code.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1528
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1529 There are (at least) three possible workarounds for this problem.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1530
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1531 Guido van Rossum recommends avoiding all uses of ``from <module> import ...``,
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1532 and placing all code inside functions. Initializations of global variables and
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1533 class variables should use constants or built-in functions only. This means
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1534 everything from an imported module is referenced as ``<module>.<name>``.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1535
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1536 Jim Roskind suggests performing steps in the following order in each module:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1537
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1538 * exports (globals, functions, and classes that don't need imported base
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1539 classes)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1540 * ``import`` statements
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1541 * active code (including globals that are initialized from imported values).
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1542
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1543 van Rossum doesn't like this approach much because the imports appear in a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1544 strange place, but it does work.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1545
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1546 Matthias Urlichs recommends restructuring your code so that the recursive import
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1547 is not necessary in the first place.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1548
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1549 These solutions are not mutually exclusive.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1550
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1551
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1552 __import__('x.y.z') returns <module 'x'>; how do I get z?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1553 ---------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1554
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1555 Try::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1556
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1557 __import__('x.y.z').y.z
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1558
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1559 For more realistic situations, you may have to do something like ::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1560
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1561 m = __import__(s)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1562 for i in s.split(".")[1:]:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1563 m = getattr(m, i)
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1564
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1565 See :mod:`importlib` for a convenience function called
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1566 :func:`~importlib.import_module`.
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1567
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1568
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1569
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1570 When I edit an imported module and reimport it, the changes don't show up. Why does this happen?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1571 -------------------------------------------------------------------------------------------------
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1572
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1573 For reasons of efficiency as well as consistency, Python only reads the module
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1574 file on the first time a module is imported. If it didn't, in a program
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1575 consisting of many modules where each one imports the same basic module, the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1576 basic module would be parsed and re-parsed many times. To force rereading of a
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1577 changed module, do this::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1578
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1579 import imp
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1580 import modname
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1581 imp.reload(modname)
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1582
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1583 Warning: this technique is not 100% fool-proof. In particular, modules
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1584 containing statements like ::
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1585
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1586 from modname import some_objects
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1587
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1588 will continue to work with the old version of the imported objects. If the
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1589 module contains class definitions, existing class instances will not be
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1590 updated to use the new class definition. This can result in the following
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1591 paradoxical behaviour:
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1592
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1593 >>> import imp
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1594 >>> import cls
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1595 >>> c = cls.C() # Create an instance of C
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1596 >>> imp.reload(cls)
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1597 <module 'cls' from 'cls.py'>
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1598 >>> isinstance(c, cls.C) # isinstance is false?!?
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1599 False
cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1600
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1601 The nature of the problem is made clear if you print out the "identity" of the
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1602 class objects:
56890 cef5cb270fdf Merged revisions 75374 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	1603
61797 6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1604 >>> hex(id(c.__class__))
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1605 '0x7352a0'
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1606 >>> hex(id(cls.C))
6ca2e6b3bf31 Merged revisions 76888,76922,81406 via svnmerge from Georg Brandl <georg@python.org> parents: 57244 diff changeset	1607 '0x4198d0'

Mercurial > cpython-lru_cache-weakref

annotate Doc/faq/programming.rst @ 78069:a8aa77458e12 3.2