Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/modules.rst @ 81343:3a7cd8efc19f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
#16852: merge with 3.3.
author Ezio Melotti <ezio.melotti@gmail.com>
date Thu, 10 Jan 2013 03:29:45 +0200
parents 18c47f9d6303
children 8fe5a98647a0
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 the *first* time the module is imported somewhere. [#]_
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 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
78 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
79 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
80 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
81 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
82 refer to its functions, ``modname.itemname``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 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
85 :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
86 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
87 symbol table.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 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
90 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
91
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 >>> from fibo import fib, fib2
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 >>> fib(500)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 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
95
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 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
97 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
98
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 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
100
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 >>> from fibo import *
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 >>> fib(500)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 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
104
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 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
106 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
107 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
108 you have already defined.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
56368
c9bd62efe6ce Merged revisions 75231 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 55580
diff changeset
110 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
111 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
112 use it to save typing in interactive sessions.
c9bd62efe6ce Merged revisions 75231 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 55580
diff changeset
113
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
114 .. 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
115
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 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
117 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
118 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
119 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
120
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 .. _tut-modulesasscripts:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 Executing modules as scripts
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 ----------------------------
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 When you run a Python module with ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 python fibo.py <arguments>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 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
132 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
133 the end of your module::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 if __name__ == "__main__":
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 import sys
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 fib(int(sys.argv[1]))
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 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
140 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
141 executed as the "main" file::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 $ python fibo.py 50
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 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
145
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 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
147
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 >>> import fibo
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 >>>
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 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
152 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
153
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 .. _tut-searchpath:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 The Module Search Path
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 ----------------------
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 .. index:: triple: module; search; path
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161
74522
6d663db63705 Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70903
diff changeset
162 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
163 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
164 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
165 :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
166
74522
6d663db63705 Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70903
diff changeset
167 * 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
168 * :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
169 shell variable :envvar:`PATH`).
6d663db63705 Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70903
diff changeset
170 * the installation-dependent default.
6d663db63705 Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70903
diff changeset
171
6d663db63705 Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70903
diff changeset
172 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
173 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
174 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
175 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
176 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
177 :ref:`tut-standardmodules` for more information.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
179 .. %
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
180 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
181
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 "Compiled" Python files
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 -----------------------
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 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
186 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
187 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
188 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
189 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
190 :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
191
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 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
193 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
194 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
195 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
196 :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
197 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
198 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
199
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 Some tips for experts:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 * 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
203 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
204 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
205 :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
206 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
207
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 * 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
209 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
210 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
211 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
212 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
213 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
214
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 * 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
216 :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
217 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
218 they are loaded.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 * 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
221 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
222 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
223 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
224 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
225 line.
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 * 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
228 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
229 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
230 moderately hard to reverse engineer.
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: compileall
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 * 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
235 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
236
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 .. _tut-standardmodules:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 Standard Modules
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 ================
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 .. index:: module: sys
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 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
246 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
247 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
248 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
249 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
250 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
251 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
252 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
253 :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
254 ``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
255 prompts::
42604
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 >>> import sys
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
258 >>> sys.ps1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259 '>>> '
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
260 >>> sys.ps2
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261 '... '
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262 >>> sys.ps1 = 'C> '
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
263 C> print('Yuck!')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264 Yuck!
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 C>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266
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 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
269
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 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
271 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
272 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
273 :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
274 operations::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 >>> import sys
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 >>> sys.path.append('/ufs/guido/lib/python')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278
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 .. _tut-dir:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
281
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 The :func:`dir` Function
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
283 ========================
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 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
286 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
287
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
288 >>> import fibo, sys
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 >>> dir(fibo)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
290 ['__name__', 'fib', 'fib2']
80464
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
291 >>> dir(sys) # doctest: +NORMALIZE_WHITESPACE
80466
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
292 ['__displayhook__', '__doc__', '__excepthook__', '__loader__', '__name__',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
293 '__package__', '__stderr__', '__stdin__', '__stdout__',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
294 '_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
295 '_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
296 '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
297 'call_tracing', 'callstats', 'copyright', 'displayhook',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
298 '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
299 '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
300 'getcheckinterval', 'getdefaultencoding', 'getdlopenflags',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
301 'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
302 'getrefcount', 'getsizeof', 'getswitchinterval', 'gettotalrefcount',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
303 '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
304 '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
305 '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
306 'setcheckinterval', 'setdlopenflags', 'setprofile', 'setrecursionlimit',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
307 'setswitchinterval', 'settrace', 'stderr', 'stdin', 'stdout',
18c47f9d6303 Merge updates about dir() with 3.3.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80465
diff changeset
308 'thread_info', 'version', 'version_info', 'warnoptions']
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
309
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
310 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
311
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 >>> a = [1, 2, 3, 4, 5]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
313 >>> import fibo
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
314 >>> fib = fibo.fib
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
315 >>> dir()
80464
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
316 ['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
317
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
318 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
319
44098
0889daf6d0d9 #1535: rename __builtin__ module to builtins.
Georg Brandl <georg@python.org>
parents: 43737
diff changeset
320 .. index:: module: builtins
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
321
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
322 :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
323 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
324 :mod:`builtins`::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
325
44098
0889daf6d0d9 #1535: rename __builtin__ module to builtins.
Georg Brandl <georg@python.org>
parents: 43737
diff changeset
326 >>> import builtins
80464
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
327 >>> dir(builtins) # doctest: +NORMALIZE_WHITESPACE
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
328 ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
80465
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
329 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
330 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
331 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
332 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
333 'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
80464
120757b34806 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78413
diff changeset
334 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
80465
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
335 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
336 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
337 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
338 'NotImplementedError', 'OSError', 'OverflowError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
339 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
340 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
341 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
342 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
343 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
344 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
345 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
346 '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
347 '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
348 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
96756204f125 Merge updates about dir() with 3.2.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 80464
diff changeset
349 '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
350 '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
351 '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
352 '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
353 '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
354 '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
355 '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
356 'zip']
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
357
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358 .. _tut-packages:
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 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
363 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
364 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
365 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
366 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
367 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
368 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
369 each other's module names.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
370
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
371 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
372 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
373 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
374 :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
375 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
376 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
377 (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
378 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
379 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
380 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
381
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
382 sound/ Top-level package
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
383 __init__.py Initialize the sound package
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
384 formats/ Subpackage for file format conversions
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 wavread.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
387 wavwrite.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
388 aiffread.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
389 aiffwrite.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 auread.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
391 auwrite.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
392 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393 effects/ Subpackage for sound effects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
394 __init__.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
395 echo.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
396 surround.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
397 reverse.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
398 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
399 filters/ Subpackage for filters
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
400 __init__.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
401 equalizer.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
402 vocoder.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
403 karaoke.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
404 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
405
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
406 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
407 ``sys.path`` looking for the package subdirectory.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
408
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
409 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
410 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
411 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
412 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
413 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
414 set the ``__all__`` variable, described later.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
415
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
416 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
417 example::
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 import sound.effects.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 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
422 its full name. ::
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 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
425
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
426 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
427
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
428 from sound.effects import echo
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 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
431 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
432
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
433 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
434
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
435 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
436
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
437 from sound.effects.echo import echofilter
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 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
440 :func:`echofilter` directly available::
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 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
443
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
444 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
445 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
446 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
447 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
448 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
449 exception is raised.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
450
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
451 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
452 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
453 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
454 item.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
455
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
456
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
457 .. _tut-pkg-import-star:
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 Importing \* From a Package
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
462 .. index:: single: __all__
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 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
465 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
466 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
467 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
468 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
469
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
470 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
471 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
472 :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
473 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
474 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
475 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
476 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
477 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
478 code::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
479
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
480 __all__ = ["echo", "surround", "reverse"]
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 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
483 named submodules of the :mod:`sound` package.
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 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
486 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
487 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
488 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
489 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
490 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
491 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
492 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
493
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
494 import sound.effects.echo
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
495 import sound.effects.surround
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
496 from sound.effects import *
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
497
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
498 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
499 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
500 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
501 ``__all__`` is defined.)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
502
56368
c9bd62efe6ce Merged revisions 75231 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 55580
diff changeset
503 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
504 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
505 production code.
42604
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 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
508 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
509 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
510 packages.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
511
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
513 Intra-package References
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
516 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
517 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
518 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
519 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
520 sound.effects import echo``.
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 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
523 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
524 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
525 module for example, you might use::
42604
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 from . import echo
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
528 from .. import formats
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
529 from ..filters import equalizer
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
530
46963
03b1233bf5fe Remove many "versionchanged" items that didn't use the official markup,
Georg Brandl <georg@python.org>
parents: 44396
diff changeset
531 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
532 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
533 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
534
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 Packages in Multiple Directories
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
539 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
540 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
541 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
542 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
543 subpackages contained in the package.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
544
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
545 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
546 modules found in a package.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
547
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
548
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
549 .. rubric:: Footnotes
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 .. [#] In fact function definitions are also 'statements' that are 'executed'; 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
552 execution of a module-level function enters the function name in the module's
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
553 global symbol table.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
554