7
If you quit from the Python interpreter and enter it again, the definitions you
8
have made (functions and variables) are lost. Therefore, if you want to write a
9
somewhat longer program, you are better off using a text editor to prepare the
10
input for the interpreter and running it with that file as input instead. This
11
is known as creating a *script*. As your program gets longer, you may want to
12
split it into several files for easier maintenance. You may also want to use a
13
handy function that you've written in several programs without copying its
14
definition into each program.
16
To support this, Python has a way to put definitions in a file and use them in a
17
script or in an interactive instance of the interpreter. Such a file is called a
18
*module*; definitions from a module can be *imported* into other modules or into
19
the *main* module (the collection of variables that you have access to in a
20
script executed at the top level and in calculator mode).
22
A module is a file containing Python definitions and statements. The file name
23
is the module name with the suffix :file:`.py` appended. Within a module, the
24
module's name (as a string) is available as the value of the global variable
25
``__name__``. For instance, use your favorite text editor to create a file
26
called :file:`fibo.py` in the current directory with the following contents::
28
# Fibonacci numbers module
30
def fib(n): # write Fibonacci series up to n
37
def fib2(n): # return Fibonacci series up to n
45
Now enter the Python interpreter and import this module with the following
50
This does not enter the names of the functions defined in ``fibo`` directly in
51
the current symbol table; it only enters the module name ``fibo`` there. Using
52
the module name you can access the functions::
55
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
57
[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
61
If you intend to use a function often you can assign it to a local name::
65
1 1 2 3 5 8 13 21 34 55 89 144 233 377
73
A module can contain executable statements as well as function definitions.
74
These statements are intended to initialize the module. They are executed only
75
the *first* time the module is imported somewhere. [#]_
77
Each module has its own private symbol table, which is used as the global symbol
78
table by all functions defined in the module. Thus, the author of a module can
79
use global variables in the module without worrying about accidental clashes
80
with a user's global variables. On the other hand, if you know what you are
81
doing you can touch a module's global variables with the same notation used to
82
refer to its functions, ``modname.itemname``.
84
Modules can import other modules. It is customary but not required to place all
85
:keyword:`import` statements at the beginning of a module (or script, for that
86
matter). The imported module names are placed in the importing module's global
89
There is a variant of the :keyword:`import` statement that imports names from a
90
module directly into the importing module's symbol table. For example::
92
>>> from fibo import fib, fib2
94
1 1 2 3 5 8 13 21 34 55 89 144 233 377
96
This does not introduce the module name from which the imports are taken in the
97
local symbol table (so in the example, ``fibo`` is not defined).
99
There is even a variant to import all names that a module defines::
101
>>> from fibo import *
103
1 1 2 3 5 8 13 21 34 55 89 144 233 377
105
This imports all names except those beginning with an underscore (``_``).
106
In most cases Python programmers do not use this facility since it introduces
107
an unknown set of names into the interpreter, possibly hiding some things
108
you have already defined.
112
For efficiency reasons, each module is only imported once per interpreter
113
session. Therefore, if you change your modules, you must restart the
114
interpreter -- or, if it's just one module you want to test interactively,
115
use :func:`imp.reload`, e.g. ``import imp; imp.reload(modulename)``.
118
.. _tut-modulesasscripts:
120
Executing modules as scripts
121
----------------------------
123
When you run a Python module with ::
125
python fibo.py <arguments>
127
the code in the module will be executed, just as if you imported it, but with
128
the ``__name__`` set to ``"__main__"``. That means that by adding this code at
129
the end of your module::
131
if __name__ == "__main__":
133
fib(int(sys.argv[1]))
135
you can make the file usable as a script as well as an importable module,
136
because the code that parses the command line only runs if the module is
137
executed as the "main" file::
142
If the module is imported, the code is not run::
147
This is often used either to provide a convenient user interface to a module, or
148
for testing purposes (running the module as a script executes a test suite).
153
The Module Search Path
154
----------------------
156
.. index:: triple: module; search; path
158
When a module named :mod:`spam` is imported, the interpreter searches for a file
159
named :file:`spam.py` in the current directory, and then in the list of
160
directories specified by the environment variable :envvar:`PYTHONPATH`. This
161
has the same syntax as the shell variable :envvar:`PATH`, that is, a list of
162
directory names. When :envvar:`PYTHONPATH` is not set, or when the file is not
163
found there, the search continues in an installation-dependent default path; on
164
Unix, this is usually :file:`.:/usr/local/lib/python`.
166
Actually, modules are searched in the list of directories given by the variable
167
``sys.path`` which is initialized from the directory containing the input script
168
(or the current directory), :envvar:`PYTHONPATH` and the installation- dependent
169
default. This allows Python programs that know what they're doing to modify or
170
replace the module search path. Note that because the directory containing the
171
script being run is on the search path, it is important that the script not have
172
the same name as a standard module, or Python will attempt to load the script as
173
a module when that module is imported. This will generally be an error. See
174
section :ref:`tut-standardmodules` for more information.
177
Do we need stuff on zip files etc. ? DUBOIS
179
"Compiled" Python files
180
-----------------------
182
As an important speed-up of the start-up time for short programs that use a lot
183
of standard modules, if a file called :file:`spam.pyc` exists in the directory
184
where :file:`spam.py` is found, this is assumed to contain an
185
already-"byte-compiled" version of the module :mod:`spam`. The modification time
186
of the version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in
187
:file:`spam.pyc`, and the :file:`.pyc` file is ignored if these don't match.
189
Normally, you don't need to do anything to create the :file:`spam.pyc` file.
190
Whenever :file:`spam.py` is successfully compiled, an attempt is made to write
191
the compiled version to :file:`spam.pyc`. It is not an error if this attempt
192
fails; if for any reason the file is not written completely, the resulting
193
:file:`spam.pyc` file will be recognized as invalid and thus ignored later. The
194
contents of the :file:`spam.pyc` file are platform independent, so a Python
195
module directory can be shared by machines of different architectures.
197
Some tips for experts:
199
* When the Python interpreter is invoked with the :option:`-O` flag, optimized
200
code is generated and stored in :file:`.pyo` files. The optimizer currently
201
doesn't help much; it only removes :keyword:`assert` statements. When
202
:option:`-O` is used, *all* :term:`bytecode` is optimized; ``.pyc`` files are
203
ignored and ``.py`` files are compiled to optimized bytecode.
205
* Passing two :option:`-O` flags to the Python interpreter (:option:`-OO`) will
206
cause the bytecode compiler to perform optimizations that could in some rare
207
cases result in malfunctioning programs. Currently only ``__doc__`` strings are
208
removed from the bytecode, resulting in more compact :file:`.pyo` files. Since
209
some programs may rely on having these available, you should only use this
210
option if you know what you're doing.
212
* A program doesn't run any faster when it is read from a :file:`.pyc` or
213
:file:`.pyo` file than when it is read from a :file:`.py` file; the only thing
214
that's faster about :file:`.pyc` or :file:`.pyo` files is the speed with which
217
* When a script is run by giving its name on the command line, the bytecode for
218
the script is never written to a :file:`.pyc` or :file:`.pyo` file. Thus, the
219
startup time of a script may be reduced by moving most of its code to a module
220
and having a small bootstrap script that imports that module. It is also
221
possible to name a :file:`.pyc` or :file:`.pyo` file directly on the command
224
* It is possible to have a file called :file:`spam.pyc` (or :file:`spam.pyo`
225
when :option:`-O` is used) without a file :file:`spam.py` for the same module.
226
This can be used to distribute a library of Python code in a form that is
227
moderately hard to reverse engineer.
229
.. index:: module: compileall
231
* The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo`
232
files when :option:`-O` is used) for all modules in a directory.
235
.. _tut-standardmodules:
240
.. index:: module: sys
242
Python comes with a library of standard modules, described in a separate
243
document, the Python Library Reference ("Library Reference" hereafter). Some
244
modules are built into the interpreter; these provide access to operations that
245
are not part of the core of the language but are nevertheless built in, either
246
for efficiency or to provide access to operating system primitives such as
247
system calls. The set of such modules is a configuration option which also
248
depends on the underlying platform For example, the :mod:`winreg` module is only
249
provided on Windows systems. One particular module deserves some attention:
250
:mod:`sys`, which is built into every Python interpreter. The variables
251
``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary
265
These two variables are only defined if the interpreter is in interactive mode.
267
The variable ``sys.path`` is a list of strings that determines the interpreter's
268
search path for modules. It is initialized to a default path taken from the
269
environment variable :envvar:`PYTHONPATH`, or from a built-in default if
270
:envvar:`PYTHONPATH` is not set. You can modify it using standard list
274
>>> sys.path.append('/ufs/guido/lib/python')
279
The :func:`dir` Function
280
========================
282
The built-in function :func:`dir` is used to find out which names a module
283
defines. It returns a sorted list of strings::
287
['__name__', 'fib', 'fib2']
289
['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__',
290
'__stdin__', '__stdout__', '_getframe', 'api_version', 'argv',
291
'builtin_module_names', 'byteorder', 'callstats', 'copyright',
292
'displayhook', 'exc_info', 'excepthook',
293
'exec_prefix', 'executable', 'exit', 'getdefaultencoding', 'getdlopenflags',
294
'getrecursionlimit', 'getrefcount', 'hexversion', 'maxint', 'maxunicode',
295
'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache',
296
'platform', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setdlopenflags',
297
'setprofile', 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout',
298
'version', 'version_info', 'warnoptions']
300
Without arguments, :func:`dir` lists the names you have defined currently::
302
>>> a = [1, 2, 3, 4, 5]
306
['__builtins__', '__doc__', '__file__', '__name__', 'a', 'fib', 'fibo', 'sys']
308
Note that it lists all types of names: variables, modules, functions, etc.
310
.. index:: module: builtins
312
:func:`dir` does not list the names of built-in functions and variables. If you
313
want a list of those, they are defined in the standard module
319
['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException', 'Buffer
320
Error', 'BytesWarning', 'DeprecationWarning', 'EOFError', 'Ellipsis', 'Environme
321
ntError', 'Exception', 'False', 'FloatingPointError', 'FutureWarning', 'Generato
322
rExit', 'IOError', 'ImportError', 'ImportWarning', 'IndentationError', 'IndexErr
323
or', 'KeyError', 'KeyboardInterrupt', 'LookupError', 'MemoryError', 'NameError',
324
'None', 'NotImplemented', 'NotImplementedError', 'OSError', 'OverflowError', 'P
325
endingDeprecationWarning', 'ReferenceError', 'RuntimeError', 'RuntimeWarning', '
326
StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'Ta
327
bError', 'True', 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', 'Unicod
328
eEncodeError', 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserW
329
arning', 'ValueError', 'Warning', 'ZeroDivisionError', '__build_class__', '__deb
330
ug__', '__doc__', '__import__', '__name__', '__package__', 'abs', 'all', 'any',
331
'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'chr', 'classmethod', 'compile', '
332
complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate
333
', 'eval', 'exec', 'exit', 'filter', 'float', 'format', 'frozenset', 'getattr',
334
'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance',
335
'issubclass', 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memory
336
view', 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property'
337
, 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice', 'sort
338
ed', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars', 'zip']
345
Packages are a way of structuring Python's module namespace by using "dotted
346
module names". For example, the module name :mod:`A.B` designates a submodule
347
named ``B`` in a package named ``A``. Just like the use of modules saves the
348
authors of different modules from having to worry about each other's global
349
variable names, the use of dotted module names saves the authors of multi-module
350
packages like NumPy or the Python Imaging Library from having to worry about
351
each other's module names.
353
Suppose you want to design a collection of modules (a "package") for the uniform
354
handling of sound files and sound data. There are many different sound file
355
formats (usually recognized by their extension, for example: :file:`.wav`,
356
:file:`.aiff`, :file:`.au`), so you may need to create and maintain a growing
357
collection of modules for the conversion between the various file formats.
358
There are also many different operations you might want to perform on sound data
359
(such as mixing, adding echo, applying an equalizer function, creating an
360
artificial stereo effect), so in addition you will be writing a never-ending
361
stream of modules to perform these operations. Here's a possible structure for
362
your package (expressed in terms of a hierarchical filesystem)::
364
sound/ Top-level package
365
__init__.py Initialize the sound package
366
formats/ Subpackage for file format conversions
375
effects/ Subpackage for sound effects
381
filters/ Subpackage for filters
388
When importing the package, Python searches through the directories on
389
``sys.path`` looking for the package subdirectory.
391
The :file:`__init__.py` files are required to make Python treat the directories
392
as containing packages; this is done to prevent directories with a common name,
393
such as ``string``, from unintentionally hiding valid modules that occur later
394
on the module search path. In the simplest case, :file:`__init__.py` can just be
395
an empty file, but it can also execute initialization code for the package or
396
set the ``__all__`` variable, described later.
398
Users of the package can import individual modules from the package, for
401
import sound.effects.echo
403
This loads the submodule :mod:`sound.effects.echo`. It must be referenced with
406
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
408
An alternative way of importing the submodule is::
410
from sound.effects import echo
412
This also loads the submodule :mod:`echo`, and makes it available without its
413
package prefix, so it can be used as follows::
415
echo.echofilter(input, output, delay=0.7, atten=4)
417
Yet another variation is to import the desired function or variable directly::
419
from sound.effects.echo import echofilter
421
Again, this loads the submodule :mod:`echo`, but this makes its function
422
:func:`echofilter` directly available::
424
echofilter(input, output, delay=0.7, atten=4)
426
Note that when using ``from package import item``, the item can be either a
427
submodule (or subpackage) of the package, or some other name defined in the
428
package, like a function, class or variable. The ``import`` statement first
429
tests whether the item is defined in the package; if not, it assumes it is a
430
module and attempts to load it. If it fails to find it, an :exc:`ImportError`
433
Contrarily, when using syntax like ``import item.subitem.subsubitem``, each item
434
except for the last must be a package; the last item can be a module or a
435
package but can't be a class or function or variable defined in the previous
439
.. _tut-pkg-import-star:
441
Importing \* From a Package
442
---------------------------
444
.. index:: single: __all__
446
Now what happens when the user writes ``from sound.effects import *``? Ideally,
447
one would hope that this somehow goes out to the filesystem, finds which
448
submodules are present in the package, and imports them all. Unfortunately,
449
this operation does not work very well on Windows platforms, where the
450
filesystem does not always have accurate information about the case of a
451
filename! On these platforms, there is no guaranteed way to know whether a file
452
:file:`ECHO.PY` should be imported as a module :mod:`echo`, :mod:`Echo` or
453
:mod:`ECHO`. (For example, Windows 95 has the annoying practice of showing all
454
file names with a capitalized first letter.) The DOS 8+3 filename restriction
455
adds another interesting problem for long module names.
457
The only solution is for the package author to provide an explicit index of the
458
package. The import statement uses the following convention: if a package's
459
:file:`__init__.py` code defines a list named ``__all__``, it is taken to be the
460
list of module names that should be imported when ``from package import *`` is
461
encountered. It is up to the package author to keep this list up-to-date when a
462
new version of the package is released. Package authors may also decide not to
463
support it, if they don't see a use for importing \* from their package. For
464
example, the file :file:`sounds/effects/__init__.py` could contain the following
467
__all__ = ["echo", "surround", "reverse"]
469
This would mean that ``from sound.effects import *`` would import the three
470
named submodules of the :mod:`sound` package.
472
If ``__all__`` is not defined, the statement ``from sound.effects import *``
473
does *not* import all submodules from the package :mod:`sound.effects` into the
474
current namespace; it only ensures that the package :mod:`sound.effects` has
475
been imported (possibly running any initialization code in :file:`__init__.py`)
476
and then imports whatever names are defined in the package. This includes any
477
names defined (and submodules explicitly loaded) by :file:`__init__.py`. It
478
also includes any submodules of the package that were explicitly loaded by
479
previous import statements. Consider this code::
481
import sound.effects.echo
482
import sound.effects.surround
483
from sound.effects import *
485
In this example, the echo and surround modules are imported in the current
486
namespace because they are defined in the :mod:`sound.effects` package when the
487
``from...import`` statement is executed. (This also works when ``__all__`` is
490
Note that in general the practice of importing ``*`` from a module or package is
491
frowned upon, since it often causes poorly readable code. However, it is okay to
492
use it to save typing in interactive sessions, and certain modules are designed
493
to export only names that follow certain patterns.
495
Remember, there is nothing wrong with using ``from Package import
496
specific_submodule``! In fact, this is the recommended notation unless the
497
importing module needs to use submodules with the same name from different
501
Intra-package References
502
------------------------
504
When packages are structured into subpackages (as with the :mod:`sound` package
505
in the example), you can use absolute imports to refer to submodules of siblings
506
packages. For example, if the module :mod:`sound.filters.vocoder` needs to use
507
the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
508
sound.effects import echo``.
510
You can also write relative imports, with the ``from module import name`` form
511
of import statement. These imports use leading dots to indicate the current and
512
parent packages involved in the relative import. From the :mod:`surround`
513
module for example, you might use::
516
from .. import formats
517
from ..filters import equalizer
519
Note that relative imports are based on the name of the current module. Since
520
the name of the main module is always ``"__main__"``, modules intended for use
521
as the main module of a Python application must always use absolute imports.
524
Packages in Multiple Directories
525
--------------------------------
527
Packages support one more special attribute, :attr:`__path__`. This is
528
initialized to be a list containing the name of the directory holding the
529
package's :file:`__init__.py` before the code in that file is executed. This
530
variable can be modified; doing so affects future searches for modules and
531
subpackages contained in the package.
533
While this feature is not often needed, it can be used to extend the set of
534
modules found in a package.
537
.. rubric:: Footnotes
539
.. [#] In fact function definitions are also 'statements' that are 'executed'; the
540
execution enters the function name in the module's global symbol table.
added
removed
Doc/tutorial/modules.rst
