cpython-lru_cache-weakref: Doc/tutorial/modules.rst annotate

annotate Doc/tutorial/modules.rst @ 84007:dbfbdf2b5c19 3.3

Fix #17967: For ftp urls CWD to target instead of hopping to each directory towards target. This fixes a bug where target is accessible, but parent directories are restricted.

author	Senthil Kumaran <senthil@uthcode.com>
date	Sat, 01 Jun 2013 08:27:06 -0700
parents	9df9931fae96
children	6684cf7a9aaf dac847938326

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. _tut-modules:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 *******
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 Modules
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 *******
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 If you quit from the Python interpreter and enter it again, the definitions you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 have made (functions and variables) are lost. Therefore, if you want to write a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 somewhat longer program, you are better off using a text editor to prepare the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 input for the interpreter and running it with that file as input instead. This
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 is known as creating a script. As your program gets longer, you may want to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 split it into several files for easier maintenance. You may also want to use a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 handy function that you've written in several programs without copying its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 definition into each program.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 To support this, Python has a way to put definitions in a file and use them in a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 script or in an interactive instance of the interpreter. Such a file is called a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 module; definitions from a module can be imported into other modules or into
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 the main module (the collection of variables that you have access to in a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 script executed at the top level and in calculator mode).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 A module is a file containing Python definitions and statements. The file name
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 is the module name with the suffix :file:`.py` appended. Within a module, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 module's name (as a string) is available as the value of the global variable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 ``__name__``. For instance, use your favorite text editor to create a file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 called :file:`fibo.py` in the current directory with the following contents::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 # Fibonacci numbers module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 def fib(n): # write Fibonacci series up to n
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 a, b = 0, 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 while b < n:
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	33 print(b, end=' ')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 a, b = b, a+b
48655 1635891b18e8 #3503: fix print statements in 3k doc. Georg Brandl <georg@python.org> parents: 47067 diff changeset	35 print()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 def fib2(n): # return Fibonacci series up to n
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 result = []
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 a, b = 0, 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 while b < n:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 result.append(b)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 a, b = b, a+b
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 return result
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 Now enter the Python interpreter and import this module with the following
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 command::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 >>> import fibo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 This does not enter the names of the functions defined in ``fibo`` directly in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 the current symbol table; it only enters the module name ``fibo`` there. Using
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 the module name you can access the functions::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 >>> fibo.fib(1000)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 >>> fibo.fib2(100)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 >>> fibo.__name__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 'fibo'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 If you intend to use a function often you can assign it to a local name::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 >>> fib = fibo.fib
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 >>> fib(500)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 1 1 2 3 5 8 13 21 34 55 89 144 233 377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 .. _tut-moremodules:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 More on Modules
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 ===============
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 A module can contain executable statements as well as function definitions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 These statements are intended to initialize the module. They are executed only
83486 9df9931fae96 #15575: Clarify tutorial description of when modules are executed. R David Murray <rdmurray@bitdance.com> parents: 83351 diff changeset	75 the first time the module name is encountered in an import statement. [#]_
9df9931fae96 #15575: Clarify tutorial description of when modules are executed. R David Murray <rdmurray@bitdance.com> parents: 83351 diff changeset	76 (They are also run if the file is executed as a script.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 Each module has its own private symbol table, which is used as the global symbol
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 table by all functions defined in the module. Thus, the author of a module can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 use global variables in the module without worrying about accidental clashes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 with a user's global variables. On the other hand, if you know what you are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 doing you can touch a module's global variables with the same notation used to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 refer to its functions, ``modname.itemname``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 Modules can import other modules. It is customary but not required to place all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 :keyword:`import` statements at the beginning of a module (or script, for that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 matter). The imported module names are placed in the importing module's global
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 symbol table.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 There is a variant of the :keyword:`import` statement that imports names from a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 module directly into the importing module's symbol table. For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 >>> from fibo import fib, fib2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 >>> fib(500)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 1 1 2 3 5 8 13 21 34 55 89 144 233 377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 This does not introduce the module name from which the imports are taken in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 local symbol table (so in the example, ``fibo`` is not defined).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 There is even a variant to import all names that a module defines::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 >>> from fibo import *
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 >>> fib(500)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 1 1 2 3 5 8 13 21 34 55 89 144 233 377
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 This imports all names except those beginning with an underscore (``_``).
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50540 diff changeset	107 In most cases Python programmers do not use this facility since it introduces
93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 50540 diff changeset	108 an unknown set of names into the interpreter, possibly hiding some things
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	109 you have already defined.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110
56368 c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	111 Note that in general the practice of importing ``*`` from a module or package is
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	112 frowned upon, since it often causes poorly readable code. However, it is okay to
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	113 use it to save typing in interactive sessions.
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	114
47063 081c15806e28 Merged revisions 62914-62916,62918-62919,62921-62922,62924-62942,62944-62945,62947-62949 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	115 .. note::
081c15806e28 Merged revisions 62914-62916,62918-62919,62921-62922,62924-62942,62944-62945,62947-62949 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	116
081c15806e28 Merged revisions 62914-62916,62918-62919,62921-62922,62924-62942,62944-62945,62947-62949 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	117 For efficiency reasons, each module is only imported once per interpreter
081c15806e28 Merged revisions 62914-62916,62918-62919,62921-62922,62924-62942,62944-62945,62947-62949 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	118 session. Therefore, if you change your modules, you must restart the
081c15806e28 Merged revisions 62914-62916,62918-62919,62921-62922,62924-62942,62944-62945,62947-62949 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	119 interpreter -- or, if it's just one module you want to test interactively,
50540 4229a4b14f1d Merged revisions 67653,67655,67682-67683,67724,67755,67780-67783,67786,67789,67841,67843,67865,67881,67884,67925,67929,67931 via svnmerge from Georg Brandl <georg@python.org> parents: 48655 diff changeset	120 use :func:`imp.reload`, e.g. ``import imp; imp.reload(modulename)``.
47063 081c15806e28 Merged revisions 62914-62916,62918-62919,62921-62922,62924-62942,62944-62945,62947-62949 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	121
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 .. _tut-modulesasscripts:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 Executing modules as scripts
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 ----------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 When you run a Python module with ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 python fibo.py <arguments>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 the code in the module will be executed, just as if you imported it, but with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 the ``__name__`` set to ``"__main__"``. That means that by adding this code at
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 the end of your module::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 if __name__ == "__main__":
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 import sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 fib(int(sys.argv[1]))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 you can make the file usable as a script as well as an importable module,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 because the code that parses the command line only runs if the module is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 executed as the "main" file::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 $ python fibo.py 50
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 1 1 2 3 5 8 13 21 34
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 If the module is imported, the code is not run::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 >>> import fibo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 >>>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 This is often used either to provide a convenient user interface to a module, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 for testing purposes (running the module as a script executes a test suite).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 .. _tut-searchpath:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 The Module Search Path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 ----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 .. index:: triple: module; search; path
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
74522 6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	163 When a module named :mod:`spam` is imported, the interpreter first searches for
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	164 a built-in module with that name. If not found, it then searches for a file
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	165 named :file:`spam.py` in a list of directories given by the variable
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	166 :data:`sys.path`. :data:`sys.path` is initialized from these locations:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167
74522 6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	168 * the directory containing the input script (or the current directory).
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	169 * :envvar:`PYTHONPATH` (a list of directory names, with the same syntax as the
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	170 shell variable :envvar:`PATH`).
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	171 * the installation-dependent default.
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	172
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	173 After initialization, Python programs can modify :data:`sys.path`. The
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	174 directory containing the script being run is placed at the beginning of the
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	175 search path, ahead of the standard library path. This means that scripts in that
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	176 directory will be loaded instead of modules of the same name in the library
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	177 directory. This is an error unless the replacement is intended. See section
6d663db63705 Issue #11948: clarify modules search path Sandro Tosi <sandro.tosi@gmail.com> parents: 70903 diff changeset	178 :ref:`tut-standardmodules` for more information.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	180 .. %
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	181 Do we need stuff on zip files etc. ? DUBOIS
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 "Compiled" Python files
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 As an important speed-up of the start-up time for short programs that use a lot
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 of standard modules, if a file called :file:`spam.pyc` exists in the directory
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 where :file:`spam.py` is found, this is assumed to contain an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 already-"byte-compiled" version of the module :mod:`spam`. The modification time
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 of the version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 :file:`spam.pyc`, and the :file:`.pyc` file is ignored if these don't match.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 Normally, you don't need to do anything to create the :file:`spam.pyc` file.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 Whenever :file:`spam.py` is successfully compiled, an attempt is made to write
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 the compiled version to :file:`spam.pyc`. It is not an error if this attempt
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 fails; if for any reason the file is not written completely, the resulting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 :file:`spam.pyc` file will be recognized as invalid and thus ignored later. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 contents of the :file:`spam.pyc` file are platform independent, so a Python
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 module directory can be shared by machines of different architectures.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 Some tips for experts:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 * When the Python interpreter is invoked with the :option:`-O` flag, optimized
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 code is generated and stored in :file:`.pyo` files. The optimizer currently
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 doesn't help much; it only removes :keyword:`assert` statements. When
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43201 diff changeset	206 :option:`-O` is used, all :term:`bytecode` is optimized; ``.pyc`` files are
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43201 diff changeset	207 ignored and ``.py`` files are compiled to optimized bytecode.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 * Passing two :option:`-O` flags to the Python interpreter (:option:`-OO`) will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 cause the bytecode compiler to perform optimizations that could in some rare
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 cases result in malfunctioning programs. Currently only ``__doc__`` strings are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 removed from the bytecode, resulting in more compact :file:`.pyo` files. Since
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 some programs may rely on having these available, you should only use this
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 option if you know what you're doing.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 * A program doesn't run any faster when it is read from a :file:`.pyc` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 :file:`.pyo` file than when it is read from a :file:`.py` file; the only thing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 that's faster about :file:`.pyc` or :file:`.pyo` files is the speed with which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 they are loaded.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 * When a script is run by giving its name on the command line, the bytecode for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 the script is never written to a :file:`.pyc` or :file:`.pyo` file. Thus, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 startup time of a script may be reduced by moving most of its code to a module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 and having a small bootstrap script that imports that module. It is also
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 possible to name a :file:`.pyc` or :file:`.pyo` file directly on the command
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 line.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 * It is possible to have a file called :file:`spam.pyc` (or :file:`spam.pyo`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 when :option:`-O` is used) without a file :file:`spam.py` for the same module.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 This can be used to distribute a library of Python code in a form that is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 moderately hard to reverse engineer.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 .. index:: module: compileall
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 * The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 files when :option:`-O` is used) for all modules in a directory.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 .. _tut-standardmodules:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 Standard Modules
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 ================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 .. index:: module: sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 Python comes with a library of standard modules, described in a separate
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 document, the Python Library Reference ("Library Reference" hereafter). Some
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 modules are built into the interpreter; these provide access to operations that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 are not part of the core of the language but are nevertheless built in, either
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 for efficiency or to provide access to operating system primitives such as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 system calls. The set of such modules is a configuration option which also
78413 66b53f555704 add missing period; thanks to Gaston Fiore from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74522 diff changeset	252 depends on the underlying platform. For example, the :mod:`winreg` module is only
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 provided on Windows systems. One particular module deserves some attention:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 :mod:`sys`, which is built into every Python interpreter. The variables
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 ``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44098 diff changeset	256 prompts::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 >>> import sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 >>> sys.ps1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 '>>> '
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 >>> sys.ps2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 '... '
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 >>> sys.ps1 = 'C> '
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	264 C> print('Yuck!')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 Yuck!
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 C>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 These two variables are only defined if the interpreter is in interactive mode.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271 The variable ``sys.path`` is a list of strings that determines the interpreter's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 search path for modules. It is initialized to a default path taken from the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 environment variable :envvar:`PYTHONPATH`, or from a built-in default if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 :envvar:`PYTHONPATH` is not set. You can modify it using standard list
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 operations::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 >>> import sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 >>> sys.path.append('/ufs/guido/lib/python')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 .. _tut-dir:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 The :func:`dir` Function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 ========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 The built-in function :func:`dir` is used to find out which names a module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 defines. It returns a sorted list of strings::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 >>> import fibo, sys
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 >>> dir(fibo)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 ['__name__', 'fib', 'fib2']
80464 120757b34806 Update section about dir() in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 78413 diff changeset	292 >>> dir(sys) # doctest: +NORMALIZE_WHITESPACE
80465 96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	293 ['__displayhook__', '__doc__', '__egginsert', '__excepthook__',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	294 '__loader__', '__name__', '__package__', '__plen', '__stderr__',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	295 '__stdin__', '__stdout__', '_clear_type_cache', '_current_frames',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	296 '_debugmallocstats', '_getframe', '_home', '_mercurial', '_xoptions',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	297 'abiflags', 'api_version', 'argv', 'base_exec_prefix', 'base_prefix',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	298 'builtin_module_names', 'byteorder', 'call_tracing', 'callstats',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	299 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_info',
80464 120757b34806 Update section about dir() in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 78413 diff changeset	300 'excepthook', 'exec_prefix', 'executable', 'exit', 'flags', 'float_info',
120757b34806 Update section about dir() in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 78413 diff changeset	301 'float_repr_style', 'getcheckinterval', 'getdefaultencoding',
120757b34806 Update section about dir() in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 78413 diff changeset	302 'getdlopenflags', 'getfilesystemencoding', 'getobjects', 'getprofile',
120757b34806 Update section about dir() in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 78413 diff changeset	303 'getrecursionlimit', 'getrefcount', 'getsizeof', 'getswitchinterval',
80465 96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	304 'gettotalrefcount', 'gettrace', 'hash_info', 'hexversion',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	305 'implementation', 'int_info', 'intern', 'maxsize', 'maxunicode',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	306 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	307 'platform', 'prefix', 'ps1', 'setcheckinterval', 'setdlopenflags',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	308 'setprofile', 'setrecursionlimit', 'setswitchinterval', 'settrace',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	309 'stderr', 'stdin', 'stdout', 'thread_info', 'version', 'version_info',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	310 'warnoptions']
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 Without arguments, :func:`dir` lists the names you have defined currently::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 >>> a = [1, 2, 3, 4, 5]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 >>> import fibo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 >>> fib = fibo.fib
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 >>> dir()
80464 120757b34806 Update section about dir() in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 78413 diff changeset	318 ['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 Note that it lists all types of names: variables, modules, functions, etc.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
44098 0889daf6d0d9 #1535: rename __builtin__ module to builtins. Georg Brandl <georg@python.org> parents: 43737 diff changeset	322 .. index:: module: builtins
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 :func:`dir` does not list the names of built-in functions and variables. If you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 want a list of those, they are defined in the standard module
44098 0889daf6d0d9 #1535: rename __builtin__ module to builtins. Georg Brandl <georg@python.org> parents: 43737 diff changeset	326 :mod:`builtins`::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
44098 0889daf6d0d9 #1535: rename __builtin__ module to builtins. Georg Brandl <georg@python.org> parents: 43737 diff changeset	328 >>> import builtins
80464 120757b34806 Update section about dir() in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 78413 diff changeset	329 >>> dir(builtins) # doctest: +NORMALIZE_WHITESPACE
120757b34806 Update section about dir() in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 78413 diff changeset	330 ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
80465 96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	331 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	332 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	333 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	334 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	335 'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
80464 120757b34806 Update section about dir() in the tutorial. Ezio Melotti <ezio.melotti@gmail.com> parents: 78413 diff changeset	336 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
80465 96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	337 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	338 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	339 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	340 'NotImplementedError', 'OSError', 'OverflowError',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	341 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	342 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	343 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	344 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	345 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	346 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	347 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	348 '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	349 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	350 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	351 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	352 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	353 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	354 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	355 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	356 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	357 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',
96756204f125 Merge updates about dir() with 3.2. Ezio Melotti <ezio.melotti@gmail.com> parents: 80464 diff changeset	358 'zip']
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 .. _tut-packages:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 Packages
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 ========
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 Packages are a way of structuring Python's module namespace by using "dotted
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 module names". For example, the module name :mod:`A.B` designates a submodule
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 named ``B`` in a package named ``A``. Just like the use of modules saves the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 authors of different modules from having to worry about each other's global
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369 variable names, the use of dotted module names saves the authors of multi-module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370 packages like NumPy or the Python Imaging Library from having to worry about
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 each other's module names.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 Suppose you want to design a collection of modules (a "package") for the uniform
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 handling of sound files and sound data. There are many different sound file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 formats (usually recognized by their extension, for example: :file:`.wav`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 :file:`.aiff`, :file:`.au`), so you may need to create and maintain a growing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377 collection of modules for the conversion between the various file formats.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 There are also many different operations you might want to perform on sound data
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379 (such as mixing, adding echo, applying an equalizer function, creating an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 artificial stereo effect), so in addition you will be writing a never-ending
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 stream of modules to perform these operations. Here's a possible structure for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 your package (expressed in terms of a hierarchical filesystem)::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 sound/ Top-level package
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 __init__.py Initialize the sound package
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 formats/ Subpackage for file format conversions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387 __init__.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 wavread.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 wavwrite.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390 aiffread.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391 aiffwrite.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 auread.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393 auwrite.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 effects/ Subpackage for sound effects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 __init__.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 echo.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 surround.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 reverse.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 filters/ Subpackage for filters
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 __init__.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 equalizer.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 vocoder.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 karaoke.py
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 When importing the package, Python searches through the directories on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 ``sys.path`` looking for the package subdirectory.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 The :file:`__init__.py` files are required to make Python treat the directories
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 as containing packages; this is done to prevent directories with a common name,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 such as ``string``, from unintentionally hiding valid modules that occur later
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 on the module search path. In the simplest case, :file:`__init__.py` can just be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 an empty file, but it can also execute initialization code for the package or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 set the ``__all__`` variable, described later.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 Users of the package can import individual modules from the package, for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 import sound.effects.echo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 This loads the submodule :mod:`sound.effects.echo`. It must be referenced with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424 its full name. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 An alternative way of importing the submodule is::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 from sound.effects import echo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 This also loads the submodule :mod:`echo`, and makes it available without its
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 package prefix, so it can be used as follows::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 echo.echofilter(input, output, delay=0.7, atten=4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 Yet another variation is to import the desired function or variable directly::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 from sound.effects.echo import echofilter
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 Again, this loads the submodule :mod:`echo`, but this makes its function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 :func:`echofilter` directly available::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 echofilter(input, output, delay=0.7, atten=4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 Note that when using ``from package import item``, the item can be either a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447 submodule (or subpackage) of the package, or some other name defined in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 package, like a function, class or variable. The ``import`` statement first
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449 tests whether the item is defined in the package; if not, it assumes it is a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 module and attempts to load it. If it fails to find it, an :exc:`ImportError`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 exception is raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453 Contrarily, when using syntax like ``import item.subitem.subsubitem``, each item
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 except for the last must be a package; the last item can be a module or a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 package but can't be a class or function or variable defined in the previous
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 item.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 .. _tut-pkg-import-star:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 Importing \* From a Package
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 ---------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464 .. index:: single: __all__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 Now what happens when the user writes ``from sound.effects import *``? Ideally,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 one would hope that this somehow goes out to the filesystem, finds which
56368 c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	468 submodules are present in the package, and imports them all. This could take a
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	469 long time and importing sub-modules might have unwanted side-effects that should
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	470 only happen when the sub-module is explicitly imported.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472 The only solution is for the package author to provide an explicit index of the
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51250 diff changeset	473 package. The :keyword:`import` statement uses the following convention: if a package's
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 :file:`__init__.py` code defines a list named ``__all__``, it is taken to be the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 list of module names that should be imported when ``from package import *`` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476 encountered. It is up to the package author to keep this list up-to-date when a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 new version of the package is released. Package authors may also decide not to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 support it, if they don't see a use for importing \* from their package. For
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 example, the file :file:`sounds/effects/__init__.py` could contain the following
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 code::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 __all__ = ["echo", "surround", "reverse"]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 This would mean that ``from sound.effects import *`` would import the three
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 named submodules of the :mod:`sound` package.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 If ``__all__`` is not defined, the statement ``from sound.effects import *``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488 does not import all submodules from the package :mod:`sound.effects` into the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 current namespace; it only ensures that the package :mod:`sound.effects` has
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 been imported (possibly running any initialization code in :file:`__init__.py`)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 and then imports whatever names are defined in the package. This includes any
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492 names defined (and submodules explicitly loaded) by :file:`__init__.py`. It
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 also includes any submodules of the package that were explicitly loaded by
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51250 diff changeset	494 previous :keyword:`import` statements. Consider this code::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 import sound.effects.echo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497 import sound.effects.surround
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 from sound.effects import *
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51250 diff changeset	500 In this example, the :mod:`echo` and :mod:`surround` modules are imported in the
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51250 diff changeset	501 current namespace because they are defined in the :mod:`sound.effects` package
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51250 diff changeset	502 when the ``from...import`` statement is executed. (This also works when
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 51250 diff changeset	503 ``__all__`` is defined.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504
56368 c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	505 Although certain modules are designed to export only names that follow certain
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	506 patterns when you use ``import *``, it is still considered bad practise in
c9bd62efe6ce Merged revisions 75231 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55580 diff changeset	507 production code.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 Remember, there is nothing wrong with using ``from Package import
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 specific_submodule``! In fact, this is the recommended notation unless the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 importing module needs to use submodules with the same name from different
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 packages.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 Intra-package References
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 When packages are structured into subpackages (as with the :mod:`sound` package
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519 in the example), you can use absolute imports to refer to submodules of siblings
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 packages. For example, if the module :mod:`sound.filters.vocoder` needs to use
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521 the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522 sound.effects import echo``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523
46963 03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 44396 diff changeset	524 You can also write relative imports, with the ``from module import name`` form
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 44396 diff changeset	525 of import statement. These imports use leading dots to indicate the current and
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 44396 diff changeset	526 parent packages involved in the relative import. From the :mod:`surround`
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 44396 diff changeset	527 module for example, you might use::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529 from . import echo
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530 from .. import formats
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531 from ..filters import equalizer
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532
46963 03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 44396 diff changeset	533 Note that relative imports are based on the name of the current module. Since
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 44396 diff changeset	534 the name of the main module is always ``"__main__"``, modules intended for use
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup, Georg Brandl <georg@python.org> parents: 44396 diff changeset	535 as the main module of a Python application must always use absolute imports.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 Packages in Multiple Directories
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 --------------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541 Packages support one more special attribute, :attr:`__path__`. This is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 initialized to be a list containing the name of the directory holding the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 package's :file:`__init__.py` before the code in that file is executed. This
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 variable can be modified; doing so affects future searches for modules and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 subpackages contained in the package.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 While this feature is not often needed, it can be used to extend the set of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 modules found in a package.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 .. [#] In fact function definitions are also 'statements' that are 'executed'; the
83351 2dbdd0f1af74 Clarify that the function definition creates the function and the binding in the module globals. Georg Brandl <georg@python.org> parents: 80465 diff changeset	554 execution of a module-level function definition enters the function name in
2dbdd0f1af74 Clarify that the function definition creates the function and the binding in the module globals. Georg Brandl <georg@python.org> parents: 80465 diff changeset	555 the module's global symbol table.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/modules.rst @ 84007:dbfbdf2b5c19 3.3