# SOME DESCRIPTIVE TITLE. # Copyright (C) 2001-2016, Python Software Foundation # This file is distributed under the same license as the Python package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Python 3.6\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2017-04-02 22:11+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: fr\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../Doc/reference/import.rst:6 msgid "The import system" msgstr "" #: ../Doc/reference/import.rst:10 msgid "" "Python code in one :term:`module` gains access to the code in another module " "by the process of :term:`importing` it. The :keyword:`import` statement is " "the most common way of invoking the import machinery, but it is not the only " "way. Functions such as :func:`importlib.import_module` and built-in :func:" "`__import__` can also be used to invoke the import machinery." msgstr "" #: ../Doc/reference/import.rst:16 msgid "" "The :keyword:`import` statement combines two operations; it searches for the " "named module, then it binds the results of that search to a name in the " "local scope. The search operation of the :keyword:`import` statement is " "defined as a call to the :func:`__import__` function, with the appropriate " "arguments. The return value of :func:`__import__` is used to perform the " "name binding operation of the :keyword:`import` statement. See the :keyword:" "`import` statement for the exact details of that name binding operation." msgstr "" #: ../Doc/reference/import.rst:25 msgid "" "A direct call to :func:`__import__` performs only the module search and, if " "found, the module creation operation. While certain side-effects may occur, " "such as the importing of parent packages, and the updating of various caches " "(including :data:`sys.modules`), only the :keyword:`import` statement " "performs a name binding operation." msgstr "" #: ../Doc/reference/import.rst:31 msgid "" "When calling :func:`__import__` as part of an import statement, the standard " "builtin :func:`__import__` is called. Other mechanisms for invoking the " "import system (such as :func:`importlib.import_module`) may choose to " "subvert :func:`__import__` and use its own solution to implement import " "semantics." msgstr "" #: ../Doc/reference/import.rst:37 msgid "" "When a module is first imported, Python searches for the module and if " "found, it creates a module object [#fnmo]_, initializing it. If the named " "module cannot be found, an :exc:`ModuleNotFoundError` is raised. Python " "implements various strategies to search for the named module when the import " "machinery is invoked. These strategies can be modified and extended by " "using various hooks described in the sections below." msgstr "" #: ../Doc/reference/import.rst:44 msgid "" "The import system has been updated to fully implement the second phase of :" "pep:`302`. There is no longer any implicit import machinery - the full " "import system is exposed through :data:`sys.meta_path`. In addition, native " "namespace package support has been implemented (see :pep:`420`)." msgstr "" #: ../Doc/reference/import.rst:52 msgid ":mod:`importlib`" msgstr "" #: ../Doc/reference/import.rst:54 msgid "" "The :mod:`importlib` module provides a rich API for interacting with the " "import system. For example :func:`importlib.import_module` provides a " "recommended, simpler API than built-in :func:`__import__` for invoking the " "import machinery. Refer to the :mod:`importlib` library documentation for " "additional detail." msgstr "" #: ../Doc/reference/import.rst:63 msgid "Packages" msgstr "Les paquets" #: ../Doc/reference/import.rst:68 msgid "" "Python has only one type of module object, and all modules are of this type, " "regardless of whether the module is implemented in Python, C, or something " "else. To help organize modules and provide a naming hierarchy, Python has a " "concept of :term:`packages `." msgstr "" #: ../Doc/reference/import.rst:73 msgid "" "You can think of packages as the directories on a file system and modules as " "files within directories, but don't take this analogy too literally since " "packages and modules need not originate from the file system. For the " "purposes of this documentation, we'll use this convenient analogy of " "directories and files. Like file system directories, packages are organized " "hierarchically, and packages may themselves contain subpackages, as well as " "regular modules." msgstr "" #: ../Doc/reference/import.rst:81 msgid "" "It's important to keep in mind that all packages are modules, but not all " "modules are packages. Or put another way, packages are just a special kind " "of module. Specifically, any module that contains a ``__path__`` attribute " "is considered a package." msgstr "" #: ../Doc/reference/import.rst:86 msgid "" "All modules have a name. Subpackage names are separated from their parent " "package name by dots, akin to Python's standard attribute access syntax. " "Thus you might have a module called :mod:`sys` and a package called :mod:" "`email`, which in turn has a subpackage called :mod:`email.mime` and a " "module within that subpackage called :mod:`email.mime.text`." msgstr "" #: ../Doc/reference/import.rst:94 msgid "Regular packages" msgstr "" #: ../Doc/reference/import.rst:99 msgid "" "Python defines two types of packages, :term:`regular packages ` and :term:`namespace packages `. Regular " "packages are traditional packages as they existed in Python 3.2 and earlier. " "A regular package is typically implemented as a directory containing an " "``__init__.py`` file. When a regular package is imported, this ``__init__." "py`` file is implicitly executed, and the objects it defines are bound to " "names in the package's namespace. The ``__init__.py`` file can contain the " "same Python code that any other module can contain, and Python will add some " "additional attributes to the module when it is imported." msgstr "" #: ../Doc/reference/import.rst:109 msgid "" "For example, the following file system layout defines a top level ``parent`` " "package with three subpackages::" msgstr "" #: ../Doc/reference/import.rst:121 msgid "" "Importing ``parent.one`` will implicitly execute ``parent/__init__.py`` and " "``parent/one/__init__.py``. Subsequent imports of ``parent.two`` or " "``parent.three`` will execute ``parent/two/__init__.py`` and ``parent/three/" "__init__.py`` respectively." msgstr "" #: ../Doc/reference/import.rst:128 msgid "Namespace packages" msgstr "" #: ../Doc/reference/import.rst:134 msgid "" "A namespace package is a composite of various :term:`portions `, " "where each portion contributes a subpackage to the parent package. Portions " "may reside in different locations on the file system. Portions may also be " "found in zip files, on the network, or anywhere else that Python searches " "during import. Namespace packages may or may not correspond directly to " "objects on the file system; they may be virtual modules that have no " "concrete representation." msgstr "" #: ../Doc/reference/import.rst:142 msgid "" "Namespace packages do not use an ordinary list for their ``__path__`` " "attribute. They instead use a custom iterable type which will automatically " "perform a new search for package portions on the next import attempt within " "that package if the path of their parent package (or :data:`sys.path` for a " "top level package) changes." msgstr "" #: ../Doc/reference/import.rst:148 msgid "" "With namespace packages, there is no ``parent/__init__.py`` file. In fact, " "there may be multiple ``parent`` directories found during import search, " "where each one is provided by a different portion. Thus ``parent/one`` may " "not be physically located next to ``parent/two``. In this case, Python will " "create a namespace package for the top-level ``parent`` package whenever it " "or one of its subpackages is imported." msgstr "" #: ../Doc/reference/import.rst:155 msgid "See also :pep:`420` for the namespace package specification." msgstr "" #: ../Doc/reference/import.rst:159 msgid "Searching" msgstr "" #: ../Doc/reference/import.rst:161 msgid "" "To begin the search, Python needs the :term:`fully qualified ` name of the module (or package, but for the purposes of this " "discussion, the difference is immaterial) being imported. This name may " "come from various arguments to the :keyword:`import` statement, or from the " "parameters to the :func:`importlib.import_module` or :func:`__import__` " "functions." msgstr "" #: ../Doc/reference/import.rst:167 msgid "" "This name will be used in various phases of the import search, and it may be " "the dotted path to a submodule, e.g. ``foo.bar.baz``. In this case, Python " "first tries to import ``foo``, then ``foo.bar``, and finally ``foo.bar." "baz``. If any of the intermediate imports fail, an :exc:" "`ModuleNotFoundError` is raised." msgstr "" #: ../Doc/reference/import.rst:174 msgid "The module cache" msgstr "" #: ../Doc/reference/import.rst:179 msgid "" "The first place checked during import search is :data:`sys.modules`. This " "mapping serves as a cache of all modules that have been previously imported, " "including the intermediate paths. So if ``foo.bar.baz`` was previously " "imported, :data:`sys.modules` will contain entries for ``foo``, ``foo.bar``, " "and ``foo.bar.baz``. Each key will have as its value the corresponding " "module object." msgstr "" #: ../Doc/reference/import.rst:186 msgid "" "During import, the module name is looked up in :data:`sys.modules` and if " "present, the associated value is the module satisfying the import, and the " "process completes. However, if the value is ``None``, then an :exc:" "`ModuleNotFoundError` is raised. If the module name is missing, Python will " "continue searching for the module." msgstr "" #: ../Doc/reference/import.rst:192 msgid "" ":data:`sys.modules` is writable. Deleting a key may not destroy the " "associated module (as other modules may hold references to it), but it will " "invalidate the cache entry for the named module, causing Python to search " "anew for the named module upon its next import. The key can also be assigned " "to ``None``, forcing the next import of the module to result in an :exc:" "`ModuleNotFoundError`." msgstr "" #: ../Doc/reference/import.rst:199 msgid "" "Beware though, as if you keep a reference to the module object, invalidate " "its cache entry in :data:`sys.modules`, and then re-import the named module, " "the two module objects will *not* be the same. By contrast, :func:`importlib." "reload` will reuse the *same* module object, and simply reinitialise the " "module contents by rerunning the module's code." msgstr "" #: ../Doc/reference/import.rst:207 msgid "Finders and loaders" msgstr "" #: ../Doc/reference/import.rst:214 msgid "" "If the named module is not found in :data:`sys.modules`, then Python's " "import protocol is invoked to find and load the module. This protocol " "consists of two conceptual objects, :term:`finders ` and :term:" "`loaders `. A finder's job is to determine whether it can find the " "named module using whatever strategy it knows about. Objects that implement " "both of these interfaces are referred to as :term:`importers ` - " "they return themselves when they find that they can load the requested " "module." msgstr "" #: ../Doc/reference/import.rst:222 msgid "" "Python includes a number of default finders and importers. The first one " "knows how to locate built-in modules, and the second knows how to locate " "frozen modules. A third default finder searches an :term:`import path` for " "modules. The :term:`import path` is a list of locations that may name file " "system paths or zip files. It can also be extended to search for any " "locatable resource, such as those identified by URLs." msgstr "" #: ../Doc/reference/import.rst:229 msgid "" "The import machinery is extensible, so new finders can be added to extend " "the range and scope of module searching." msgstr "" #: ../Doc/reference/import.rst:232 msgid "" "Finders do not actually load modules. If they can find the named module, " "they return a :dfn:`module spec`, an encapsulation of the module's import-" "related information, which the import machinery then uses when loading the " "module." msgstr "" #: ../Doc/reference/import.rst:236 msgid "" "The following sections describe the protocol for finders and loaders in more " "detail, including how you can create and register new ones to extend the " "import machinery." msgstr "" #: ../Doc/reference/import.rst:240 msgid "" "In previous versions of Python, finders returned :term:`loaders ` " "directly, whereas now they return module specs which *contain* loaders. " "Loaders are still used during import but have fewer responsibilities." msgstr "" #: ../Doc/reference/import.rst:246 msgid "Import hooks" msgstr "" #: ../Doc/reference/import.rst:256 msgid "" "The import machinery is designed to be extensible; the primary mechanism for " "this are the *import hooks*. There are two types of import hooks: *meta " "hooks* and *import path hooks*." msgstr "" #: ../Doc/reference/import.rst:260 msgid "" "Meta hooks are called at the start of import processing, before any other " "import processing has occurred, other than :data:`sys.modules` cache look " "up. This allows meta hooks to override :data:`sys.path` processing, frozen " "modules, or even built-in modules. Meta hooks are registered by adding new " "finder objects to :data:`sys.meta_path`, as described below." msgstr "" #: ../Doc/reference/import.rst:266 msgid "" "Import path hooks are called as part of :data:`sys.path` (or ``package." "__path__``) processing, at the point where their associated path item is " "encountered. Import path hooks are registered by adding new callables to :" "data:`sys.path_hooks` as described below." msgstr "" #: ../Doc/reference/import.rst:273 msgid "The meta path" msgstr "" #: ../Doc/reference/import.rst:279 msgid "" "When the named module is not found in :data:`sys.modules`, Python next " "searches :data:`sys.meta_path`, which contains a list of meta path finder " "objects. These finders are queried in order to see if they know how to " "handle the named module. Meta path finders must implement a method called :" "meth:`~importlib.abc.MetaPathFinder.find_spec()` which takes three " "arguments: a name, an import path, and (optionally) a target module. The " "meta path finder can use any strategy it wants to determine whether it can " "handle the named module or not." msgstr "" #: ../Doc/reference/import.rst:288 msgid "" "If the meta path finder knows how to handle the named module, it returns a " "spec object. If it cannot handle the named module, it returns ``None``. " "If :data:`sys.meta_path` processing reaches the end of its list without " "returning a spec, then a :exc:`ModuleNotFoundError` is raised. Any other " "exceptions raised are simply propagated up, aborting the import process." msgstr "" #: ../Doc/reference/import.rst:294 msgid "" "The :meth:`~importlib.abc.MetaPathFinder.find_spec()` method of meta path " "finders is called with two or three arguments. The first is the fully " "qualified name of the module being imported, for example ``foo.bar.baz``. " "The second argument is the path entries to use for the module search. For " "top-level modules, the second argument is ``None``, but for submodules or " "subpackages, the second argument is the value of the parent package's " "``__path__`` attribute. If the appropriate ``__path__`` attribute cannot be " "accessed, an :exc:`ModuleNotFoundError` is raised. The third argument is an " "existing module object that will be the target of loading later. The import " "system passes in a target module only during reload." msgstr "" #: ../Doc/reference/import.rst:305 msgid "" "The meta path may be traversed multiple times for a single import request. " "For example, assuming none of the modules involved has already been cached, " "importing ``foo.bar.baz`` will first perform a top level import, calling " "``mpf.find_spec(\"foo\", None, None)`` on each meta path finder (``mpf``). " "After ``foo`` has been imported, ``foo.bar`` will be imported by traversing " "the meta path a second time, calling ``mpf.find_spec(\"foo.bar\", foo." "__path__, None)``. Once ``foo.bar`` has been imported, the final traversal " "will call ``mpf.find_spec(\"foo.bar.baz\", foo.bar.__path__, None)``." msgstr "" #: ../Doc/reference/import.rst:315 msgid "" "Some meta path finders only support top level imports. These importers will " "always return ``None`` when anything other than ``None`` is passed as the " "second argument." msgstr "" #: ../Doc/reference/import.rst:319 msgid "" "Python's default :data:`sys.meta_path` has three meta path finders, one that " "knows how to import built-in modules, one that knows how to import frozen " "modules, and one that knows how to import modules from an :term:`import " "path` (i.e. the :term:`path based finder`)." msgstr "" #: ../Doc/reference/import.rst:324 msgid "" "The :meth:`~importlib.abc.MetaPathFinder.find_spec` method of meta path " "finders replaced :meth:`~importlib.abc.MetaPathFinder.find_module`, which is " "now deprecated. While it will continue to work without change, the import " "machinery will try it only if the finder does not implement ``find_spec()``." msgstr "" #: ../Doc/reference/import.rst:333 msgid "Loading" msgstr "" #: ../Doc/reference/import.rst:335 msgid "" "If and when a module spec is found, the import machinery will use it (and " "the loader it contains) when loading the module. Here is an approximation " "of what happens during the loading portion of import::" msgstr "" #: ../Doc/reference/import.rst:370 msgid "Note the following details:" msgstr "" #: ../Doc/reference/import.rst:372 msgid "" "If there is an existing module object with the given name in :data:`sys." "modules`, import will have already returned it." msgstr "" #: ../Doc/reference/import.rst:375 msgid "" "The module will exist in :data:`sys.modules` before the loader executes the " "module code. This is crucial because the module code may (directly or " "indirectly) import itself; adding it to :data:`sys.modules` beforehand " "prevents unbounded recursion in the worst case and multiple loading in the " "best." msgstr "" #: ../Doc/reference/import.rst:381 msgid "" "If loading fails, the failing module -- and only the failing module -- gets " "removed from :data:`sys.modules`. Any module already in the :data:`sys." "modules` cache, and any module that was successfully loaded as a side-" "effect, must remain in the cache. This contrasts with reloading where even " "the failing module is left in :data:`sys.modules`." msgstr "" #: ../Doc/reference/import.rst:387 msgid "" "After the module is created but before execution, the import machinery sets " "the import-related module attributes (\"_init_module_attrs\" in the pseudo-" "code example above), as summarized in a :ref:`later section `." msgstr "" #: ../Doc/reference/import.rst:392 msgid "" "Module execution is the key moment of loading in which the module's " "namespace gets populated. Execution is entirely delegated to the loader, " "which gets to decide what gets populated and how." msgstr "" #: ../Doc/reference/import.rst:396 msgid "" "The module created during loading and passed to exec_module() may not be the " "one returned at the end of import [#fnlo]_." msgstr "" #: ../Doc/reference/import.rst:399 msgid "" "The import system has taken over the boilerplate responsibilities of " "loaders. These were previously performed by the :meth:`importlib.abc.Loader." "load_module` method." msgstr "" #: ../Doc/reference/import.rst:405 msgid "Loaders" msgstr "" #: ../Doc/reference/import.rst:407 msgid "" "Module loaders provide the critical function of loading: module execution. " "The import machinery calls the :meth:`importlib.abc.Loader.exec_module` " "method with a single argument, the module object to execute. Any value " "returned from :meth:`~importlib.abc.Loader.exec_module` is ignored." msgstr "" #: ../Doc/reference/import.rst:412 msgid "Loaders must satisfy the following requirements:" msgstr "" #: ../Doc/reference/import.rst:414 msgid "" "If the module is a Python module (as opposed to a built-in module or a " "dynamically loaded extension), the loader should execute the module's code " "in the module's global name space (``module.__dict__``)." msgstr "" #: ../Doc/reference/import.rst:418 msgid "" "If the loader cannot execute the module, it should raise an :exc:" "`ImportError`, although any other exception raised during :meth:`~importlib." "abc.Loader.exec_module` will be propagated." msgstr "" #: ../Doc/reference/import.rst:422 msgid "" "In many cases, the finder and loader can be the same object; in such cases " "the :meth:`~importlib.abc.MetaPathFinder.find_spec` method would just return " "a spec with the loader set to ``self``." msgstr "" #: ../Doc/reference/import.rst:426 msgid "" "Module loaders may opt in to creating the module object during loading by " "implementing a :meth:`~importlib.abc.Loader.create_module` method. It takes " "one argument, the module spec, and returns the new module object to use " "during loading. ``create_module()`` does not need to set any attributes on " "the module object. If the method returns ``None``, the import machinery " "will create the new module itself." msgstr "" #: ../Doc/reference/import.rst:433 msgid "The :meth:`~importlib.abc.Loader.create_module` method of loaders." msgstr "" #: ../Doc/reference/import.rst:436 msgid "" "The :meth:`~importlib.abc.Loader.load_module` method was replaced by :meth:" "`~importlib.abc.Loader.exec_module` and the import machinery assumed all the " "boilerplate responsibilities of loading." msgstr "" #: ../Doc/reference/import.rst:441 msgid "" "For compatibility with existing loaders, the import machinery will use the " "``load_module()`` method of loaders if it exists and the loader does not " "also implement ``exec_module()``. However, ``load_module()`` has been " "deprecated and loaders should implement ``exec_module()`` instead." msgstr "" #: ../Doc/reference/import.rst:446 msgid "" "The ``load_module()`` method must implement all the boilerplate loading " "functionality described above in addition to executing the module. All the " "same constraints apply, with some additional clarification:" msgstr "" #: ../Doc/reference/import.rst:450 msgid "" "If there is an existing module object with the given name in :data:`sys." "modules`, the loader must use that existing module. (Otherwise, :func:" "`importlib.reload` will not work correctly.) If the named module does not " "exist in :data:`sys.modules`, the loader must create a new module object and " "add it to :data:`sys.modules`." msgstr "" #: ../Doc/reference/import.rst:456 msgid "" "The module *must* exist in :data:`sys.modules` before the loader executes " "the module code, to prevent unbounded recursion or multiple loading." msgstr "" #: ../Doc/reference/import.rst:460 msgid "" "If loading fails, the loader must remove any modules it has inserted into :" "data:`sys.modules`, but it must remove **only** the failing module(s), and " "only if the loader itself has loaded the module(s) explicitly." msgstr "" #: ../Doc/reference/import.rst:465 msgid "" "A :exc:`DeprecationWarning` is raised when ``exec_module()`` is defined but " "``create_module()`` is not." msgstr "" #: ../Doc/reference/import.rst:469 msgid "" "An :exc:`ImportError` is raised when ``exec_module()`` is defined but " "``create_module()`` is not." msgstr "" #: ../Doc/reference/import.rst:474 msgid "Submodules" msgstr "" #: ../Doc/reference/import.rst:476 msgid "" "When a submodule is loaded using any mechanism (e.g. ``importlib`` APIs, the " "``import`` or ``import-from`` statements, or built-in ``__import__()``) a " "binding is placed in the parent module's namespace to the submodule object. " "For example, if package ``spam`` has a submodule ``foo``, after importing " "``spam.foo``, ``spam`` will have an attribute ``foo`` which is bound to the " "submodule. Let's say you have the following directory structure::" msgstr "" #: ../Doc/reference/import.rst:488 msgid "and ``spam/__init__.py`` has the following lines in it::" msgstr "" #: ../Doc/reference/import.rst:493 msgid "" "then executing the following puts a name binding to ``foo`` and ``bar`` in " "the ``spam`` module::" msgstr "" #: ../Doc/reference/import.rst:502 msgid "" "Given Python's familiar name binding rules this might seem surprising, but " "it's actually a fundamental feature of the import system. The invariant " "holding is that if you have ``sys.modules['spam']`` and ``sys.modules['spam." "foo']`` (as you would after the above import), the latter must appear as the " "``foo`` attribute of the former." msgstr "" #: ../Doc/reference/import.rst:509 msgid "Module spec" msgstr "" #: ../Doc/reference/import.rst:511 msgid "" "The import machinery uses a variety of information about each module during " "import, especially before loading. Most of the information is common to all " "modules. The purpose of a module's spec is to encapsulate this import-" "related information on a per-module basis." msgstr "" #: ../Doc/reference/import.rst:516 msgid "" "Using a spec during import allows state to be transferred between import " "system components, e.g. between the finder that creates the module spec and " "the loader that executes it. Most importantly, it allows the import " "machinery to perform the boilerplate operations of loading, whereas without " "a module spec the loader had that responsibility." msgstr "" #: ../Doc/reference/import.rst:522 msgid "" "See :class:`~importlib.machinery.ModuleSpec` for more specifics on what " "information a module's spec may hold." msgstr "" #: ../Doc/reference/import.rst:530 msgid "Import-related module attributes" msgstr "" #: ../Doc/reference/import.rst:532 msgid "" "The import machinery fills in these attributes on each module object during " "loading, based on the module's spec, before the loader executes the module." msgstr "" #: ../Doc/reference/import.rst:538 msgid "" "The ``__name__`` attribute must be set to the fully-qualified name of the " "module. This name is used to uniquely identify the module in the import " "system." msgstr "" #: ../Doc/reference/import.rst:544 msgid "" "The ``__loader__`` attribute must be set to the loader object that the " "import machinery used when loading the module. This is mostly for " "introspection, but can be used for additional loader-specific functionality, " "for example getting data associated with a loader." msgstr "" #: ../Doc/reference/import.rst:551 msgid "" "The module's ``__package__`` attribute must be set. Its value must be a " "string, but it can be the same value as its ``__name__``. When the module " "is a package, its ``__package__`` value should be set to its ``__name__``. " "When the module is not a package, ``__package__`` should be set to the empty " "string for top-level modules, or for submodules, to the parent package's " "name. See :pep:`366` for further details." msgstr "" #: ../Doc/reference/import.rst:559 msgid "" "This attribute is used instead of ``__name__`` to calculate explicit " "relative imports for main modules, as defined in :pep:`366`. It is expected " "to have the same value as ``__spec__.parent``." msgstr "" #: ../Doc/reference/import.rst:563 msgid "" "The value of ``__package__`` is expected to be the same as ``__spec__." "parent``." msgstr "" #: ../Doc/reference/import.rst:569 msgid "" "The ``__spec__`` attribute must be set to the module spec that was used when " "importing the module. Setting ``__spec__`` appropriately applies equally to :" "ref:`modules initialized during interpreter startup `. The one " "exception is ``__main__``, where ``__spec__`` is :ref:`set to None in some " "cases `." msgstr "" #: ../Doc/reference/import.rst:575 msgid "" "When ``__package__`` is not defined, ``__spec__.parent`` is used as a " "fallback." msgstr "" #: ../Doc/reference/import.rst:580 msgid "" "``__spec__.parent`` is used as a fallback when ``__package__`` is not " "defined." msgstr "" #: ../Doc/reference/import.rst:586 msgid "" "If the module is a package (either regular or namespace), the module " "object's ``__path__`` attribute must be set. The value must be iterable, " "but may be empty if ``__path__`` has no further significance. If " "``__path__`` is not empty, it must produce strings when iterated over. More " "details on the semantics of ``__path__`` are given :ref:`below `." msgstr "" #: ../Doc/reference/import.rst:593 msgid "Non-package modules should not have a ``__path__`` attribute." msgstr "" #: ../Doc/reference/import.rst:598 msgid "" "``__file__`` is optional. If set, this attribute's value must be a string. " "The import system may opt to leave ``__file__`` unset if it has no semantic " "meaning (e.g. a module loaded from a database)." msgstr "" #: ../Doc/reference/import.rst:602 msgid "" "If ``__file__`` is set, it may also be appropriate to set the ``__cached__`` " "attribute which is the path to any compiled version of the code (e.g. byte-" "compiled file). The file does not need to exist to set this attribute; the " "path can simply point to where the compiled file would exist (see :pep:" "`3147`)." msgstr "" #: ../Doc/reference/import.rst:608 msgid "" "It is also appropriate to set ``__cached__`` when ``__file__`` is not set. " "However, that scenario is quite atypical. Ultimately, the loader is what " "makes use of ``__file__`` and/or ``__cached__``. So if a loader can load " "from a cached module but otherwise does not load from a file, that atypical " "scenario may be appropriate." msgstr "" #: ../Doc/reference/import.rst:617 msgid "module.__path__" msgstr "" #: ../Doc/reference/import.rst:619 msgid "" "By definition, if a module has an ``__path__`` attribute, it is a package, " "regardless of its value." msgstr "" #: ../Doc/reference/import.rst:622 msgid "" "A package's ``__path__`` attribute is used during imports of its " "subpackages. Within the import machinery, it functions much the same as :" "data:`sys.path`, i.e. providing a list of locations to search for modules " "during import. However, ``__path__`` is typically much more constrained " "than :data:`sys.path`." msgstr "" #: ../Doc/reference/import.rst:628 msgid "" "``__path__`` must be an iterable of strings, but it may be empty. The same " "rules used for :data:`sys.path` also apply to a package's ``__path__``, and :" "data:`sys.path_hooks` (described below) are consulted when traversing a " "package's ``__path__``." msgstr "" #: ../Doc/reference/import.rst:633 msgid "" "A package's ``__init__.py`` file may set or alter the package's ``__path__`` " "attribute, and this was typically the way namespace packages were " "implemented prior to :pep:`420`. With the adoption of :pep:`420`, namespace " "packages no longer need to supply ``__init__.py`` files containing only " "``__path__`` manipulation code; the import machinery automatically sets " "``__path__`` correctly for the namespace package." msgstr "" #: ../Doc/reference/import.rst:641 msgid "Module reprs" msgstr "" #: ../Doc/reference/import.rst:643 msgid "" "By default, all modules have a usable repr, however depending on the " "attributes set above, and in the module's spec, you can more explicitly " "control the repr of module objects." msgstr "" #: ../Doc/reference/import.rst:647 msgid "" "If the module has a spec (``__spec__``), the import machinery will try to " "generate a repr from it. If that fails or there is no spec, the import " "system will craft a default repr using whatever information is available on " "the module. It will try to use the ``module.__name__``, ``module." "__file__``, and ``module.__loader__`` as input into the repr, with defaults " "for whatever information is missing." msgstr "" #: ../Doc/reference/import.rst:654 msgid "Here are the exact rules used:" msgstr "" #: ../Doc/reference/import.rst:656 msgid "" "If the module has a ``__spec__`` attribute, the information in the spec is " "used to generate the repr. The \"name\", \"loader\", \"origin\", and " "\"has_location\" attributes are consulted." msgstr "" #: ../Doc/reference/import.rst:660 msgid "" "If the module has a ``__file__`` attribute, this is used as part of the " "module's repr." msgstr "" #: ../Doc/reference/import.rst:663 msgid "" "If the module has no ``__file__`` but does have a ``__loader__`` that is not " "``None``, then the loader's repr is used as part of the module's repr." msgstr "" #: ../Doc/reference/import.rst:666 msgid "Otherwise, just use the module's ``__name__`` in the repr." msgstr "" #: ../Doc/reference/import.rst:668 msgid "" "Use of :meth:`loader.module_repr() ` has " "been deprecated and the module spec is now used by the import machinery to " "generate a module repr." msgstr "" #: ../Doc/reference/import.rst:673 msgid "" "For backward compatibility with Python 3.3, the module repr will be " "generated by calling the loader's :meth:`~importlib.abc.Loader.module_repr` " "method, if defined, before trying either approach described above. However, " "the method is deprecated." msgstr "" #: ../Doc/reference/import.rst:680 msgid "The Path Based Finder" msgstr "" #: ../Doc/reference/import.rst:685 msgid "" "As mentioned previously, Python comes with several default meta path " "finders. One of these, called the :term:`path based finder` (:class:" "`~importlib.machinery.PathFinder`), searches an :term:`import path`, which " "contains a list of :term:`path entries `. Each path entry names " "a location to search for modules." msgstr "" #: ../Doc/reference/import.rst:691 msgid "" "The path based finder itself doesn't know how to import anything. Instead, " "it traverses the individual path entries, associating each of them with a " "path entry finder that knows how to handle that particular kind of path." msgstr "" #: ../Doc/reference/import.rst:695 msgid "" "The default set of path entry finders implement all the semantics for " "finding modules on the file system, handling special file types such as " "Python source code (``.py`` files), Python byte code (``.pyc`` files) and " "shared libraries (e.g. ``.so`` files). When supported by the :mod:" "`zipimport` module in the standard library, the default path entry finders " "also handle loading all of these file types (other than shared libraries) " "from zipfiles." msgstr "" #: ../Doc/reference/import.rst:702 msgid "" "Path entries need not be limited to file system locations. They can refer " "to URLs, database queries, or any other location that can be specified as a " "string." msgstr "" #: ../Doc/reference/import.rst:706 msgid "" "The path based finder provides additional hooks and protocols so that you " "can extend and customize the types of searchable path entries. For example, " "if you wanted to support path entries as network URLs, you could write a " "hook that implements HTTP semantics to find modules on the web. This hook " "(a callable) would return a :term:`path entry finder` supporting the " "protocol described below, which was then used to get a loader for the module " "from the web." msgstr "" #: ../Doc/reference/import.rst:714 msgid "" "A word of warning: this section and the previous both use the term *finder*, " "distinguishing between them by using the terms :term:`meta path finder` and :" "term:`path entry finder`. These two types of finders are very similar, " "support similar protocols, and function in similar ways during the import " "process, but it's important to keep in mind that they are subtly different. " "In particular, meta path finders operate at the beginning of the import " "process, as keyed off the :data:`sys.meta_path` traversal." msgstr "" #: ../Doc/reference/import.rst:722 msgid "" "By contrast, path entry finders are in a sense an implementation detail of " "the path based finder, and in fact, if the path based finder were to be " "removed from :data:`sys.meta_path`, none of the path entry finder semantics " "would be invoked." msgstr "" #: ../Doc/reference/import.rst:729 msgid "Path entry finders" msgstr "" #: ../Doc/reference/import.rst:737 msgid "" "The :term:`path based finder` is responsible for finding and loading Python " "modules and packages whose location is specified with a string :term:`path " "entry`. Most path entries name locations in the file system, but they need " "not be limited to this." msgstr "" #: ../Doc/reference/import.rst:742 msgid "" "As a meta path finder, the :term:`path based finder` implements the :meth:" "`~importlib.abc.MetaPathFinder.find_spec` protocol previously described, " "however it exposes additional hooks that can be used to customize how " "modules are found and loaded from the :term:`import path`." msgstr "" #: ../Doc/reference/import.rst:747 msgid "" "Three variables are used by the :term:`path based finder`, :data:`sys." "path`, :data:`sys.path_hooks` and :data:`sys.path_importer_cache`. The " "``__path__`` attributes on package objects are also used. These provide " "additional ways that the import machinery can be customized." msgstr "" #: ../Doc/reference/import.rst:752 msgid "" ":data:`sys.path` contains a list of strings providing search locations for " "modules and packages. It is initialized from the :data:`PYTHONPATH` " "environment variable and various other installation- and implementation-" "specific defaults. Entries in :data:`sys.path` can name directories on the " "file system, zip files, and potentially other \"locations\" (see the :mod:" "`site` module) that should be searched for modules, such as URLs, or " "database queries. Only strings and bytes should be present on :data:`sys." "path`; all other data types are ignored. The encoding of bytes entries is " "determined by the individual :term:`path entry finders `." msgstr "" #: ../Doc/reference/import.rst:763 msgid "" "The :term:`path based finder` is a :term:`meta path finder`, so the import " "machinery begins the :term:`import path` search by calling the path based " "finder's :meth:`~importlib.machinery.PathFinder.find_spec` method as " "described previously. When the ``path`` argument to :meth:`~importlib." "machinery.PathFinder.find_spec` is given, it will be a list of string paths " "to traverse - typically a package's ``__path__`` attribute for an import " "within that package. If the ``path`` argument is ``None``, this indicates a " "top level import and :data:`sys.path` is used." msgstr "" #: ../Doc/reference/import.rst:772 msgid "" "The path based finder iterates over every entry in the search path, and for " "each of these, looks for an appropriate :term:`path entry finder` (:class:" "`~importlib.abc.PathEntryFinder`) for the path entry. Because this can be " "an expensive operation (e.g. there may be `stat()` call overheads for this " "search), the path based finder maintains a cache mapping path entries to " "path entry finders. This cache is maintained in :data:`sys." "path_importer_cache` (despite the name, this cache actually stores finder " "objects rather than being limited to :term:`importer` objects). In this way, " "the expensive search for a particular :term:`path entry` location's :term:" "`path entry finder` need only be done once. User code is free to remove " "cache entries from :data:`sys.path_importer_cache` forcing the path based " "finder to perform the path entry search again [#fnpic]_." msgstr "" #: ../Doc/reference/import.rst:785 msgid "" "If the path entry is not present in the cache, the path based finder " "iterates over every callable in :data:`sys.path_hooks`. Each of the :term:" "`path entry hooks ` in this list is called with a single " "argument, the path entry to be searched. This callable may either return a :" "term:`path entry finder` that can handle the path entry, or it may raise :" "exc:`ImportError`. An :exc:`ImportError` is used by the path based finder " "to signal that the hook cannot find a :term:`path entry finder` for that :" "term:`path entry`. The exception is ignored and :term:`import path` " "iteration continues. The hook should expect either a string or bytes " "object; the encoding of bytes objects is up to the hook (e.g. it may be a " "file system encoding, UTF-8, or something else), and if the hook cannot " "decode the argument, it should raise :exc:`ImportError`." msgstr "" #: ../Doc/reference/import.rst:799 msgid "" "If :data:`sys.path_hooks` iteration ends with no :term:`path entry finder` " "being returned, then the path based finder's :meth:`~importlib.machinery." "PathFinder.find_spec` method will store ``None`` in :data:`sys." "path_importer_cache` (to indicate that there is no finder for this path " "entry) and return ``None``, indicating that this :term:`meta path finder` " "could not find the module." msgstr "" #: ../Doc/reference/import.rst:806 msgid "" "If a :term:`path entry finder` *is* returned by one of the :term:`path entry " "hook` callables on :data:`sys.path_hooks`, then the following protocol is " "used to ask the finder for a module spec, which is then used when loading " "the module." msgstr "" #: ../Doc/reference/import.rst:811 msgid "" "The current working directory -- denoted by an empty string -- is handled " "slightly differently from other entries on :data:`sys.path`. First, if the " "current working directory is found to not exist, no value is stored in :data:" "`sys.path_importer_cache`. Second, the value for the current working " "directory is looked up fresh for each module lookup. Third, the path used " "for :data:`sys.path_importer_cache` and returned by :meth:`importlib." "machinery.PathFinder.find_spec` will be the actual current working directory " "and not the empty string." msgstr "" #: ../Doc/reference/import.rst:821 msgid "Path entry finder protocol" msgstr "" #: ../Doc/reference/import.rst:823 msgid "" "In order to support imports of modules and initialized packages and also to " "contribute portions to namespace packages, path entry finders must implement " "the :meth:`~importlib.abc.PathEntryFinder.find_spec` method." msgstr "" #: ../Doc/reference/import.rst:827 msgid "" ":meth:`~importlib.abc.PathEntryFinder.find_spec` takes two argument, the " "fully qualified name of the module being imported, and the (optional) target " "module. ``find_spec()`` returns a fully populated spec for the module. This " "spec will always have \"loader\" set (with one exception)." msgstr "" #: ../Doc/reference/import.rst:832 msgid "" "To indicate to the import machinery that the spec represents a namespace :" "term:`portion`. the path entry finder sets \"loader\" on the spec to " "``None`` and \"submodule_search_locations\" to a list containing the portion." msgstr "" #: ../Doc/reference/import.rst:837 msgid "" ":meth:`~importlib.abc.PathEntryFinder.find_spec` replaced :meth:`~importlib." "abc.PathEntryFinder.find_loader` and :meth:`~importlib.abc.PathEntryFinder." "find_module`, both of which are now deprecated, but will be used if " "``find_spec()`` is not defined." msgstr "" #: ../Doc/reference/import.rst:843 msgid "" "Older path entry finders may implement one of these two deprecated methods " "instead of ``find_spec()``. The methods are still respected for the sake of " "backward compatibility. However, if ``find_spec()`` is implemented on the " "path entry finder, the legacy methods are ignored." msgstr "" #: ../Doc/reference/import.rst:848 msgid "" ":meth:`~importlib.abc.PathEntryFinder.find_loader` takes one argument, the " "fully qualified name of the module being imported. ``find_loader()`` " "returns a 2-tuple where the first item is the loader and the second item is " "a namespace :term:`portion`. When the first item (i.e. the loader) is " "``None``, this means that while the path entry finder does not have a loader " "for the named module, it knows that the path entry contributes to a " "namespace portion for the named module. This will almost always be the case " "where Python is asked to import a namespace package that has no physical " "presence on the file system. When a path entry finder returns ``None`` for " "the loader, the second item of the 2-tuple return value must be a sequence, " "although it can be empty." msgstr "" #: ../Doc/reference/import.rst:860 msgid "" "If ``find_loader()`` returns a non-``None`` loader value, the portion is " "ignored and the loader is returned from the path based finder, terminating " "the search through the path entries." msgstr "" #: ../Doc/reference/import.rst:864 msgid "" "For backwards compatibility with other implementations of the import " "protocol, many path entry finders also support the same, traditional " "``find_module()`` method that meta path finders support. However path entry " "finder ``find_module()`` methods are never called with a ``path`` argument " "(they are expected to record the appropriate path information from the " "initial call to the path hook)." msgstr "" #: ../Doc/reference/import.rst:871 msgid "" "The ``find_module()`` method on path entry finders is deprecated, as it does " "not allow the path entry finder to contribute portions to namespace " "packages. If both ``find_loader()`` and ``find_module()`` exist on a path " "entry finder, the import system will always call ``find_loader()`` in " "preference to ``find_module()``." msgstr "" #: ../Doc/reference/import.rst:879 msgid "Replacing the standard import system" msgstr "" #: ../Doc/reference/import.rst:881 msgid "" "The most reliable mechanism for replacing the entire import system is to " "delete the default contents of :data:`sys.meta_path`, replacing them " "entirely with a custom meta path hook." msgstr "" #: ../Doc/reference/import.rst:885 msgid "" "If it is acceptable to only alter the behaviour of import statements without " "affecting other APIs that access the import system, then replacing the " "builtin :func:`__import__` function may be sufficient. This technique may " "also be employed at the module level to only alter the behaviour of import " "statements within that module." msgstr "" #: ../Doc/reference/import.rst:891 msgid "" "To selectively prevent import of some modules from a hook early on the meta " "path (rather than disabling the standard import system entirely), it is " "sufficient to raise :exc:`ModuleNoFoundError` directly from :meth:" "`~importlib.abc.MetaPathFinder.find_spec` instead of returning ``None``. The " "latter indicates that the meta path search should continue, while raising an " "exception terminates it immediately." msgstr "" #: ../Doc/reference/import.rst:900 msgid "Special considerations for __main__" msgstr "" #: ../Doc/reference/import.rst:902 msgid "" "The :mod:`__main__` module is a special case relative to Python's import " "system. As noted :ref:`elsewhere `, the ``__main__`` module is " "directly initialized at interpreter startup, much like :mod:`sys` and :mod:" "`builtins`. However, unlike those two, it doesn't strictly qualify as a " "built-in module. This is because the manner in which ``__main__`` is " "initialized depends on the flags and other options with which the " "interpreter is invoked." msgstr "" #: ../Doc/reference/import.rst:913 msgid "__main__.__spec__" msgstr "" #: ../Doc/reference/import.rst:915 msgid "" "Depending on how :mod:`__main__` is initialized, ``__main__.__spec__`` gets " "set appropriately or to ``None``." msgstr "" #: ../Doc/reference/import.rst:918 msgid "" "When Python is started with the :option:`-m` option, ``__spec__`` is set to " "the module spec of the corresponding module or package. ``__spec__`` is also " "populated when the ``__main__`` module is loaded as part of executing a " "directory, zipfile or other :data:`sys.path` entry." msgstr "" #: ../Doc/reference/import.rst:923 msgid "" "In :ref:`the remaining cases ` ``__main__." "__spec__`` is set to ``None``, as the code used to populate the :mod:" "`__main__` does not correspond directly with an importable module:" msgstr "" #: ../Doc/reference/import.rst:927 msgid "interactive prompt" msgstr "" #: ../Doc/reference/import.rst:928 msgid "-c switch" msgstr "" #: ../Doc/reference/import.rst:929 msgid "running from stdin" msgstr "" #: ../Doc/reference/import.rst:930 msgid "running directly from a source or bytecode file" msgstr "" #: ../Doc/reference/import.rst:932 msgid "" "Note that ``__main__.__spec__`` is always ``None`` in the last case, *even " "if* the file could technically be imported directly as a module instead. Use " "the :option:`-m` switch if valid module metadata is desired in :mod:" "`__main__`." msgstr "" #: ../Doc/reference/import.rst:937 msgid "" "Note also that even when ``__main__`` corresponds with an importable module " "and ``__main__.__spec__`` is set accordingly, they're still considered " "*distinct* modules. This is due to the fact that blocks guarded by ``if " "__name__ == \"__main__\":`` checks only execute when the module is used to " "populate the ``__main__`` namespace, and not during normal import." msgstr "" #: ../Doc/reference/import.rst:945 msgid "Open issues" msgstr "" #: ../Doc/reference/import.rst:947 msgid "XXX It would be really nice to have a diagram." msgstr "" #: ../Doc/reference/import.rst:949 msgid "" "XXX * (import_machinery.rst) how about a section devoted just to the " "attributes of modules and packages, perhaps expanding upon or supplanting " "the related entries in the data model reference page?" msgstr "" #: ../Doc/reference/import.rst:953 msgid "" "XXX runpy, pkgutil, et al in the library manual should all get \"See Also\" " "links at the top pointing to the new import system section." msgstr "" #: ../Doc/reference/import.rst:956 msgid "" "XXX Add more explanation regarding the different ways in which ``__main__`` " "is initialized?" msgstr "" #: ../Doc/reference/import.rst:959 msgid "" "XXX Add more info on ``__main__`` quirks/pitfalls (i.e. copy from :pep:" "`395`)." msgstr "" #: ../Doc/reference/import.rst:964 msgid "References" msgstr "" #: ../Doc/reference/import.rst:966 msgid "" "The import machinery has evolved considerably since Python's early days. " "The original `specification for packages `_ is still available to read, although some details " "have changed since the writing of that document." msgstr "" #: ../Doc/reference/import.rst:971 msgid "" "The original specification for :data:`sys.meta_path` was :pep:`302`, with " "subsequent extension in :pep:`420`." msgstr "" #: ../Doc/reference/import.rst:974 msgid "" ":pep:`420` introduced :term:`namespace packages ` for " "Python 3.3. :pep:`420` also introduced the :meth:`find_loader` protocol as " "an alternative to :meth:`find_module`." msgstr "" #: ../Doc/reference/import.rst:978 msgid "" ":pep:`366` describes the addition of the ``__package__`` attribute for " "explicit relative imports in main modules." msgstr "" #: ../Doc/reference/import.rst:981 msgid "" ":pep:`328` introduced absolute and explicit relative imports and initially " "proposed ``__name__`` for semantics :pep:`366` would eventually specify for " "``__package__``." msgstr "" #: ../Doc/reference/import.rst:985 msgid ":pep:`338` defines executing modules as scripts." msgstr "" #: ../Doc/reference/import.rst:987 msgid "" ":pep:`451` adds the encapsulation of per-module import state in spec " "objects. It also off-loads most of the boilerplate responsibilities of " "loaders back onto the import machinery. These changes allow the deprecation " "of several APIs in the import system and also addition of new methods to " "finders and loaders." msgstr "" #: ../Doc/reference/import.rst:994 msgid "Footnotes" msgstr "Notes" #: ../Doc/reference/import.rst:995 msgid "See :class:`types.ModuleType`." msgstr "" #: ../Doc/reference/import.rst:997 msgid "" "The importlib implementation avoids using the return value directly. " "Instead, it gets the module object by looking the module name up in :data:" "`sys.modules`. The indirect effect of this is that an imported module may " "replace itself in :data:`sys.modules`. This is implementation-specific " "behavior that is not guaranteed to work in other Python implementations." msgstr "" #: ../Doc/reference/import.rst:1004 msgid "" "In legacy code, it is possible to find instances of :class:`imp." "NullImporter` in the :data:`sys.path_importer_cache`. It is recommended " "that code be changed to use ``None`` instead. See :ref:`portingpythoncode` " "for more details." msgstr ""