| There is even a variant to import all names that a module defines:: |
| |
| >>> from fibo import * |
| >>> fib(500) |
| 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
| |
| This imports all names except those beginning with an underscore (``_``). |
| |
n | .. note:: |
| |
| For efficiency reasons, each module is only imported once per interpreter |
| session. Therefore, if you change your modules, you must restart the |
| interpreter -- or, if it's just one module you want to test interactively, |
| use :func:`reload`, e.g. ``reload(modulename)``. |
| |
| |
| .. _tut-modulesasscripts: |
| |
| Executing modules as scripts |
| ---------------------------- |
| |
| When you run a Python module with :: |
| |
| python fibo.py <arguments> |
| |
| the code in the module will be executed, just as if you imported it, but with |
| the ``__name__`` set to ``"__main__"``. That means that by adding this code at |
| the end of your module:: |
| |
| if __name__ == "__main__": |
| import sys |
| fib(int(sys.argv[1])) |
| |
| you can make the file usable as a script as well as an importable module, |
| because the code that parses the command line only runs if the module is |
| executed as the "main" file:: |
| |
| $ python fibo.py 50 |
| 1 1 2 3 5 8 13 21 34 |
| |
| If the module is imported, the code is not run:: |
| |
| >>> import fibo |
| >>> |
| |
| This is often used either to provide a convenient user interface to a module, or |
| for testing purposes (running the module as a script executes a test suite). |
| |
| |
| .. _tut-searchpath: |
| |
| The Module Search Path |
| ---------------------- |
| |
| .. index:: triple: module; search; path |
| |
| When a module named :mod:`spam` is imported, the interpreter searches for a file |
| named :file:`spam.py` in the current directory, and then in the list of |
| directories specified by the environment variable :envvar:`PYTHONPATH`. This |
| has the same syntax as the shell variable :envvar:`PATH`, that is, a list of |
| directory names. When :envvar:`PYTHONPATH` is not set, or when the file is not |
| found there, the search continues in an installation-dependent default path; on |
| Unix, this is usually :file:`.:/usr/local/lib/python`. |
| |
n | Actually, modules are searched in the list of directories given by the variable |
n | Actually, modules are searched in the list of directories given by the variable |
| ``sys.path`` which is initialized from the directory containing the input |
| ``sys.path`` which is initialized from the directory containing the input script |
| script (or the current directory), :envvar:`PYTHONPATH` and the installation- |
| (or the current directory), :envvar:`PYTHONPATH` and the installation- dependent |
| dependent default. This allows Python programs that know what they're doing to |
| default. This allows Python programs that know what they're doing to modify or |
| modify or replace the module search path. Note that because the directory |
| replace the module search path. Note that because the directory containing the |
| containing the script being run is on the search path, it is important that the |
| script being run is on the search path, it is important that the script not have |
| script not have the same name as a standard module, or Python will attempt to |
| the same name as a standard module, or Python will attempt to load the script as |
| load the script as a module when that module is imported. This will generally be |
| a module when that module is imported. This will generally be an error. See |
| an error. See section :ref:`tut-standardmodules`, "Standard Modules," for more |
| section :ref:`tut-standardmodules` for more information. |
| information. |
| |
| |
| "Compiled" Python files |
| ----------------------- |
| |
| As an important speed-up of the start-up time for short programs that use a lot |
| of standard modules, if a file called :file:`spam.pyc` exists in the directory |
n | where :file:`spam.py` is found, this is assumed to contain an already-"byte- |
n | where :file:`spam.py` is found, this is assumed to contain an |
| compiled" version of the module :mod:`spam`. The modification time of the |
| already-"byte-compiled" version of the module :mod:`spam`. The modification time |
| version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in |
| of the version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in |
| :file:`spam.pyc`, and the :file:`.pyc` file is ignored if these don't match. |
| |
| Normally, you don't need to do anything to create the :file:`spam.pyc` file. |
| Whenever :file:`spam.py` is successfully compiled, an attempt is made to write |
| the compiled version to :file:`spam.pyc`. It is not an error if this attempt |
| fails; if for any reason the file is not written completely, the resulting |
| :file:`spam.pyc` file will be recognized as invalid and thus ignored later. The |
| contents of the :file:`spam.pyc` file are platform independent, so a Python |
| module directory can be shared by machines of different architectures. |
| |
| Some tips for experts: |
| |
| * When the Python interpreter is invoked with the :option:`-O` flag, optimized |
| code is generated and stored in :file:`.pyo` files. The optimizer currently |
| doesn't help much; it only removes :keyword:`assert` statements. When |
n | :option:`-O` is used, *all* bytecode is optimized; ``.pyc`` files are ignored |
n | :option:`-O` is used, *all* :term:`bytecode` is optimized; ``.pyc`` files are |
| and ``.py`` files are compiled to optimized bytecode. |
| ignored and ``.py`` files are compiled to optimized bytecode. |
| |
| * Passing two :option:`-O` flags to the Python interpreter (:option:`-OO`) will |
| cause the bytecode compiler to perform optimizations that could in some rare |
| cases result in malfunctioning programs. Currently only ``__doc__`` strings are |
| removed from the bytecode, resulting in more compact :file:`.pyo` files. Since |
| some programs may rely on having these available, you should only use this |
| option if you know what you're doing. |
| |
| |
| * It is possible to have a file called :file:`spam.pyc` (or :file:`spam.pyo` |
| when :option:`-O` is used) without a file :file:`spam.py` for the same module. |
| This can be used to distribute a library of Python code in a form that is |
| moderately hard to reverse engineer. |
| |
| .. index:: module: compileall |
| |
n | * The module :mod:`compileall` (XXX reference: ../lib/module-compileall.html) |
n | * The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo` |
| can create :file:`.pyc` files (or :file:`.pyo` files when :option:`-O` is used) |
| files when :option:`-O` is used) for all modules in a directory. |
| for all modules in a directory. |
| |
| .. % |
| |
| |
| .. _tut-standardmodules: |
| |
| Standard Modules |
| ================ |
| |
| .. index:: module: sys |
| |
| Python comes with a library of standard modules, described in a separate |
n | document, the Python Library Reference (XXX reference: ../lib/lib.html) |
n | document, the Python Library Reference ("Library Reference" hereafter). Some |
| ("Library Reference" hereafter). Some modules are built into the interpreter; |
| modules are built into the interpreter; these provide access to operations that |
| these provide access to operations that are not part of the core of the language |
| are not part of the core of the language but are nevertheless built in, either |
| but are nevertheless built in, either for efficiency or to provide access to |
| for efficiency or to provide access to operating system primitives such as |
| operating system primitives such as system calls. The set of such modules is a |
| system calls. The set of such modules is a configuration option which also |
| configuration option which also depends on the underlying platform For example, |
| depends on the underlying platform For example, the :mod:`winreg` module is only |
| the :mod:`amoeba` module is only provided on systems that somehow support Amoeba |
| provided on Windows systems. One particular module deserves some attention: |
| primitives. One particular module deserves some attention: :mod:`sys` (XXX |
| :mod:`sys`, which is built into every Python interpreter. The variables |
| reference: ../lib/module-sys.html), which is built into every Python |
| ``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary |
| interpreter. The variables ``sys.ps1`` and ``sys.ps2`` define the strings used |
| prompts:: |
| as primary and secondary prompts: |
| |
| .. % |
| |
| :: |
| |
| >>> import sys |
| >>> sys.ps1 |
| '>>> ' |
| >>> sys.ps2 |
| '... ' |
| >>> sys.ps1 = 'C> ' |
| C> print 'Yuck!' |
| The built-in function :func:`dir` is used to find out which names a module |
| defines. It returns a sorted list of strings:: |
| |
| >>> import fibo, sys |
| >>> dir(fibo) |
| ['__name__', 'fib', 'fib2'] |
| >>> dir(sys) |
| ['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__', |
n | '__stdin__', '__stdout__', '_getframe', 'api_version', 'argv', |
n | '__stdin__', '__stdout__', '_getframe', 'api_version', 'argv', |
| 'builtin_module_names', 'byteorder', 'callstats', 'copyright', |
| 'displayhook', 'exc_clear', 'exc_info', 'exc_type', 'excepthook', |
| 'exec_prefix', 'executable', 'exit', 'getdefaultencoding', 'getdlopenflags', |
| 'getrecursionlimit', 'getrefcount', 'hexversion', 'maxint', 'maxunicode', |
| 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache', |
| 'platform', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setdlopenflags', |
| 'setprofile', 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout', |
| 'version', 'version_info', 'warnoptions'] |
| |
| >>> import __builtin__ |
| >>> dir(__builtin__) |
| ['ArithmeticError', 'AssertionError', 'AttributeError', 'DeprecationWarning', |
| 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False', |
| 'FloatingPointError', 'FutureWarning', 'IOError', 'ImportError', |
| 'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt', |
| 'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented', |
n | 'NotImplementedError', 'OSError', 'OverflowError', |
n | 'NotImplementedError', 'OSError', 'OverflowError', |
| 'PendingDeprecationWarning', 'ReferenceError', 'RuntimeError', |
| 'RuntimeWarning', 'StandardError', 'StopIteration', 'SyntaxError', |
| 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True', |
| 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', |
| 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError', |
| 'UserWarning', 'ValueError', 'Warning', 'WindowsError', |
| 'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__', |
| '__name__', 'abs', 'apply', 'basestring', 'bool', 'buffer', |
| such as ``string``, from unintentionally hiding valid modules that occur later |
| on the module search path. In the simplest case, :file:`__init__.py` can just be |
| an empty file, but it can also execute initialization code for the package or |
| set the ``__all__`` variable, described later. |
| |
| Users of the package can import individual modules from the package, for |
| example:: |
| |
n | import Sound.Effects.echo |
n | import sound.effects.echo |
| |
n | This loads the submodule :mod:`Sound.Effects.echo`. It must be referenced with |
n | This loads the submodule :mod:`sound.effects.echo`. It must be referenced with |
| its full name. :: |
| |
n | Sound.Effects.echo.echofilter(input, output, delay=0.7, atten=4) |
n | sound.effects.echo.echofilter(input, output, delay=0.7, atten=4) |
| |
| An alternative way of importing the submodule is:: |
| |
n | from Sound.Effects import echo |
n | from sound.effects import echo |
| |
| This also loads the submodule :mod:`echo`, and makes it available without its |
| package prefix, so it can be used as follows:: |
| |
| echo.echofilter(input, output, delay=0.7, atten=4) |
| |
| Yet another variation is to import the desired function or variable directly:: |
| |
n | from Sound.Effects.echo import echofilter |
n | from sound.effects.echo import echofilter |
| |
| Again, this loads the submodule :mod:`echo`, but this makes its function |
| :func:`echofilter` directly available:: |
| |
| echofilter(input, output, delay=0.7, atten=4) |
| |
| Note that when using ``from package import item``, the item can be either a |
| submodule (or subpackage) of the package, or some other name defined in the |
| |
| .. _tut-pkg-import-star: |
| |
| Importing \* From a Package |
| --------------------------- |
| |
| .. index:: single: __all__ |
| |
n | Now what happens when the user writes ``from Sound.Effects import *``? Ideally, |
n | Now what happens when the user writes ``from sound.effects import *``? Ideally, |
| one would hope that this somehow goes out to the filesystem, finds which |
| submodules are present in the package, and imports them all. Unfortunately, |
n | this operation does not work very well on Mac and Windows platforms, where the |
n | this operation does not work very well on Windows platforms, where the |
| filesystem does not always have accurate information about the case of a |
| filename! On these platforms, there is no guaranteed way to know whether a file |
| :file:`ECHO.PY` should be imported as a module :mod:`echo`, :mod:`Echo` or |
| :mod:`ECHO`. (For example, Windows 95 has the annoying practice of showing all |
| file names with a capitalized first letter.) The DOS 8+3 filename restriction |
| adds another interesting problem for long module names. |
n | |
| .. % The \code{__all__} Attribute |
| |
| The only solution is for the package author to provide an explicit index of the |
| package. The import statement uses the following convention: if a package's |
| :file:`__init__.py` code defines a list named ``__all__``, it is taken to be the |
| list of module names that should be imported when ``from package import *`` is |
| encountered. It is up to the package author to keep this list up-to-date when a |
| new version of the package is released. Package authors may also decide not to |
| support it, if they don't see a use for importing \* from their package. For |
n | example, the file :file:`Sounds/Effects/__init__.py` could contain the following |
n | example, the file :file:`sounds/effects/__init__.py` could contain the following |
| code:: |
| |
| __all__ = ["echo", "surround", "reverse"] |
| |
n | This would mean that ``from Sound.Effects import *`` would import the three |
n | This would mean that ``from sound.effects import *`` would import the three |
| named submodules of the :mod:`Sound` package. |
| named submodules of the :mod:`sound` package. |
| |
n | If ``__all__`` is not defined, the statement ``from Sound.Effects import *`` |
n | If ``__all__`` is not defined, the statement ``from sound.effects import *`` |
| does *not* import all submodules from the package :mod:`Sound.Effects` into the |
| does *not* import all submodules from the package :mod:`sound.effects` into the |
| current namespace; it only ensures that the package :mod:`Sound.Effects` has |
| current namespace; it only ensures that the package :mod:`sound.effects` has |
| been imported (possibly running any initialization code in :file:`__init__.py`) |
| and then imports whatever names are defined in the package. This includes any |
| names defined (and submodules explicitly loaded) by :file:`__init__.py`. It |
| also includes any submodules of the package that were explicitly loaded by |
| previous import statements. Consider this code:: |
| |
n | import Sound.Effects.echo |
n | import sound.effects.echo |
| import Sound.Effects.surround |
| import sound.effects.surround |
| from Sound.Effects import * |
| from sound.effects import * |
| |
| In this example, the echo and surround modules are imported in the current |
n | namespace because they are defined in the :mod:`Sound.Effects` package when the |
n | namespace because they are defined in the :mod:`sound.effects` package when the |
| ``from...import`` statement is executed. (This also works when ``__all__`` is |
| defined.) |
| |
| Note that in general the practice of importing ``*`` from a module or package is |
| frowned upon, since it often causes poorly readable code. However, it is okay to |
| use it to save typing in interactive sessions, and certain modules are designed |
| to export only names that follow certain patterns. |
| |
| :mod:`surround` module might use the :mod:`echo` module. In fact, such |
| references are so common that the :keyword:`import` statement first looks in the |
| containing package before looking in the standard module search path. Thus, the |
| :mod:`surround` module can simply use ``import echo`` or ``from echo import |
| echofilter``. If the imported module is not found in the current package (the |
| package of which the current module is a submodule), the :keyword:`import` |
| statement looks for a top-level module with the given name. |
| |
n | When packages are structured into subpackages (as with the :mod:`Sound` package |
n | When packages are structured into subpackages (as with the :mod:`sound` package |
| in the example), there's no shortcut to refer to submodules of sibling packages |
| in the example), you can use absolute imports to refer to submodules of siblings |
| - the full name of the subpackage must be used. For example, if the module |
| packages. For example, if the module :mod:`sound.filters.vocoder` needs to use |
| :mod:`Sound.Filters.vocoder` needs to use the :mod:`echo` module in the |
| the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from |
| :mod:`Sound.Effects` package, it can use ``from Sound.Effects import echo``. |
| sound.effects import echo``. |
| |
| Starting with Python 2.5, in addition to the implicit relative imports described |
| above, you can write explicit relative imports with the ``from module import |
| name`` form of import statement. These explicit relative imports use leading |
| dots to indicate the current and parent packages involved in the relative |
| import. From the :mod:`surround` module for example, you might use:: |
| |
| from . import echo |
t | from .. import Formats |
t | from .. import formats |
| from ..Filters import equalizer |
| from ..filters import equalizer |
| |
| Note that both explicit and implicit relative imports are based on the name of |
| the current module. Since the name of the main module is always ``"__main__"``, |
| modules intended for use as the main module of a Python application should |
| always use absolute imports. |
| |
| |
| Packages in Multiple Directories |