Lines Matching +full:import +full:- +full:module
1 .. _tut-modules:
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
45 Now enter the Python interpreter and import this module with the following
48 >>> import fibo
51 the current :term:`namespace` (see :ref:`tut-scopes` for more details);
52 it only adds the module name ``fibo`` there. Using
53 the module name you can access the functions::
69 .. _tut-moremodules:
74 A module can contain executable statements as well as function definitions.
75 These statements are intended to initialize the module. They are executed only
76 the *first* time the module name is encountered in an import statement. [#]_
79 Each module has its own private namespace, which is used as the global namespace
80 by all functions defined in the module. Thus, the author of a module can
81 use global variables in the module without worrying about accidental clashes
83 doing you can touch a module's global variables with the same notation used to
86 Modules can import other modules. It is customary but not required to place all
87 :keyword:`import` statements at the beginning of a module (or script, for that
88 matter). The imported module names, if placed at the top level of a module
89 (outside any functions or classes), are added to the module's global namespace.
91 There is a variant of the :keyword:`import` statement that imports names from a
92 module directly into the importing module's namespace. For example::
94 >>> from fibo import fib, fib2
98 This does not introduce the module name from which the imports are taken in the
101 There is even a variant to import all names that a module defines::
103 >>> from fibo import *
112 Note that in general the practice of importing ``*`` from a module or package is
116 If the module name is followed by :keyword:`!as`, then the name
117 following :keyword:`!as` is bound directly to the imported module.
121 >>> import fibo as fib
125 This is effectively importing the module in the same way that ``import fibo``
130 >>> from fibo import fib as fibonacci
137 For efficiency reasons, each module is only imported once per interpreter
139 interpreter -- or, if it's just one module you want to test interactively,
140 use :func:`importlib.reload`, e.g. ``import importlib;
144 .. _tut-modulesasscripts:
147 ----------------------------
149 When you run a Python module with ::
153 the code in the module will be executed, just as if you imported it, but with
155 the end of your module::
158 import sys
161 you can make the file usable as a script as well as an importable module,
162 because the code that parses the command line only runs if the module is
165 .. code-block:: shell-session
170 If the module is imported, the code is not run::
172 >>> import fibo
175 This is often used either to provide a convenient user interface to a module, or
176 for testing purposes (running the module as a script executes a test suite).
179 .. _tut-searchpath:
181 The Module Search Path
182 ----------------------
184 .. index:: triple: module; search; path
186 When a module named :mod:`spam` is imported, the interpreter first searches for
187 a built-in module with that name. These module names are listed in
196 * The installation-dependent default (by convention including a
197 ``site-packages`` directory, handled by the :mod:`site` module).
199 More details are at :ref:`sys-path-init`.
204 directory containing the symlink is **not** added to the module search path.
211 :ref:`tut-standardmodules` for more information.
216 .. _tut-pycache:
219 -----------------------
221 To speed up loading modules, Python caches the compiled version of each module
222 in the ``__pycache__`` directory under the name :file:`module.{version}.pyc`,
225 version of spam.py would be cached as ``__pycache__/spam.cpython-33.pyc``. This
231 automatic process. Also, the compiled modules are platform-independent, so the
235 recompiles and does not store the result for the module that's loaded directly
237 source module. To support a non-source (compiled only) distribution, the
238 compiled module must be in the source directory, and there must not be a source
239 module.
243 * You can use the :option:`-O` or :option:`-OO` switches on the Python command
244 to reduce the size of a compiled module. The ``-O`` switch removes assert
245 statements, the ``-OO`` switch removes both assert statements and __doc__
248 an ``opt-`` tag and are usually smaller. Future releases may
255 * The module :mod:`compileall` can create .pyc files for all modules in a
262 .. _tut-standardmodules:
267 .. index:: pair: module; sys
275 depends on the underlying platform. For example, the :mod:`winreg` module is only
276 provided on Windows systems. One particular module deserves some attention:
281 >>> import sys
296 environment variable :envvar:`PYTHONPATH`, or from a built-in default if
300 >>> import sys
304 .. _tut-dir:
309 The built-in function :func:`dir` is used to find out which names a module
312 >>> import fibo, sys
341 >>> import fibo
348 .. index:: pair: module; builtins
350 :func:`dir` does not list the names of built-in functions and variables. If you
351 want a list of those, they are defined in the standard module
354 >>> import builtins
386 .. _tut-packages:
391 Packages are a way of structuring Python's module namespace by using "dotted
392 module names". For example, the module name :mod:`A.B` designates a submodule
395 variable names, the use of dotted module names saves the authors of multi-module
397 each other's module names.
406 artificial stereo effect), so in addition you will be writing a never-ending
410 .. code-block:: text
412 sound/ Top-level package
442 on the module search path. In the simplest case, :file:`__init__.py` can just be
446 Users of the package can import individual modules from the package, for
449 import sound.effects.echo
458 from sound.effects import echo
465 Yet another variation is to import the desired function or variable directly::
467 from sound.effects.echo import echofilter
474 Note that when using ``from package import item``, the item can be either a
476 package, like a function, class or variable. The ``import`` statement first
478 module and attempts to load it. If it fails to find it, an :exc:`ImportError`
481 Contrarily, when using syntax like ``import item.subitem.subsubitem``, each item
482 except for the last must be a package; the last item can be a module or a
487 .. _tut-pkg-import-star:
490 ---------------------------
494 Now what happens when the user writes ``from sound.effects import *``? Ideally,
497 long time and importing sub-modules might have unwanted side-effects that should
498 only happen when the sub-module is explicitly imported.
501 package. The :keyword:`import` statement uses the following convention: if a package's
503 list of module names that should be imported when ``from package import *`` is
504 encountered. It is up to the package author to keep this list up-to-date when a
512 This would mean that ``from sound.effects import *`` would import the three
515 If ``__all__`` is not defined, the statement ``from sound.effects import *``
516 does *not* import all submodules from the package :mod:`sound.effects` into the
522 previous :keyword:`import` statements. Consider this code::
524 import sound.effects.echo
525 import sound.effects.surround
526 from sound.effects import *
530 when the ``from...import`` statement is executed. (This also works when
534 patterns when you use ``import *``, it is still considered bad practice in
537 Remember, there is nothing wrong with using ``from package import
539 importing module needs to use submodules with the same name from different
543 .. _intra-package-references:
545 Intra-package References
546 ------------------------
550 packages. For example, if the module :mod:`sound.filters.vocoder` needs to use
551 the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
552 sound.effects import echo``.
554 You can also write relative imports, with the ``from module import name`` form
555 of import statement. These imports use leading dots to indicate the current and
556 parent packages involved in the relative import. From the :mod:`surround`
557 module for example, you might use::
559 from . import echo
560 from .. import formats
561 from ..filters import equalizer
563 Note that relative imports are based on the name of the current module. Since
564 the name of the main module is always ``"__main__"``, modules intended for use
565 as the main module of a Python application must always use absolute imports.
569 --------------------------------
584 execution of a module-level function definition adds the function name to
585 the module's global namespace.