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
45 Now enter the Python interpreter and import this module with the following
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. [#]_
77 (They are also run if the file is executed as a script.)
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::
98 This does not introduce the module name from which the imports are taken in the
99 local namespace (so in the example, ``fibo`` is not defined).
101 There is even a variant to import all names that a module defines::
112 Note that in general the practice of importing ``*`` from a module or package is
113 frowned upon, since it often causes poorly readable code. However, it is okay to
116 If the module name is followed by :keyword:`!as`, then the name
117 following :keyword:`!as` is bound directly to the imported module.
125 This is effectively importing the module in the same way that ``import fibo``
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,
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::
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::
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
190 :data:`sys.path`. :data:`sys.path` is initialized from these locations:
193 file is specified).
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`.
203 script is calculated after the symlink is followed. In other words the
204 directory containing the symlink is **not** added to the module search path.
207 directory containing the script being run is placed at the beginning of the
210 directory. This is an error unless the replacement is intended. See section
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
230 to see if it's out of date and needs to be recompiled. This is a completely
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
236 from the command line. Second, it does not check the cache if there is no
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
251 * A program doesn't run any faster when it is read from a ``.pyc``
252 file than when it is read from a ``.py`` file; the only thing that's faster
253 about ``.pyc`` files is the speed with which they are loaded.
255 * The module :mod:`compileall` can create .pyc files for all modules in a
258 * There is more detail on this process, including a flow chart of the
262 .. _tut-standardmodules:
267 .. index:: pair: module; sys
274 system calls. The set of such modules is a configuration option which also
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:
277 :mod:`sys`, which is built into every Python interpreter. The variables
292 These two variables are only defined if the interpreter is in interactive mode.
294 The variable ``sys.path`` is a list of strings that determines the interpreter's
295 search path for modules. It is initialized to a default path taken from the
296 environment variable :envvar:`PYTHONPATH`, or from a built-in default if
297 :envvar:`PYTHONPATH` is not set. You can modify it using standard list
304 .. _tut-dir:
309 The built-in function :func:`dir` is used to find out which names a module
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
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
456 An alternative way of importing the submodule is::
465 Yet another variation is to import the desired function or variable directly::
477 tests whether the item is defined in the package; if not, it assumes it is a
478 module and attempts to load it. If it fails to find it, an :exc:`ImportError`
479 exception is raised.
482 except for the last must be a package; the last item can be a module or a
487 .. _tut-pkg-import-star:
490 ---------------------------
497 long time and importing sub-modules might have unwanted side-effects that should
498 only happen when the sub-module is explicitly imported.
500 The only solution is for the package author to provide an explicit index of the
502 :file:`__init__.py` code defines a list named ``__all__``, it is taken to be the
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
505 new version of the package is released. Package authors may also decide not to
515 If ``__all__`` is not defined, the statement ``from sound.effects import *``
530 when the ``from...import`` statement is executed. (This also works when
531 ``__all__`` is defined.)
534 patterns when you use ``import *``, it is still considered bad practice in
537 Remember, there is nothing wrong with using ``from package import
538 specific_submodule``! In fact, this is the recommended notation unless the
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
554 You can also write relative imports, with the ``from module import name`` form
557 module for example, you might use::
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 --------------------------------
571 Packages support one more special attribute, :attr:`__path__`. This is
573 package's :file:`__init__.py` before the code in that file is executed. This
577 While this feature is not often needed, it can be used to extend the set of
584 execution of a module-level function definition adds the function name to
585 the module's global namespace.