Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/modules.rst @ 80661:94de77bd0b4b 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.
author Andrew Svetlov <andrew.svetlov@gmail.com>
date Thu, 29 Nov 2012 19:51:28 +0200
parents 770bbc93ae89
children 6cb6c332c24f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. _tut-modules:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 *******
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 Modules
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 *******
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 definition into each program.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 script executed at the top level and in calculator mode).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 # Fibonacci numbers module
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 def fib(n): # write Fibonacci series up to n
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 a, b = 0, 1
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 while b < n:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 print b,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 a, b = b, a+b
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 def fib2(n): # return Fibonacci series up to n
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 result = []
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 a, b = 0, 1
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 while b < n:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 result.append(b)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 a, b = b, a+b
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 return result
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 Now enter the Python interpreter and import this module with the following
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 command::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 >>> import fibo
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 This does not enter the names of the functions defined in ``fibo`` directly in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 the current symbol table; it only enters the module name ``fibo`` there. Using
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 the module name you can access the functions::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 >>> fibo.fib(1000)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 >>> fibo.fib2(100)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 >>> fibo.__name__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 'fibo'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 If you intend to use a function often you can assign it to a local name::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 >>> fib = fibo.fib
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 >>> fib(500)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 1 1 2 3 5 8 13 21 34 55 89 144 233 377
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 .. _tut-moremodules:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 More on Modules
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 ===============
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 A module can contain executable statements as well as function definitions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 These statements are intended to initialize the module. They are executed only
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 the *first* time the module is imported somewhere. [#]_
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 Each module has its own private symbol table, which is used as the global symbol
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 table by all functions defined in the module. Thus, the author of a module can
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 use global variables in the module without worrying about accidental clashes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 with a user's global variables. On the other hand, if you know what you are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 doing you can touch a module's global variables with the same notation used to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 refer to its functions, ``modname.itemname``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 Modules can import other modules. It is customary but not required to place all
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 :keyword:`import` statements at the beginning of a module (or script, for that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 matter). The imported module names are placed in the importing module's global
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 symbol table.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 There is a variant of the :keyword:`import` statement that imports names from a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 module directly into the importing module's symbol table. For example::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 >>> from fibo import fib, fib2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 >>> fib(500)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 1 1 2 3 5 8 13 21 34 55 89 144 233 377
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 This does not introduce the module name from which the imports are taken in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 local symbol table (so in the example, ``fibo`` is not defined).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 There is even a variant to import all names that a module defines::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 >>> from fibo import *
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 >>> fib(500)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 1 1 2 3 5 8 13 21 34 55 89 144 233 377
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 This imports all names except those beginning with an underscore (``_``).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
106 Note that in general the practice of importing ``*`` from a module or package is
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
107 frowned upon, since it often causes poorly readable code. However, it is okay to
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
108 use it to save typing in interactive sessions.
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
109
46786
ccc337b45b2e Add a note about using reload().
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
110 .. note::
ccc337b45b2e Add a note about using reload().
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
111
ccc337b45b2e Add a note about using reload().
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
112 For efficiency reasons, each module is only imported once per interpreter
ccc337b45b2e Add a note about using reload().
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
113 session. Therefore, if you change your modules, you must restart the
ccc337b45b2e Add a note about using reload().
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
114 interpreter -- or, if it's just one module you want to test interactively,
46860
fb14ff057c09 reload() takes the module itself.
Georg Brandl <georg@python.org>
parents: 46786
diff changeset
115 use :func:`reload`, e.g. ``reload(modulename)``.
46786
ccc337b45b2e Add a note about using reload().
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
116
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 .. _tut-modulesasscripts:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 Executing modules as scripts
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 ----------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 When you run a Python module with ::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 python fibo.py <arguments>
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 the code in the module will be executed, just as if you imported it, but with
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 the ``__name__`` set to ``"__main__"``. That means that by adding this code at
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 the end of your module::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 if __name__ == "__main__":
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 import sys
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 fib(int(sys.argv[1]))
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 you can make the file usable as a script as well as an importable module,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 because the code that parses the command line only runs if the module is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 executed as the "main" file::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 $ python fibo.py 50
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 1 1 2 3 5 8 13 21 34
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
141
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 If the module is imported, the code is not run::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 >>> import fibo
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 >>>
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 This is often used either to provide a convenient user interface to a module, or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 for testing purposes (running the module as a script executes a test suite).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 .. _tut-searchpath:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 The Module Search Path
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 ----------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 .. index:: triple: module; search; path
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157
74521
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
158 When a module named :mod:`spam` is imported, the interpreter first searches for
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
159 a built-in module with that name. If not found, it then searches for a file
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
160 named :file:`spam.py` in a list of directories given by the variable
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
161 :data:`sys.path`. :data:`sys.path` is initialized from these locations:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
74521
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
163 * the directory containing the input script (or the current directory).
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
164 * :envvar:`PYTHONPATH` (a list of directory names, with the same syntax as the
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
165 shell variable :envvar:`PATH`).
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
166 * the installation-dependent default.
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
167
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
168 After initialization, Python programs can modify :data:`sys.path`. The
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
169 directory containing the script being run is placed at the beginning of the
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
170 search path, ahead of the standard library path. This means that scripts in that
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
171 directory will be loaded instead of modules of the same name in the library
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
172 directory. This is an error unless the replacement is intended. See section
d01208ba482f Issue #11948: clarify modules search path
Sandro Tosi <sandro.tosi@gmail.com>
parents: 70905
diff changeset
173 :ref:`tut-standardmodules` for more information.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 "Compiled" Python files
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 -----------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 As an important speed-up of the start-up time for short programs that use a lot
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 of standard modules, if a file called :file:`spam.pyc` exists in the directory
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 where :file:`spam.py` is found, this is assumed to contain an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 already-"byte-compiled" version of the module :mod:`spam`. The modification time
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 of the version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 :file:`spam.pyc`, and the :file:`.pyc` file is ignored if these don't match.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 Normally, you don't need to do anything to create the :file:`spam.pyc` file.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 Whenever :file:`spam.py` is successfully compiled, an attempt is made to write
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 the compiled version to :file:`spam.pyc`. It is not an error if this attempt
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 fails; if for any reason the file is not written completely, the resulting
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 :file:`spam.pyc` file will be recognized as invalid and thus ignored later. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191 contents of the :file:`spam.pyc` file are platform independent, so a Python
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 module directory can be shared by machines of different architectures.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 Some tips for experts:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 * When the Python interpreter is invoked with the :option:`-O` flag, optimized
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 code is generated and stored in :file:`.pyo` files. The optimizer currently
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 doesn't help much; it only removes :keyword:`assert` statements. When
43627
faf5de69e977 Add :term:s for descriptors.
Georg Brandl <georg@python.org>
parents: 42603
diff changeset
199 :option:`-O` is used, *all* :term:`bytecode` is optimized; ``.pyc`` files are
faf5de69e977 Add :term:s for descriptors.
Georg Brandl <georg@python.org>
parents: 42603
diff changeset
200 ignored and ``.py`` files are compiled to optimized bytecode.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 * Passing two :option:`-O` flags to the Python interpreter (:option:`-OO`) will
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 cause the bytecode compiler to perform optimizations that could in some rare
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
204 cases result in malfunctioning programs. Currently only ``__doc__`` strings are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205 removed from the bytecode, resulting in more compact :file:`.pyo` files. Since
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 some programs may rely on having these available, you should only use this
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207 option if you know what you're doing.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 * A program doesn't run any faster when it is read from a :file:`.pyc` or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210 :file:`.pyo` file than when it is read from a :file:`.py` file; the only thing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 that's faster about :file:`.pyc` or :file:`.pyo` files is the speed with which
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 they are loaded.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214 * When a script is run by giving its name on the command line, the bytecode for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 the script is never written to a :file:`.pyc` or :file:`.pyo` file. Thus, the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 startup time of a script may be reduced by moving most of its code to a module
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 and having a small bootstrap script that imports that module. It is also
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 possible to name a :file:`.pyc` or :file:`.pyo` file directly on the command
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 line.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 * It is possible to have a file called :file:`spam.pyc` (or :file:`spam.pyo`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 when :option:`-O` is used) without a file :file:`spam.py` for the same module.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
223 This can be used to distribute a library of Python code in a form that is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 moderately hard to reverse engineer.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226 .. index:: module: compileall
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 * The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 files when :option:`-O` is used) for all modules in a directory.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 .. _tut-standardmodules:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 Standard Modules
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235 ================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 .. index:: module: sys
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 Python comes with a library of standard modules, described in a separate
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 document, the Python Library Reference ("Library Reference" hereafter). Some
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 modules are built into the interpreter; these provide access to operations that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
242 are not part of the core of the language but are nevertheless built in, either
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 for efficiency or to provide access to operating system primitives such as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 system calls. The set of such modules is a configuration option which also
78412
1bc398a63444 add missing period; thanks to Gaston Fiore from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74521
diff changeset
245 depends on the underlying platform. For example, the :mod:`winreg` module is only
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 provided on Windows systems. One particular module deserves some attention:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 :mod:`sys`, which is built into every Python interpreter. The variables
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248 ``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 43627
diff changeset
249 prompts::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
250
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
251 >>> import sys
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
252 >>> sys.ps1
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253 '>>> '
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
254 >>> sys.ps2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
255 '... '
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 >>> sys.ps1 = 'C> '
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 C> print 'Yuck!'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
258 Yuck!
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259 C>
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
260
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262 These two variables are only defined if the interpreter is in interactive mode.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264 The variable ``sys.path`` is a list of strings that determines the interpreter's
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 search path for modules. It is initialized to a default path taken from the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266 environment variable :envvar:`PYTHONPATH`, or from a built-in default if
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 :envvar:`PYTHONPATH` is not set. You can modify it using standard list
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268 operations::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 >>> import sys
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
271 >>> sys.path.append('/ufs/guido/lib/python')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
272
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274 .. _tut-dir:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 The :func:`dir` Function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 ========================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 The built-in function :func:`dir` is used to find out which names a module
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
280 defines. It returns a sorted list of strings::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
281
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 >>> import fibo, sys
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
283 >>> dir(fibo)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
284 ['__name__', 'fib', 'fib2']
80463
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
285 >>> dir(sys) # doctest: +NORMALIZE_WHITESPACE
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
286 ['__displayhook__', '__doc__', '__excepthook__', '__name__', '__package__',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
287 '__stderr__', '__stdin__', '__stdout__', '_clear_type_cache',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
288 '_current_frames', '_getframe', '_mercurial', 'api_version', 'argv',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
289 'builtin_module_names', 'byteorder', 'call_tracing', 'callstats',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
290 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_clear', 'exc_info',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
291 'exc_traceback', 'exc_type', 'exc_value', 'excepthook', 'exec_prefix',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
292 'executable', 'exit', 'flags', 'float_info', 'float_repr_style',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
293 'getcheckinterval', 'getdefaultencoding', 'getdlopenflags',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
294 'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
295 'getrefcount', 'getsizeof', 'gettotalrefcount', 'gettrace', 'hexversion',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
296 'long_info', 'maxint', 'maxsize', 'maxunicode', 'meta_path', 'modules',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
297 'path', 'path_hooks', 'path_importer_cache', 'platform', 'prefix', 'ps1',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
298 'py3kwarning', 'setcheckinterval', 'setdlopenflags', 'setprofile',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
299 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout', 'subversion',
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
300 'version', 'version_info', 'warnoptions']
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 Without arguments, :func:`dir` lists the names you have defined currently::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304 >>> a = [1, 2, 3, 4, 5]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
305 >>> import fibo
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
306 >>> fib = fibo.fib
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
307 >>> dir()
80463
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
308 ['__builtins__', '__name__', '__package__', 'a', 'fib', 'fibo', 'sys']
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
309
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
310 Note that it lists all types of names: variables, modules, functions, etc.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 .. index:: module: __builtin__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
313
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
314 :func:`dir` does not list the names of built-in functions and variables. If you
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
315 want a list of those, they are defined in the standard module
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
316 :mod:`__builtin__`::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
317
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
318 >>> import __builtin__
80463
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
319 >>> dir(__builtin__) # doctest: +NORMALIZE_WHITESPACE
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
320 ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
321 'BufferError', 'BytesWarning', 'DeprecationWarning', 'EOFError',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
322 'Ellipsis', 'EnvironmentError', 'Exception', 'False', 'FloatingPointError',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
323 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError', 'ImportWarning',
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
324 'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
325 'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented',
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 46860
diff changeset
326 'NotImplementedError', 'OSError', 'OverflowError',
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
327 'PendingDeprecationWarning', 'ReferenceError', 'RuntimeError',
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328 'RuntimeWarning', 'StandardError', 'StopIteration', 'SyntaxError',
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
329 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True',
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError',
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
331 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError',
80463
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
332 'UnicodeWarning', 'UserWarning', 'ValueError', 'Warning',
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
333 'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__',
80463
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
334 '__name__', '__package__', 'abs', 'all', 'any', 'apply', 'basestring',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
335 'bin', 'bool', 'buffer', 'bytearray', 'bytes', 'callable', 'chr',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
336 'classmethod', 'cmp', 'coerce', 'compile', 'complex', 'copyright',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
337 'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
338 'execfile', 'exit', 'file', 'filter', 'float', 'format', 'frozenset',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
339 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
340 'int', 'intern', 'isinstance', 'issubclass', 'iter', 'len', 'license',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
341 'list', 'locals', 'long', 'map', 'max', 'memoryview', 'min', 'next',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
342 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property', 'quit',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
343 'range', 'raw_input', 'reduce', 'reload', 'repr', 'reversed', 'round',
770bbc93ae89 Update section about dir() in the tutorial.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78412
diff changeset
344 'set', 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super',
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
345 'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip']
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348 .. _tut-packages:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350 Packages
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
351 ========
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
353 Packages are a way of structuring Python's module namespace by using "dotted
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
354 module names". For example, the module name :mod:`A.B` designates a submodule
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
355 named ``B`` in a package named ``A``. Just like the use of modules saves the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
356 authors of different modules from having to worry about each other's global
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
357 variable names, the use of dotted module names saves the authors of multi-module
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358 packages like NumPy or the Python Imaging Library from having to worry about
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
359 each other's module names.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
361 Suppose you want to design a collection of modules (a "package") for the uniform
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
362 handling of sound files and sound data. There are many different sound file
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
363 formats (usually recognized by their extension, for example: :file:`.wav`,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
364 :file:`.aiff`, :file:`.au`), so you may need to create and maintain a growing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
365 collection of modules for the conversion between the various file formats.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
366 There are also many different operations you might want to perform on sound data
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
367 (such as mixing, adding echo, applying an equalizer function, creating an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
368 artificial stereo effect), so in addition you will be writing a never-ending
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
369 stream of modules to perform these operations. Here's a possible structure for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
370 your package (expressed in terms of a hierarchical filesystem)::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
371
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
372 sound/ Top-level package
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
373 __init__.py Initialize the sound package
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
374 formats/ Subpackage for file format conversions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
375 __init__.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
376 wavread.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
377 wavwrite.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
378 aiffread.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
379 aiffwrite.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
380 auread.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
381 auwrite.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
382 ...
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
383 effects/ Subpackage for sound effects
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
384 __init__.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
385 echo.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
386 surround.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
387 reverse.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
388 ...
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
389 filters/ Subpackage for filters
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 __init__.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
391 equalizer.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
392 vocoder.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393 karaoke.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
394 ...
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
395
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
396 When importing the package, Python searches through the directories on
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
397 ``sys.path`` looking for the package subdirectory.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
398
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
399 The :file:`__init__.py` files are required to make Python treat the directories
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
400 as containing packages; this is done to prevent directories with a common name,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
401 such as ``string``, from unintentionally hiding valid modules that occur later
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
402 on the module search path. In the simplest case, :file:`__init__.py` can just be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
403 an empty file, but it can also execute initialization code for the package or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
404 set the ``__all__`` variable, described later.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
405
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
406 Users of the package can import individual modules from the package, for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
407 example::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
408
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
409 import sound.effects.echo
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
410
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
411 This loads the submodule :mod:`sound.effects.echo`. It must be referenced with
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
412 its full name. ::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
413
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
414 sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
415
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
416 An alternative way of importing the submodule is::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
417
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
418 from sound.effects import echo
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
419
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
420 This also loads the submodule :mod:`echo`, and makes it available without its
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
421 package prefix, so it can be used as follows::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
422
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
423 echo.echofilter(input, output, delay=0.7, atten=4)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
424
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
425 Yet another variation is to import the desired function or variable directly::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
426
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
427 from sound.effects.echo import echofilter
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
428
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
429 Again, this loads the submodule :mod:`echo`, but this makes its function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
430 :func:`echofilter` directly available::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
431
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
432 echofilter(input, output, delay=0.7, atten=4)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
433
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
434 Note that when using ``from package import item``, the item can be either a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
435 submodule (or subpackage) of the package, or some other name defined in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
436 package, like a function, class or variable. The ``import`` statement first
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
437 tests whether the item is defined in the package; if not, it assumes it is a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
438 module and attempts to load it. If it fails to find it, an :exc:`ImportError`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
439 exception is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
440
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
441 Contrarily, when using syntax like ``import item.subitem.subsubitem``, each item
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
442 except for the last must be a package; the last item can be a module or a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
443 package but can't be a class or function or variable defined in the previous
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
444 item.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
445
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
446
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
447 .. _tut-pkg-import-star:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
448
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
449 Importing \* From a Package
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
450 ---------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
451
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
452 .. index:: single: __all__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
453
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
454 Now what happens when the user writes ``from sound.effects import *``? Ideally,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
455 one would hope that this somehow goes out to the filesystem, finds which
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
456 submodules are present in the package, and imports them all. This could take a
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
457 long time and importing sub-modules might have unwanted side-effects that should
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
458 only happen when the sub-module is explicitly imported.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
459
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
460 The only solution is for the package author to provide an explicit index of the
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
461 package. The :keyword:`import` statement uses the following convention: if a package's
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
462 :file:`__init__.py` code defines a list named ``__all__``, it is taken to be the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
463 list of module names that should be imported when ``from package import *`` is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
464 encountered. It is up to the package author to keep this list up-to-date when a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
465 new version of the package is released. Package authors may also decide not to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
466 support it, if they don't see a use for importing \* from their package. For
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
467 example, the file :file:`sounds/effects/__init__.py` could contain the following
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
468 code::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
469
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
470 __all__ = ["echo", "surround", "reverse"]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
471
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
472 This would mean that ``from sound.effects import *`` would import the three
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
473 named submodules of the :mod:`sound` package.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
474
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
475 If ``__all__`` is not defined, the statement ``from sound.effects import *``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
476 does *not* import all submodules from the package :mod:`sound.effects` into the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
477 current namespace; it only ensures that the package :mod:`sound.effects` has
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
478 been imported (possibly running any initialization code in :file:`__init__.py`)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
479 and then imports whatever names are defined in the package. This includes any
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
480 names defined (and submodules explicitly loaded) by :file:`__init__.py`. It
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
481 also includes any submodules of the package that were explicitly loaded by
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
482 previous :keyword:`import` statements. Consider this code::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
483
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
484 import sound.effects.echo
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
485 import sound.effects.surround
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
486 from sound.effects import *
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
487
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
488 In this example, the :mod:`echo` and :mod:`surround` modules are imported in the
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
489 current namespace because they are defined in the :mod:`sound.effects` package
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
490 when the ``from...import`` statement is executed. (This also works when
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
491 ``__all__`` is defined.)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
492
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
493 Although certain modules are designed to export only names that follow certain
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
494 patterns when you use ``import *``, it is still considered bad practise in
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
495 production code.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
496
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
497 Remember, there is nothing wrong with using ``from Package import
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
498 specific_submodule``! In fact, this is the recommended notation unless the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
499 importing module needs to use submodules with the same name from different
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
500 packages.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
501
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
502
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
503 Intra-package References
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
504 ------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
505
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
506 The submodules often need to refer to each other. For example, the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
507 :mod:`surround` module might use the :mod:`echo` module. In fact, such
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
508 references are so common that the :keyword:`import` statement first looks in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
509 containing package before looking in the standard module search path. Thus, the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
510 :mod:`surround` module can simply use ``import echo`` or ``from echo import
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
511 echofilter``. If the imported module is not found in the current package (the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
512 package of which the current module is a submodule), the :keyword:`import`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
513 statement looks for a top-level module with the given name.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
514
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
515 When packages are structured into subpackages (as with the :mod:`sound` package
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
516 in the example), you can use absolute imports to refer to submodules of siblings
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
517 packages. For example, if the module :mod:`sound.filters.vocoder` needs to use
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
518 the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
519 sound.effects import echo``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
520
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
521 Starting with Python 2.5, in addition to the implicit relative imports described
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
522 above, you can write explicit relative imports with the ``from module import
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
523 name`` form of import statement. These explicit relative imports use leading
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
524 dots to indicate the current and parent packages involved in the relative
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
525 import. From the :mod:`surround` module for example, you might use::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
526
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
527 from . import echo
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
528 from .. import formats
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
529 from ..filters import equalizer
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
530
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
531 Note that both explicit and implicit relative imports are based on the name of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
532 the current module. Since the name of the main module is always ``"__main__"``,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
533 modules intended for use as the main module of a Python application should
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
534 always use absolute imports.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
535
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
536
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
537 Packages in Multiple Directories
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
538 --------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
539
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
540 Packages support one more special attribute, :attr:`__path__`. This is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
541 initialized to be a list containing the name of the directory holding the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
542 package's :file:`__init__.py` before the code in that file is executed. This
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
543 variable can be modified; doing so affects future searches for modules and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
544 subpackages contained in the package.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
545
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
546 While this feature is not often needed, it can be used to extend the set of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
547 modules found in a package.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
548
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
549
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
550 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
551
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
552 .. [#] In fact function definitions are also 'statements' that are 'executed'; the
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
553 execution of a module-level function enters the function name in the module's
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
554 global symbol table.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
555