Lines Matching +full:is +full:- +full:module
1 .. _tut-modules:
11 is known as creating a *script*. As your program gets longer, you may want to
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
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
28 # Fibonacci numbers module
44 Now enter the Python interpreter and import this module with the following
50 the current symbol table; it only enters the module name ``fibo`` there. Using
51 the module name you can access the functions::
67 .. _tut-moremodules:
72 A module can contain executable statements as well as function definitions.
73 These statements are intended to initialize the module. They are executed only
74 the *first* time the module name is encountered in an import statement. [#]_
75 (They are also run if the file is executed as a script.)
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
81 doing you can touch a module's global variables with the same notation used to
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::
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::
107 Note that in general the practice of importing ``*`` from a module or package is
108 frowned upon, since it often causes poorly readable code. However, it is okay to
111 If the module name is followed by :keyword:`as`, then the name
112 following :keyword:`as` is bound directly to the imported module.
120 This is effectively importing the module in the same way that ``import fibo``
132 For efficiency reasons, each module is only imported once per interpreter
134 interpreter -- or, if it's just one module you want to test interactively,
138 .. _tut-modulesasscripts:
141 ----------------------------
143 When you run a Python module with ::
147 the code in the module will be executed, just as if you imported it, but with
149 the end of your module::
155 you can make the file usable as a script as well as an importable module,
156 because the code that parses the command line only runs if the module is
159 .. code-block:: shell-session
164 If the module is imported, the code is not run::
169 This is often used either to provide a convenient user interface to a module, or
170 for testing purposes (running the module as a script executes a test suite).
173 .. _tut-searchpath:
175 The Module Search Path
176 ----------------------
178 .. index:: triple: module; search; path
180 When a module named :mod:`spam` is imported, the interpreter first searches for
181 a built-in module with that name. If not found, it then searches for a file
183 :data:`sys.path`. :data:`sys.path` is initialized from these locations:
188 * the installation-dependent default.
191 directory containing the script being run is placed at the beginning of the
194 directory. This is an error unless the replacement is intended. See section
195 :ref:`tut-standardmodules` for more information.
199 -----------------------
201 As an important speed-up of the start-up time for short programs that use a lot
203 where :file:`spam.py` is found, this is assumed to contain an
204 already-"byte-compiled" version of the module :mod:`spam`. The modification time
205 of the version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in
206 :file:`spam.pyc`, and the :file:`.pyc` file is ignored if these don't match.
209 Whenever :file:`spam.py` is successfully compiled, an attempt is made to write
210 the compiled version to :file:`spam.pyc`. It is not an error if this attempt
211 fails; if for any reason the file is not written completely, the resulting
214 module directory can be shared by machines of different architectures.
218 * When the Python interpreter is invoked with the :option:`-O` flag, optimized
219 code is generated and stored in :file:`.pyo` files. The optimizer currently
221 :option:`-O` is used, *all* :term:`bytecode` is optimized; ``.pyc`` files are
224 * Passing two :option:`-O` flags to the Python interpreter (:option:`-OO`) will
231 * A program doesn't run any faster when it is read from a :file:`.pyc` or
232 :file:`.pyo` file than when it is read from a :file:`.py` file; the only thing
233 that's faster about :file:`.pyc` or :file:`.pyo` files is the speed with which
236 * When a script is run by giving its name on the command line, the bytecode for
237 the script is never written to a :file:`.pyc` or :file:`.pyo` file. Thus, the
238 startup time of a script may be reduced by moving most of its code to a module
239 and having a small bootstrap script that imports that module. It is also
243 * It is possible to have a file called :file:`spam.pyc` (or :file:`spam.pyo`
244 when :option:`-O` is used) without a file :file:`spam.py` for the same module.
245 This can be used to distribute a library of Python code in a form that is
248 .. index:: module: compileall
250 * The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo`
251 files when :option:`-O` is used) for all modules in a directory.
254 .. _tut-standardmodules:
259 .. index:: module: sys
266 system calls. The set of such modules is a configuration option which also
267 depends on the underlying platform. For example, the :mod:`winreg` module is only
268 provided on Windows systems. One particular module deserves some attention:
269 :mod:`sys`, which is built into every Python interpreter. The variables
284 These two variables are only defined if the interpreter is in interactive mode.
286 The variable ``sys.path`` is a list of strings that determines the interpreter's
287 search path for modules. It is initialized to a default path taken from the
288 environment variable :envvar:`PYTHONPATH`, or from a built-in default if
289 :envvar:`PYTHONPATH` is not set. You can modify it using standard list
296 .. _tut-dir:
301 The built-in function :func:`dir` is used to find out which names a module
334 .. index:: module: __builtin__
336 :func:`dir` does not list the names of built-in functions and variables. If you
337 want a list of those, they are defined in the standard module
370 .. _tut-packages:
375 Packages are a way of structuring Python's module namespace by using "dotted
376 module names". For example, the module name :mod:`A.B` designates a submodule
379 variable names, the use of dotted module names saves the authors of multi-module
381 each other's module names.
390 artificial stereo effect), so in addition you will be writing a never-ending
394 .. code-block:: text
396 sound/ Top-level package
424 as containing packages; this is done to prevent directories with a common name,
426 on the module search path. In the simplest case, :file:`__init__.py` can just be
440 An alternative way of importing the submodule is::
449 Yet another variation is to import the desired function or variable directly::
461 tests whether the item is defined in the package; if not, it assumes it is a
462 module and attempts to load it. If it fails to find it, an :exc:`ImportError`
463 exception is raised.
466 except for the last must be a package; the last item can be a module or a
471 .. _tut-pkg-import-star:
474 ---------------------------
481 long time and importing sub-modules might have unwanted side-effects that should
482 only happen when the sub-module is explicitly imported.
484 The only solution is for the package author to provide an explicit index of the
486 :file:`__init__.py` code defines a list named ``__all__``, it is taken to be the
487 list of module names that should be imported when ``from package import *`` is
488 encountered. It is up to the package author to keep this list up-to-date when a
489 new version of the package is released. Package authors may also decide not to
499 If ``__all__`` is not defined, the statement ``from sound.effects import *``
514 when the ``from...import`` statement is executed. (This also works when
515 ``__all__`` is defined.)
518 patterns when you use ``import *``, it is still considered bad practice in
521 Remember, there is nothing wrong with using ``from Package import
522 specific_submodule``! In fact, this is the recommended notation unless the
523 importing module needs to use submodules with the same name from different
527 Intra-package References
528 ------------------------
531 :mod:`surround` module might use the :mod:`echo` module. In fact, such
533 containing package before looking in the standard module search path. Thus, the
534 :mod:`surround` module can simply use ``import echo`` or ``from echo import
535 echofilter``. If the imported module is not found in the current package (the
536 package of which the current module is a submodule), the :keyword:`import`
537 statement looks for a top-level module with the given name.
541 packages. For example, if the module :mod:`sound.filters.vocoder` needs to use
542 the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
546 above, you can write explicit relative imports with the ``from module import
549 import. From the :mod:`surround` module for example, you might use::
556 the current module. Since the name of the main module is always ``"__main__"``,
557 modules intended for use as the main module of a Python application should
562 --------------------------------
564 Packages support one more special attribute, :attr:`__path__`. This is
566 package's :file:`__init__.py` before the code in that file is executed. This
570 While this feature is not often needed, it can be used to extend the set of
577 execution of a module-level function definition enters the function name in
578 the module's global symbol table.