Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/modules.rst @ 87690:66c1c9f32567 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859
author Radomir Dopieralski <devel@sheep.art.pl>
date Tue, 03 Dec 2013 16:02:48 +0100
parents 824f29de4c9e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
86240
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
186 To speed up loading modules, Python caches the compiled version of each module
86685
5536129fc5f9 Fix markup errors in the docs and amend suspicious ignores.
Georg Brandl <georg@python.org>
parents: 86240
diff changeset
187 in the ``__pycache__`` directory under the name :file:`module.{version}.pyc`,
86240
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
188 where the version encodes the format of the compiled file; it generally contains
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
189 the Python version number. For example, in CPython release 3.3 the compiled
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
190 version of spam.py would be cached as ``__pycache__/spam.cpython-33.pyc``. This
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
191 naming convention allows compiled modules from different releases and different
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
192 versions of Python to coexist.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193
86240
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
194 Python checks the modification date of the source against the compiled version
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
195 to see if it's out of date and needs to be recompiled. This is a completely
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
196 automatic process. Also, the compiled modules are platform-independent, so the
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
197 same library can be shared among systems with different architectures.
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
198
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
199 Python does not check the cache in two circumstances. First, it always
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
200 recompiles and does not store the result for the module that's loaded directly
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
201 from the command line. Second, it does not check the cache if there is no
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
202 source module. To support a non-source (compiled only) distribution, the
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
203 compiled module must be in the source directory, and there must not be a source
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
204 module.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 Some tips for experts:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207
86240
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
208 * You can use the :option:`-O` or :option:`-OO` switches on the Python command
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
209 to reduce the size of a compiled module. The ``-O`` switch removes assert
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
210 statements, the ``-OO`` switch removes both assert statements and __doc__
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
211 strings. Since some programs may rely on having these available, you should
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
212 only use this option if you know what you're doing. "Optimized" modules have
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
213 a .pyo rather than a .pyc suffix and are usually smaller. Future releases may
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
214 change the effects of optimization.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215
86240
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
216 * A program doesn't run any faster when it is read from a ``.pyc`` or ``.pyo``
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
217 file than when it is read from a ``.py`` file; the only thing that's faster
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
218 about ``.pyc`` or ``.pyo`` files is the speed with which they are loaded.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219
86240
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
220 * The module :mod:`compileall` can create .pyc files (or .pyo files when
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
221 :option:`-O` is used) for all modules in a directory.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222
86240
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
223 * There is more detail on this process, including a flow chart of the
6ecef57f57f9 Closes #13915: update tutorial with respect to .pyc files (__pycache__ / PEP 3147).
Georg Brandl <georg@python.org>
parents: 86124
diff changeset
224 decisions, in PEP 3147.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 .. _tut-standardmodules:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 Standard Modules
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 ================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 .. index:: module: sys
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 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
235 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
236 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
237 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
238 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
239 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
240 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
241 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
242 :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
243 ``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
244 prompts::
42604
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 >>> import sys
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 >>> sys.ps1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248 '>>> '
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
249 >>> sys.ps2
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
250 '... '
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
251 >>> sys.ps1 = 'C> '
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
252 C> print('Yuck!')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253 Yuck!
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
254 C>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
255
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
256
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 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
258
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259 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
260 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
261 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
262 :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
263 operations::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 >>> import sys
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266 >>> sys.path.append('/ufs/guido/lib/python')
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 .. _tut-dir:
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 :func:`dir` Function
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
272 ========================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274 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
275 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
276
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 >>> import fibo, sys
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278 >>> dir(fibo)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 ['__name__', 'fib', 'fib2']
80464
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
280 >>> dir(sys) # doctest: +NORMALIZE_WHITESPACE
80466
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
281 ['__displayhook__', '__doc__', '__excepthook__', '__loader__', '__name__',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
282 '__package__', '__stderr__', '__stdin__', '__stdout__',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
283 '_clear_type_cache', '_current_frames', '_debugmallocstats', '_getframe',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
284 '_home', '_mercurial', '_xoptions', 'abiflags', 'api_version', 'argv',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
285 'base_exec_prefix', 'base_prefix', 'builtin_module_names', 'byteorder',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
286 'call_tracing', 'callstats', 'copyright', 'displayhook',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
287 'dont_write_bytecode', 'exc_info', 'excepthook', 'exec_prefix',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
288 'executable', 'exit', 'flags', 'float_info', 'float_repr_style',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
289 'getcheckinterval', 'getdefaultencoding', 'getdlopenflags',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
290 'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
291 'getrefcount', 'getsizeof', 'getswitchinterval', 'gettotalrefcount',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
292 'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
293 'intern', 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
294 'path_hooks', 'path_importer_cache', 'platform', 'prefix', 'ps1',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
295 'setcheckinterval', 'setdlopenflags', 'setprofile', 'setrecursionlimit',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
296 'setswitchinterval', 'settrace', 'stderr', 'stdin', 'stdout',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
297 'thread_info', 'version', 'version_info', 'warnoptions']
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
298
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
299 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
300
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301 >>> a = [1, 2, 3, 4, 5]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 >>> import fibo
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 >>> fib = fibo.fib
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304 >>> dir()
80464
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
305 ['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
306
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
307 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
308
44098
0889daf6d0d9 #1535: rename __builtin__ module to builtins.
Georg Brandl <georg@python.org>
parents: 43737
diff changeset
309 .. index:: module: builtins
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
310
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311 :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
312 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
313 :mod:`builtins`::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
314
44098
0889daf6d0d9 #1535: rename __builtin__ module to builtins.
Georg Brandl <georg@python.org>
parents: 43737
diff changeset
315 >>> import builtins
80464
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
316 >>> dir(builtins) # doctest: +NORMALIZE_WHITESPACE
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
317 ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
80465
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
318 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
319 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
320 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
321 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
322 'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
80464
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
323 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
80465
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
324 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
325 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
326 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
327 'NotImplementedError', 'OSError', 'OverflowError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
328 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
329 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
330 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
331 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
332 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
333 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
334 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
335 '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
336 '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
337 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
338 '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
339 '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
340 '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
341 '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
342 '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
343 '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
344 '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
345 'zip']
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 .. _tut-packages:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 Packages
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350 ========
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
351
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352 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
353 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
354 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
355 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
356 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
357 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
358 each other's module names.
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 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
361 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
362 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
363 :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
364 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
365 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
366 (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
367 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
368 stream of modules to perform these operations. Here's a possible structure for
86038
6684cf7a9aaf Fix wrong Python highlighting in directory hierarchy code block.
Georg Brandl <georg@python.org>
parents: 83486
diff changeset
369 your package (expressed in terms of a hierarchical filesystem):
6684cf7a9aaf Fix wrong Python highlighting in directory hierarchy code block.
Georg Brandl <georg@python.org>
parents: 83486
diff changeset
370
6684cf7a9aaf Fix wrong Python highlighting in directory hierarchy code block.
Georg Brandl <georg@python.org>
parents: 83486
diff changeset
371 .. code-block:: text
42604
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 sound/ Top-level package
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
374 __init__.py Initialize the sound package
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
375 formats/ Subpackage for file format conversions
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
376 __init__.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
377 wavread.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
378 wavwrite.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
379 aiffread.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
380 aiffwrite.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
381 auread.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
382 auwrite.py
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 effects/ Subpackage for sound effects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
385 __init__.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
386 echo.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
387 surround.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
388 reverse.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
389 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 filters/ Subpackage for filters
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
391 __init__.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
392 equalizer.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393 vocoder.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
394 karaoke.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
395 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
396
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
397 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
398 ``sys.path`` looking for the package subdirectory.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
399
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
400 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
401 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
402 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
403 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
404 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
405 set the ``__all__`` variable, described later.
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 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
408 example::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
409
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
410 import sound.effects.echo
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
411
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
412 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
413 its full name. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
414
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
415 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
416
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
417 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
418
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
419 from sound.effects import echo
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 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
422 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
423
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
424 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
425
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
426 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
427
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
428 from sound.effects.echo import echofilter
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 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
431 :func:`echofilter` directly available::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
432
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
433 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
434
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
435 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
436 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
437 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
438 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
439 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
440 exception is raised.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
441
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
442 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
443 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
444 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
445 item.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
446
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
447
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
448 .. _tut-pkg-import-star:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
449
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
450 Importing \* From a Package
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
451 ---------------------------
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 .. index:: single: __all__
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
454
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
455 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
456 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
457 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
458 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
459 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
460
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
461 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
462 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
463 :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
464 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
465 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
466 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
467 support it, if they don't see a use for importing \* from their package. For
86124
b8f6a0357fc3 Fix typo in example file name. Found by John Bokma on docs@.
Georg Brandl <georg@python.org>
parents: 86038
diff changeset
468 example, the file :file:`sound/effects/__init__.py` could contain the following
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
469 code::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
470
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
471 __all__ = ["echo", "surround", "reverse"]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
472
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
473 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
474 named submodules of the :mod:`sound` package.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
475
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
476 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
477 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
478 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
479 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
480 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
481 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
482 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
483 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
484
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
485 import sound.effects.echo
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
486 import sound.effects.surround
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
487 from sound.effects import *
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
488
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
489 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
490 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
491 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
492 ``__all__`` is defined.)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
493
56368
c9bd62efe6ce Merged revisions 75231 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 55580
diff changeset
494 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
495 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
496 production code.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
497
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
498 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
499 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
500 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
501 packages.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
502
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
503
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
504 Intra-package References
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
505 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
506
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
507 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
508 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
509 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
510 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
511 sound.effects import echo``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
512
46963
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup,
Georg Brandl <georg@python.org>
parents: 44396
diff changeset
513 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
514 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
515 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
516 module for example, you might use::
42604
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 from . import echo
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
519 from .. import formats
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
520 from ..filters import equalizer
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
521
46963
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup,
Georg Brandl <georg@python.org>
parents: 44396
diff changeset
522 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
523 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
524 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
525
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
526
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
527 Packages in Multiple Directories
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
530 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
531 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
532 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
533 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
534 subpackages contained in the package.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
535
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
536 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
537 modules found in a package.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
538
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 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
541
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
542 .. [#] 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
543 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
544 the module's global symbol table.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
545