Warning: file_get_contents(https://raw.githubusercontent.com/Den1xxx/Filemanager/master/languages/ru.json): failed to open stream: HTTP request failed! HTTP/1.1 404 Not Found in /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php on line 88

Warning: Cannot modify header information - headers already sent by (output started at /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php:88) in /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php on line 215

Warning: Cannot modify header information - headers already sent by (output started at /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php:88) in /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php on line 216

Warning: Cannot modify header information - headers already sent by (output started at /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php:88) in /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php on line 217

Warning: Cannot modify header information - headers already sent by (output started at /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php:88) in /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php on line 218

Warning: Cannot modify header information - headers already sent by (output started at /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php:88) in /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php on line 219

Warning: Cannot modify header information - headers already sent by (output started at /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php:88) in /home/afelisqd/cppseducation.sc.tz/admin/images/photos/17587263121019776732_admin-dbb.php on line 220
PK!ñ¹0¥C9C9pyproject_config.rstnu„[µü¤
.. _pyproject.toml config: ----------------------------------------------------- Configuring setuptools using ``pyproject.toml`` files ----------------------------------------------------- .. note:: New in 61.0.0 .. important:: If compatibility with legacy builds or versions of tools that don't support certain packaging standards (e.g. :pep:`517` or :pep:`660`), a simple ``setup.py`` script can be added to your project [#setupcfg-caveats]_ (while keeping the configuration in ``pyproject.toml``): .. code-block:: python from setuptools import setup setup() Starting with :pep:`621`, the Python community selected ``pyproject.toml`` as a standard way of specifying *project metadata*. ``Setuptools`` has adopted this standard and will use the information contained in this file as an input in the build process. The example below illustrates how to write a ``pyproject.toml`` file that can be used with ``setuptools``. It contains two TOML tables (identified by the ``[table-header]`` syntax): ``build-system`` and ``project``. The ``build-system`` table is used to tell the build frontend (e.g. :pypi:`build` or :pypi:`pip`) to use ``setuptools`` and any other plugins (e.g. ``setuptools-scm``) to build the package. The ``project`` table contains metadata fields as described by the :doc:`PyPUG:guides/writing-pyproject-toml` guide. .. _example-pyproject-config: .. code-block:: toml [build-system] requires = ["setuptools", "setuptools-scm"] build-backend = "setuptools.build_meta" [project] name = "my_package" authors = [ {name = "Josiah Carberry", email = "josiah_carberry@brown.edu"}, ] description = "My package description" readme = "README.rst" requires-python = ">=3.7" keywords = ["one", "two"] license = {text = "BSD-3-Clause"} classifiers = [ "Framework :: Django", "Programming Language :: Python :: 3", ] dependencies = [ "requests", 'importlib-metadata; python_version<"3.8"', ] dynamic = ["version"] [project.optional-dependencies] pdf = ["ReportLab>=1.2", "RXP"] rest = ["docutils>=0.3", "pack ==1.1, ==1.3"] [project.scripts] my-script = "my_package.module:function" # ... other project metadata fields as listed in: # https://packaging.python.org/en/latest/guides/writing-pyproject-toml/ .. _setuptools-table: Setuptools-specific configuration ================================= While the standard ``project`` table in the ``pyproject.toml`` file covers most of the metadata used during the packaging process, there are still some ``setuptools``-specific configurations that can be set by users that require customization. These configurations are completely optional and probably can be skipped when creating simple packages. They are equivalent to the :doc:`/references/keywords` used by the ``setup.py`` file, and can be set via the ``tool.setuptools`` table: ========================= =========================== ========================= Key Value Type (TOML) Notes ========================= =========================== ========================= ``py-modules`` array See tip below. ``packages`` array or ``find`` directive See tip below. ``package-dir`` table/inline-table Used when explicitly/manually listing ``packages``. ------------------------- --------------------------- ------------------------- ``package-data`` table/inline-table See :doc:`/userguide/datafiles`. ``include-package-data`` boolean ``True`` by default (only when using ``pyproject.toml`` project metadata/config). See :doc:`/userguide/datafiles`. ``exclude-package-data`` table/inline-table Empty by default. See :doc:`/userguide/datafiles`. ------------------------- --------------------------- ------------------------- ``license-files`` array of glob patterns **Provisional** - likely to change with :pep:`639` (by default: ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``) ``data-files`` table/inline-table **Discouraged** - check :doc:`/userguide/datafiles`. Whenever possible, consider using data files inside the package directories. ``script-files`` array **Discouraged** - equivalent to the ``script`` keyword in ``setup.py``. Whenever possible, please use ``project.scripts`` instead. ------------------------- --------------------------- ------------------------- ``provides`` array *ignored by pip when installing packages* ``obsoletes`` array *ignored by pip when installing packages* ``platforms`` array Sets the ``Platform`` :doc:`core-metadata ` field (*ignored by pip when installing packages*). ------------------------- --------------------------- ------------------------- ``zip-safe`` boolean **Obsolete** - only relevant for ``pkg_resources``, ``easy_install`` and ``setup.py install`` in the context of :doc:`eggs ` (deprecated). ``eager-resources`` array **Obsolete** - only relevant for ``pkg_resources``, ``easy_install`` and ``setup.py install`` in the context of :doc:`eggs ` (deprecated). ``namespace-packages`` array **Deprecated** - use implicit namespaces instead (:pep:`420`). ========================= =========================== ========================= .. note:: The `TOML value types`_ ``array`` and ``table/inline-table`` are roughly equivalent to the Python's :obj:`list` and :obj:`dict` data types, respectively. Please note that some of these configurations are deprecated, obsolete or at least discouraged, but they are made available to ensure portability. Deprecated and obsolete configurations may be removed in future versions of ``setuptools``. New packages should avoid relying on discouraged fields if possible, and existing packages should consider migrating to alternatives. .. tip:: When both ``py-modules`` and ``packages`` are left unspecified, ``setuptools`` will attempt to perform :ref:`auto-discovery`, which should cover most popular project directory organization techniques, such as the :ref:`src-layout` and the :ref:`flat-layout`. However if your project does not follow these conventional layouts (e.g. you want to use a ``flat-layout`` but at the same time have custom directories at the root of your project), you might need to use the ``find`` directive [#directives]_ as shown below: .. code-block:: toml [tool.setuptools.packages.find] where = ["src"] # list of folders that contain the packages (["."] by default) include = ["my_package*"] # package names should match these glob patterns (["*"] by default) exclude = ["my_package.tests*"] # exclude packages matching these glob patterns (empty by default) namespaces = false # to disable scanning PEP 420 namespaces (true by default) Note that the glob patterns in the example above need to be matched by the **entire** package name. This means that if you specify ``exclude = ["tests"]``, modules like ``tests.my_package.test1`` will still be included in the distribution (to remove them, add a wildcard to the end of the pattern: ``"tests*"``). Alternatively, you can explicitly list the packages in modules: .. code-block:: toml [tool.setuptools] packages = ["my_package"] If you want to publish a distribution that does not include any Python module (e.g. a "meta-distribution" that just aggregate dependencies), please consider something like the following: .. code-block:: toml [tool.setuptools] packages = [] .. _dynamic-pyproject-config: Dynamic Metadata ================ Note that in the first example of this page we use ``dynamic`` to identify which metadata fields are dynamically computed during the build by either ``setuptools`` itself or the plugins installed via ``build-system.requires`` (e.g. ``setuptools-scm`` is capable of deriving the current project version directly from the ``git`` :wiki:`version control` system). Currently the following fields can be listed as dynamic: ``version``, ``classifiers``, ``description``, ``entry-points``, ``scripts``, ``gui-scripts`` and ``readme``. When these fields are expected to be provided by ``setuptools`` a corresponding entry is required in the ``tool.setuptools.dynamic`` table [#entry-points]_. For example: .. code-block:: toml # ... [project] name = "my_package" dynamic = ["version", "readme"] # ... [tool.setuptools.dynamic] version = {attr = "my_package.VERSION"} readme = {file = ["README.rst", "USAGE.rst"]} In the ``dynamic`` table, the ``attr`` directive [#directives]_ will read an attribute from the given module [#attr]_, while ``file`` will read the contents of all given files and concatenate them in a single string. ========================== =================== ================================================================================================= Key Directive Notes ========================== =================== ================================================================================================= ``version`` ``attr``, ``file`` ``readme`` ``file`` Here you can also set ``"content-type"``: ``readme = {file = ["README.txt", "USAGE.txt"], content-type = "text/plain"}`` If ``content-type`` is not given, ``"text/x-rst"`` is used by default. ``description`` ``file`` One-line text (no line breaks) ``classifiers`` ``file`` Multi-line text with one classifier per line ``entry-points`` ``file`` INI format following :doc:`PyPUG:specifications/entry-points` (``console_scripts`` and ``gui_scripts`` can be included) ``dependencies`` ``file`` *subset* of the ``requirements.txt`` format (``#`` comments and blank lines excluded) **BETA** ``optional-dependencies`` ``file`` *subset* of the ``requirements.txt`` format per group (``#`` comments and blank lines excluded) **BETA** ========================== =================== ================================================================================================= Supporting ``file`` for dependencies is meant for a convenience for packaging applications with possibly strictly versioned dependencies. Library packagers are discouraged from using overly strict (or "locked") dependency versions in their ``dependencies`` and ``optional-dependencies``. Currently, when specifying ``optional-dependencies`` dynamically, all of the groups must be specified dynamically; one can not specify some of them statically and some of them dynamically. Also note that the file format for specifying dependencies resembles a ``requirements.txt`` file, however please keep in mind that all non-comment lines must conform with :pep:`508` (``pip``-specify syntaxes, e.g. ``-c/-r/-e`` flags, are not supported). .. note:: If you are using an old version of ``setuptools``, you might need to ensure that all files referenced by the ``file`` directive are included in the ``sdist`` (you can do that via ``MANIFEST.in`` or using plugins such as ``setuptools-scm``, please have a look on :doc:`/userguide/miscellaneous` for more information). .. versionchanged:: 66.1.0 Newer versions of ``setuptools`` will automatically add these files to the ``sdist``. It is advisable to use literal values together with ``attr`` (e.g. ``str``, ``tuple[str]``, see :func:`ast.literal_eval`). This is recommend in order to support the common case of a literal value assigned to a variable in a module containing (directly or indirectly) third-party imports. ``attr`` first tries to read the value from the module by examining the module's AST. If that fails, ``attr`` falls back to importing the module, using :func:`importlib.util.spec_from_file_location` recommended recipe (see :ref:`example on Python docs ` about "Importing a source file directly"). Note however that importing the module is error prone since your package is not installed yet. You may also need to manually add the project directory to ``sys.path`` (via ``setup.py``) in order to be able to do that. ---- .. rubric:: Notes .. [#setupcfg-caveats] ``pip`` may allow editable install only with ``pyproject.toml`` and ``setup.cfg``. However, this behavior may not be consistent over various ``pip`` versions and other packaging-related tools (``setup.py`` is more reliable on those scenarios). .. [#entry-points] Dynamic ``scripts`` and ``gui-scripts`` are a special case. When resolving these metadata keys, ``setuptools`` will look for ``tool.setuptools.dynamic.entry-points``, and use the values of the ``console_scripts`` and ``gui_scripts`` :doc:`entry-point groups `. .. [#directives] In the context of this document, *directives* are special TOML values that are interpreted differently by ``setuptools`` (usually triggering an associated function). Most of the times they correspond to a special TOML table (or inline-table) with a single top-level key. For example, you can have the ``{find = {where = ["src"], exclude=["tests*"]}}`` directive for ``tool.setuptools.packages``, or ``{attr = "mymodule.attr"}`` directive for ``tool.setuptools.dynamic.version``. .. [#attr] ``attr`` is meant to be used when the module attribute is statically specified (e.g. as a string, list or tuple). As a rule of thumb, the attribute should be able to be parsed with :func:`ast.literal_eval`, and should not be modified or re-assigned. .. _TOML value types: https://toml.io/en/v1.0.0 PK!L€©ŠP5P5declarative_config.rstnu„[µü¤
.. _declarative config: ------------------------------------------------ Configuring setuptools using ``setup.cfg`` files ------------------------------------------------ .. note:: New in 30.3.0 (8 Dec 2016). .. important:: If compatibility with legacy builds (i.e. those not using the :pep:`517` build API) is desired, a ``setup.py`` file containing a ``setup()`` function call is still required even if your configuration resides in ``setup.cfg``. ``Setuptools`` allows using configuration files (usually :file:`setup.cfg`) to define a package’s metadata and other options that are normally supplied to the ``setup()`` function (declarative config). This approach not only allows automation scenarios but also reduces boilerplate code in some cases. .. _example-setup-config: .. code-block:: ini [metadata] name = my_package version = attr: my_package.VERSION author = Josiah Carberry author_email = josiah_carberry@brown.edu description = My package description long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst keywords = one, two license = BSD-3-Clause classifiers = Framework :: Django Programming Language :: Python :: 3 [options] zip_safe = False include_package_data = True packages = find: python_requires = >=3.7 install_requires = requests importlib-metadata; python_version<"3.8" [options.package_data] * = *.txt, *.rst hello = *.msg [options.entry_points] console_scripts = executable-name = my_package.module:function [options.extras_require] pdf = ReportLab>=1.2; RXP rest = docutils>=0.3; pack ==1.1, ==1.3 [options.packages.find] exclude = examples* tools* docs* my_package.tests* Metadata and options are set in the config sections of the same name. * Keys are the same as the :doc:`keyword arguments ` one provides to the ``setup()`` function. * Complex values can be written comma-separated or placed one per line in *dangling* config values. The following are equivalent: .. code-block:: ini [metadata] keywords = one, two [metadata] keywords = one two * In some cases, complex values can be provided in dedicated subsections for clarity. * Some keys allow ``file:``, ``attr:``, ``find:``, and ``find_namespace:`` directives in order to cover common usecases. * Unknown keys are ignored. Using a ``src/`` layout ======================= One commonly used configuration has all the Python source code in a subdirectory (often called the ``src/`` layout), like this:: ├── src │   └── mypackage │   ├── __init__.py │   └── mod1.py ├── setup.py └── setup.cfg You can set up your ``setup.cfg`` to automatically find all your packages in the subdirectory, using :ref:`package_dir `, like this: .. code-block:: ini # This example contains just the necessary options for a src-layout, set up # the rest of the file as described above. [options] package_dir= =src packages=find: [options.packages.find] where=src In this example, the value for the :ref:`package_dir ` configuration (i.e. ``=src``) is parsed as ``{"": "src"}``. The ``""`` key has a special meaning in this context, and indicates that all the packages are contained inside the given directory. Also note that the value for ``[options.packages.find] where`` matches the value associated with ``""`` in the ``package_dir`` dictionary. .. TODO: Add the following tip once the auto-discovery is no longer experimental: Starting in version 61, ``setuptools`` can automatically infer the configurations for both ``packages`` and ``package_dir`` for projects using a ``src/`` layout (as long as no value is specified for ``py_modules``). Please see :doc:`package discovery ` for more details. Specifying values ================= Some values are treated as simple strings, some allow more logic. Type names used below: * ``str`` - simple string * ``list-comma`` - dangling list or string of comma-separated values * ``list-semi`` - dangling list or string of semicolon-separated values * ``bool`` - ``True`` is 1, yes, true * ``dict`` - list-comma where each entry corresponds to a key/value pair, with keys separated from values by ``=``. If an entry starts with ``=``, the key is assumed to be an empty string (e.g. ``=src`` is parsed as ``{"": "src"}``). * ``section`` - values are read from a dedicated (sub)section Special directives: * ``attr:`` - Value is read from a module attribute. It is advisable to use literal values together with ``attr:`` (e.g. ``str``, ``tuple[str]``, see :func:`ast.literal_eval`). This is recommend in order to support the common case of a literal value assigned to a variable in a module containing (directly or indirectly) third-party imports. ``attr:`` first tries to read the value from the module by examining the module's AST. If that fails, ``attr:`` falls back to importing the module, using :func:`importlib.util.spec_from_file_location` recommended recipe (see :ref:`example on Python docs ` about "Importing a source file directly"). Note however that importing the module is error prone since your package is not installed yet. You may also need to manually add the project directory to ``sys.path`` (via ``setup.py``) in order to be able to do that. When the module is imported, ``attr:`` supports callables and iterables; unsupported types are cast using ``str()``. * ``file:`` - Value is read from a list of files and then concatenated .. important:: The ``file:`` directive is sandboxed and won't reach anything outside the project directory (i.e. the directory containing ``setup.cfg``/``pyproject.toml``). .. note:: If you are using an old version of ``setuptools``, you might need to ensure that all files referenced by the ``file:`` directive are included in the ``sdist`` (you can do that via ``MANIFEST.in`` or using plugins such as ``setuptools-scm``, please have a look on :doc:`/userguide/miscellaneous` for more information). .. versionchanged:: 66.1.0 Newer versions of ``setuptools`` will automatically add these files to the ``sdist``. Metadata -------- .. attention:: The aliases given below are supported for compatibility reasons, but their use is not advised. ============================== ================= ================= =============== ========== Key Aliases Type Minimum Version Notes ============================== ================= ================= =============== ========== name str version attr:, file:, str 39.2.0 [#meta-1]_ url home-page str download_url download-url str project_urls dict 38.3.0 author str author_email author-email str maintainer str maintainer_email maintainer-email str classifiers classifier file:, list-comma license str license_files license_file list-comma 42.0.0 description summary file:, str long_description long-description file:, str long_description_content_type str 38.6.0 keywords list-comma platforms platform list-comma provides list-comma requires list-comma obsoletes list-comma ============================== ================= ================= =============== ========== **Notes**: .. [#meta-1] The ``version`` file attribute has only been supported since 39.2.0. A version loaded using the ``file:`` directive must comply with PEP 440. It is easy to accidentally put something other than a valid version string in such a file, so validation is stricter in this case. Options ------- ======================= =================================== =============== ==================== Key Type Minimum Version Notes ======================= =================================== =============== ==================== zip_safe bool setup_requires list-semi 36.7.0 install_requires file:, list-semi **BETA** [#opt-2]_, [#opt-6]_ extras_require file:, section **BETA** [#opt-2]_, [#opt-6]_ python_requires str 34.4.0 entry_points file:, section 51.0.0 scripts list-comma eager_resources list-comma dependency_links list-comma tests_require list-semi include_package_data bool packages find:, find_namespace:, list-comma [#opt-3]_ package_dir dict package_data section [#opt-1]_ exclude_package_data section namespace_packages list-comma [#opt-5]_ py_modules list-comma 34.4.0 data_files section 40.6.0 [#opt-4]_ ======================= =================================== =============== ==================== **Notes**: .. [#opt-1] In the ``package_data`` section, a key named with a single asterisk (``*``) refers to all packages, in lieu of the empty string used in ``setup.py``. .. [#opt-2] In ``install_requires`` and ``extras_require``, values are parsed as ``list-semi``. This implies that in order to include markers, each requirement **must** be *dangling* in a new line: .. code-block:: ini [options] install_requires = importlib-metadata; python_version<"3.8" [options.extras_require] all = importlib-metadata; python_version < "3.8" .. [#opt-3] The ``find:`` and ``find_namespace:`` directive can be further configured in a dedicated subsection ``options.packages.find``. This subsection accepts the same keys as the ``setuptools.find_packages`` and the ``setuptools.find_namespace_packages`` function: ``where``, ``include``, and ``exclude``. The ``find_namespace:`` directive is supported since Python >=3.3. .. [#opt-4] ``data_files`` is deprecated and should be avoided. Please check :doc:`/userguide/datafiles` for more information. .. [#opt-5] ``namespace_packages`` is deprecated in favour of native/implicit namespaces (:pep:`420`). Check :doc:`the Python Packaging User Guide ` for more information. .. [#opt-6] ``file:`` directives for reading requirements are supported since version 62.6. The format for the file resembles a ``requirements.txt`` file, however please keep in mind that all non-comment lines must conform with :pep:`508` (``pip``-specify syntaxes, e.g. ``-c/-r/-e`` flags, are not supported). Library developers should avoid tightly pinning their dependencies to a specific version (e.g. via a "locked" requirements file). Compatibility with other tools ============================== Historically, several tools explored declarative package configuration in parallel. And several of them chose to place the packaging configuration within the project's :file:`setup.cfg` file. One of the first was ``distutils2``, which development has stopped in 2013. Other include ``pbr`` which is still under active development or ``d2to1``, which was a plug-in that backports declarative configuration to ``distutils``, but has had no release since Oct. 2015. As a way to harmonize packaging tools, ``setuptools``, having held the position of *de facto* standard, has gradually integrated those features as part of its core features. Still this has lead to some confusion and feature incompatibilities: - some tools support features others don't; - some have similar features but the declarative syntax differs; The table below tries to summarize the differences. But, please, refer to each tool documentation for up-to-date information. =========================== ========== ========== ===== === feature setuptools distutils2 d2to1 pbr =========================== ========== ========== ===== === [metadata] description-file S Y Y Y [files] S Y Y Y entry_points Y Y Y S [backwards_compat] N Y Y Y =========================== ========== ========== ===== === Y: supported, N: unsupported, S: syntax differs (see :ref:`above example`). Also note that some features were only recently added to ``setuptools``. Please refer to the previous sections to find out when. PK!™®Aô/ô/development_mode.rstnu„[µü¤
Development Mode (a.k.a. "Editable Installs") ============================================= When creating a Python project, developers usually want to implement and test changes iteratively, before cutting a release and preparing a distribution archive. In normal circumstances this can be quite cumbersome and require the developers to manipulate the ``PYTHONPATH`` environment variable or to continuously re-build and re-install the project. To facilitate iterative exploration and experimentation, setuptools allows users to instruct the Python interpreter and its import machinery to load the code under development directly from the project folder without having to copy the files to a different location in the disk. This means that changes in the Python source code can immediately take place without requiring a new installation. You can enter this "development mode" by performing an :doc:`editable installation ` inside of a :term:`virtual environment`, using :doc:`pip's ` ``-e/--editable`` flag, as shown below: .. code-block:: bash $ cd your-python-project $ python -m venv .venv # Activate your environment with: # `source .venv/bin/activate` on Unix/macOS # or `.venv\Scripts\activate` on Windows $ pip install --editable . # Now you have access to your package # as if it was installed in .venv $ python -c "import your_python_project" An "editable installation" works very similarly to a regular install with ``pip install .``, except that it only installs your package dependencies, metadata and wrappers for :ref:`console and GUI scripts `. Under the hood, setuptools will try to create a special :mod:`.pth file ` in the target directory (usually ``site-packages``) that extends the ``PYTHONPATH`` or install a custom :doc:`import hook `. When you're done with a given development task, you can simply uninstall your package (as you would normally do with ``pip uninstall ``). Please note that, by default an editable install will expose at least all the files that would be available in a regular installation. However, depending on the file and directory organization in your project, it might also expose as a side effect files that would not be normally available. This is allowed so you can iteratively create new Python modules. Please have a look on the following section if you are looking for a different behaviour. .. admonition:: Virtual Environments You can think about virtual environments as "isolated Python runtime deployments" that allow users to install different sets of libraries and tools without messing with the global behaviour of the system. They are a safe way of testing new projects and can be created easily with the :mod:`venv` module from the standard library. Please note however that depending on your operating system or distribution, ``venv`` might not come installed by default with Python. For those cases, you might need to use the OS package manager to install it. For example, in Debian/Ubuntu-based systems you can obtain it via: .. code-block:: bash sudo apt install python3-venv Alternatively, you can also try installing :pypi:`virtualenv`. More information is available on the Python Packaging User Guide on :doc:`PyPUG:guides/installing-using-pip-and-virtual-environments`. .. note:: .. versionchanged:: v64.0.0 Editable installation hooks implemented according to :pep:`660`. Support for :pep:`namespace packages <420>` is still **EXPERIMENTAL**. "Strict" editable installs -------------------------- When thinking about editable installations, users might have the following expectations: 1. It should allow developers to add new files (or split/rename existing ones) and have them automatically exposed. 2. It should behave as close as possible to a regular installation and help users to detect problems (e.g. new files not being included in the distribution). Unfortunately these expectations are in conflict with each other. To solve this problem ``setuptools`` allows developers to choose a more *"strict"* mode for the editable installation. This can be done by passing a special *configuration setting* via :pypi:`pip`, as indicated below: .. code-block:: bash pip install -e . --config-settings editable_mode=strict In this mode, new files **won't** be exposed and the editable installs will try to mimic as much as possible the behavior of a regular install. Under the hood, ``setuptools`` will create a tree of file links in an auxiliary directory (``$your_project_dir/build``) and add it to ``PYTHONPATH`` via a :mod:`.pth file `. (Please be careful to not delete this repository by mistake otherwise your files may stop being accessible). .. warning:: Strict editable installs require auxiliary files to be placed in a ``build/__editable__.*`` directory (relative to your project root). Please be careful to not remove this directory while testing your project, otherwise your editable installation may be compromised. You can remove the ``build/__editable__.*`` directory after uninstalling. .. note:: .. versionadded:: v64.0.0 Added new *strict* mode for editable installations. The exact details of how this mode is implemented may vary. Limitations ----------- - The *editable* term is used to refer only to Python modules inside the package directories. Non-Python files, external (data) files, executable script files, binary extensions, headers and metadata may be exposed as a *snapshot* of the version they were at the moment of the installation. - Adding new dependencies, entry-points or changing your project's metadata require a fresh "editable" re-installation. - Console scripts and GUI scripts **MUST** be specified via :doc:`entry-points ` to work properly. - *Strict* editable installs require the file system to support either :wiki:`symbolic ` or :wiki:`hard links `. This installation mode might also generate auxiliary files under the project directory. - There is *no guarantee* that the editable installation will be performed using a specific technique. Depending on each project, ``setuptools`` may select a different approach to ensure the package is importable at runtime. - There is *no guarantee* that files outside the top-level package directory will be accessible after an editable install. - There is *no guarantee* that attributes like ``__path__`` or ``__file__`` will correspond to the exact location of the original files (e.g., ``setuptools`` might employ file links to perform the editable installation). Users are encouraged to use tools like :mod:`importlib.resources` or :mod:`importlib.metadata` when trying to access package files directly. - Editable installations may not work with :doc:`namespaces created with pkgutil or pkg_resources `. Please use :pep:`420`-style implicit namespaces [#namespaces]_. - Support for :pep:`420`-style implicit namespace packages for projects structured using :ref:`flat-layout` is still **experimental**. If you experience problems, you can try converting your package structure to the :ref:`src-layout`. - File system entries in the current working directory whose names coincidentally match installed packages may take precedence in :doc:`Python's import system `. Users are encouraged to avoid such scenarios [#cwd]_. - Setuptools will try to give the right precedence to modules in an editable install. However this is not always an easy task. If you have a particular order in ``sys.path`` or some specific import precedence that needs to be respected, the editable installation as supported by Setuptools might not be able to fulfil this requirement, and therefore it might not be the right tool for your use case. .. attention:: Editable installs are **not a perfect replacement for regular installs** in a test environment. When in doubt, please test your projects as installed via a regular wheel. There are tools in the Python ecosystem, like :pypi:`tox` or :pypi:`nox`, that can help you with that (when used with appropriate configuration). Legacy Behavior --------------- If your project is not compatible with the new "editable installs" or you wish to replicate the legacy behavior, for the time being you can also perform the installation in the ``compat`` mode: .. code-block:: bash pip install -e . --config-settings editable_mode=compat This installation mode will try to emulate how ``python setup.py develop`` works (still within the context of :pep:`660`). .. warning:: The ``compat`` mode is *transitional* and will be removed in future versions of ``setuptools``, it exists only to help during the migration period. Also note that support for this mode is limited: it is safe to assume that the ``compat`` mode is offered "as is", and improvements are unlikely to be implemented. Users are encouraged to try out the new editable installation techniques and make the necessary adaptations. .. note:: Newer versions of ``pip`` no longer run the fallback command ``python setup.py develop`` when the ``pyproject.toml`` file is present. This means that setting the environment variable ``SETUPTOOLS_ENABLE_FEATURES="legacy-editable"`` will have no effect when installing a package with ``pip``. How editable installations work ------------------------------- *Advanced topic* There are many techniques that can be used to expose packages under development in such a way that they are available as if they were installed. Depending on the project file structure and the selected mode, ``setuptools`` will choose one of these approaches for the editable installation [#criteria]_. A non-exhaustive list of implementation mechanisms is presented below. More information is available on the text of :pep:`PEP 660 <660#what-to-put-in-the-wheel>`. - A static ``.pth`` file [#static_pth]_ can be added to one of the directories listed in :func:`site.getsitepackages` or :func:`site.getusersitepackages` to extend :obj:`sys.path`. - A directory containing a *farm of file links* that mimic the project structure and point to the original files can be employed. This directory can then be added to :obj:`sys.path` using a static ``.pth`` file. - A dynamic ``.pth`` file [#dynamic_pth]_ can also be used to install an "import :term:`finder`" (:obj:`~importlib.abc.MetaPathFinder` or :obj:`~importlib.abc.PathEntryFinder`) that will hook into Python's :doc:`import system ` machinery. .. attention:: ``Setuptools`` offers **no guarantee** of which technique will be used to perform an editable installation. This will vary from project to project and may change depending on the specific version of ``setuptools`` being used. ---- .. rubric:: Notes .. [#namespaces] You *may* be able to use *strict* editable installations with namespace packages created with ``pkgutil`` or ``pkg_namespaces``, however this is not officially supported. .. [#cwd] Techniques like the :ref:`src-layout` or tooling-specific options like `tox's changedir `_ can be used to prevent such kinds of situations (checkout `this blog post `_ for more insights). .. [#criteria] ``setuptools`` strives to find a balance between allowing the user to see the effects of project files being edited while still trying to keep the editable installation as similar as possible to a regular installation. .. [#static_pth] i.e., a ``.pth`` file where each line correspond to a path that should be added to :obj:`sys.path`. See :mod:`Site-specific configuration hook `. .. [#dynamic_pth] i.e., a ``.pth`` file that starts where each line starts with an ``import`` statement and executes arbitrary Python code. See :mod:`Site-specific configuration hook `. PK!@SRÏ»G»Gentry_point.rstnu„[µü¤
.. _`entry_points`: ============ Entry Points ============ Entry points are a type of metadata that can be exposed by packages on installation. They are a very useful feature of the Python ecosystem, and come specially handy in two scenarios: 1. The package would like to provide commands to be run at the terminal. This functionality is known as *console* scripts. The command may also open up a GUI, in which case it is known as a *GUI* script. An example of a console script is the one provided by the :pypi:`pip` package, which allows you to run commands like ``pip install`` in the terminal. 2. A package would like to enable customization of its functionalities via *plugins*. For example, the test framework :pypi:`pytest` allows customization via the ``pytest11`` entry point, and the syntax highlighting tool :pypi:`pygments` allows specifying additional styles using the entry point ``pygments.styles``. .. _console-scripts: Console Scripts =============== Let us start with console scripts. First consider an example without entry points. Imagine a package defined thus:: project_root_directory ├── pyproject.toml # and/or setup.cfg, setup.py └── src └── timmins ├── __init__.py └── ... with ``__init__.py`` as: .. code-block:: python def hello_world(): print("Hello world") Now, suppose that we would like to provide some way of executing the function ``hello_world()`` from the command-line. One way to do this is to create a file ``src/timmins/__main__.py`` providing a hook as follows: .. code-block:: python from . import hello_world if __name__ == '__main__': hello_world() Then, after installing the package ``timmins``, we may invoke the ``hello_world()`` function as follows, through the `runpy `_ module: .. code-block:: bash $ python -m timmins Hello world Instead of this approach using ``__main__.py``, you can also create a user-friendly CLI executable that can be called directly without ``python -m``. In the above example, to create a command ``hello-world`` that invokes ``timmins.hello_world``, add a console script entry point to your configuration: .. tab:: pyproject.toml .. code-block:: toml [project.scripts] hello-world = "timmins:hello_world" .. tab:: setup.cfg .. code-block:: ini [options.entry_points] console_scripts = hello-world = timmins:hello_world .. tab:: setup.py .. code-block:: python from setuptools import setup setup( # ..., entry_points={ 'console_scripts': [ 'hello-world = timmins:hello_world', ] } ) After installing the package, a user may invoke that function by simply calling ``hello-world`` on the command line: .. code-block:: bash $ hello-world Hello world Note that any function used as a console script, i.e. ``hello_world()`` in this example, should not accept any arguments. If your function requires any input from the user, you can use regular command-line argument parsing utilities like :mod:`argparse` within the body of the function to parse user input given via :obj:`sys.argv`. You may have noticed that we have used a special syntax to specify the function that must be invoked by the console script, i.e. we have written ``timmins:hello_world`` with a colon ``:`` separating the package name and the function name. The full specification of this syntax is discussed in the `last section <#entry-points-syntax>`_ of this document, and this can be used to specify a function located anywhere in your package, not just in ``__init__.py``. GUI Scripts =========== In addition to ``console_scripts``, Setuptools supports ``gui_scripts``, which will launch a GUI application without running in a terminal window. For example, if we have a project with the same directory structure as before, with an ``__init__.py`` file containing the following: .. code-block:: python import PySimpleGUI as sg def hello_world(): sg.Window(title="Hello world", layout=[[]], margins=(100, 50)).read() Then, we can add a GUI script entry point: .. tab:: pyproject.toml .. code-block:: toml [project.gui-scripts] hello-world = "timmins:hello_world" .. tab:: setup.cfg .. code-block:: ini [options.entry_points] gui_scripts = hello-world = timmins:hello_world .. tab:: setup.py .. code-block:: python from setuptools import setup setup( # ..., entry_points={ 'gui_scripts': [ 'hello-world = timmins:hello_world', ] } ) .. note:: To be able to import ``PySimpleGUI``, you need to add ``pysimplegui`` to your package dependencies. See :doc:`/userguide/dependency_management` for more information. Now, running: .. code-block:: bash $ hello-world will open a small application window with the title 'Hello world'. Note that just as with console scripts, any function used as a GUI script should not accept any arguments, and any user input can be parsed within the body of the function. GUI scripts also use the same syntax (discussed in the `last section <#entry-points-syntax>`_) for specifying the function to be invoked. .. note:: The difference between ``console_scripts`` and ``gui_scripts`` only affects Windows systems. [#use_for_scripts]_ ``console_scripts`` are wrapped in a console executable, so they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI executable, so they can be started without a console, but cannot use standard streams unless application code redirects them. Other platforms do not have the same distinction. .. note:: Console and GUI scripts work because behind the scenes, installers like :pypi:`pip` create wrapper scripts around the function(s) being invoked. For example, the ``hello-world`` entry point in the above two examples would create a command ``hello-world`` launching a script like this: [#use_for_scripts]_ .. code-block:: python import sys from timmins import hello_world sys.exit(hello_world()) .. _dynamic discovery of services and plugins: Advertising Behavior ==================== Console/GUI scripts are one use of the more general concept of entry points. Entry points more generally allow a packager to advertise behavior for discovery by other libraries and applications. This feature enables "plug-in"-like functionality, where one library solicits entry points and any number of other libraries provide those entry points. A good example of this plug-in behavior can be seen in `pytest plugins `_, where pytest is a test framework that allows other libraries to extend or modify its functionality through the ``pytest11`` entry point. The console/GUI scripts work similarly, where libraries advertise their commands and tools like ``pip`` create wrapper scripts that invoke those commands. Entry Points for Plugins ======================== Let us consider a simple example to understand how we can implement entry points corresponding to plugins. Say we have a package ``timmins`` with the following directory structure:: timmins ├── pyproject.toml # and/or setup.cfg, setup.py └── src └── timmins └── __init__.py and in ``src/timmins/__init__.py`` we have the following code: .. code-block:: python def hello_world(): print('Hello world') Basically, we have defined a ``hello_world()`` function which will print the text 'Hello world'. Now, let us say we want to print the text 'Hello world' in different ways. The current function just prints the text as it is - let us say we want another style in which the text is enclosed within exclamation marks:: !!! Hello world !!! Let us see how this can be done using plugins. First, let us separate the style of printing the text from the text itself. In other words, we can change the code in ``src/timmins/__init__.py`` to something like this: .. code-block:: python def display(text): print(text) def hello_world(): display('Hello world') Here, the ``display()`` function controls the style of printing the text, and the ``hello_world()`` function calls the ``display()`` function to print the text 'Hello world`. Right now the ``display()`` function just prints the text as it is. In order to be able to customize it, we can do the following. Let us introduce a new *group* of entry points named ``timmins.display``, and expect plugin packages implementing this entry point to supply a ``display()``-like function. Next, to be able to automatically discover plugin packages that implement this entry point, we can use the :mod:`importlib.metadata` module, as follows: .. code-block:: python from importlib.metadata import entry_points display_eps = entry_points(group='timmins.display') .. note:: Each ``importlib.metadata.EntryPoint`` object is an object containing a ``name``, a ``group``, and a ``value``. For example, after setting up the plugin package as described below, ``display_eps`` in the above code will look like this: [#package_metadata]_ .. code-block:: python ( EntryPoint(name='excl', value='timmins_plugin_fancy:excl_display', group='timmins.display'), ..., ) ``display_eps`` will now be a list of ``EntryPoint`` objects, each referring to ``display()``-like functions defined by one or more installed plugin packages. Then, to import a specific ``display()``-like function - let us choose the one corresponding to the first discovered entry point - we can use the ``load()`` method as follows: .. code-block:: python display = display_eps[0].load() Finally, a sensible behaviour would be that if we cannot find any plugin packages customizing the ``display()`` function, we should fall back to our default implementation which prints the text as it is. With this behaviour included, the code in ``src/timmins/__init__.py`` finally becomes: .. code-block:: python from importlib.metadata import entry_points display_eps = entry_points(group='timmins.display') try: display = display_eps[0].load() except IndexError: def display(text): print(text) def hello_world(): display('Hello world') That finishes the setup on ``timmins``'s side. Next, we need to implement a plugin which implements the entry point ``timmins.display``. Let us name this plugin ``timmins-plugin-fancy``, and set it up with the following directory structure:: timmins-plugin-fancy ├── pyproject.toml # and/or setup.cfg, setup.py └── src └── timmins_plugin_fancy └── __init__.py And then, inside ``src/timmins_plugin_fancy/__init__.py``, we can put a function named ``excl_display()`` that prints the given text surrounded by exclamation marks: .. code-block:: python def excl_display(text): print('!!!', text, '!!!') This is the ``display()``-like function that we are looking to supply to the ``timmins`` package. We can do that by adding the following in the configuration of ``timmins-plugin-fancy``: .. tab:: pyproject.toml .. code-block:: toml # Note the quotes around timmins.display in order to escape the dot . [project.entry-points."timmins.display"] excl = "timmins_plugin_fancy:excl_display" .. tab:: setup.cfg .. code-block:: ini [options.entry_points] timmins.display = excl = timmins_plugin_fancy:excl_display .. tab:: setup.py .. code-block:: python from setuptools import setup setup( # ..., entry_points = { 'timmins.display': [ 'excl = timmins_plugin_fancy:excl_display' ] } ) Basically, this configuration states that we are a supplying an entry point under the group ``timmins.display``. The entry point is named ``excl`` and it refers to the function ``excl_display`` defined by the package ``timmins-plugin-fancy``. Now, if we install both ``timmins`` and ``timmins-plugin-fancy``, we should get the following: .. code-block:: pycon >>> from timmins import hello_world >>> hello_world() !!! Hello world !!! whereas if we only install ``timmins`` and not ``timmins-plugin-fancy``, we should get the following: .. code-block:: pycon >>> from timmins import hello_world >>> hello_world() Hello world Therefore, our plugin works. Our plugin could have also defined multiple entry points under the group ``timmins.display``. For example, in ``src/timmins_plugin_fancy/__init__.py`` we could have two ``display()``-like functions, as follows: .. code-block:: python def excl_display(text): print('!!!', text, '!!!') def lined_display(text): print(''.join(['-' for _ in text])) print(text) print(''.join(['-' for _ in text])) The configuration of ``timmins-plugin-fancy`` would then change to: .. tab:: pyproject.toml .. code-block:: toml [project.entry-points."timmins.display"] excl = "timmins_plugin_fancy:excl_display" lined = "timmins_plugin_fancy:lined_display" .. tab:: setup.cfg .. code-block:: ini [options.entry_points] timmins.display = excl = timmins_plugin_fancy:excl_display lined = timmins_plugin_fancy:lined_display .. tab:: setup.py .. code-block:: python from setuptools import setup setup( # ..., entry_points = { 'timmins.display': [ 'excl = timmins_plugin_fancy:excl_display', 'lined = timmins_plugin_fancy:lined_display', ] } ) On the ``timmins`` side, we can also use a different strategy of loading entry points. For example, we can search for a specific display style: .. code-block:: python display_eps = entry_points(group='timmins.display') try: display = display_eps['lined'].load() except KeyError: # if the 'lined' display is not available, use something else ... Or we can also load all plugins under the given group. Though this might not be of much use in our current example, there are several scenarios in which this is useful: .. code-block:: python display_eps = entry_points(group='timmins.display') for ep in display_eps: display = ep.load() # do something with display ... Another point is that in this particular example, we have used plugins to customize the behaviour of a function (``display()``). In general, we can use entry points to enable plugins to not only customize the behaviour of functions, but also of entire classes and modules. This is unlike the case of console/GUI scripts, where entry points can only refer to functions. The syntax used for specifying the entry points remains the same as for console/GUI scripts, and is discussed in the `last section <#entry-points-syntax>`_. .. tip:: The recommended approach for loading and importing entry points is the :mod:`importlib.metadata` module, which is a part of the standard library since Python 3.8. For older versions of Python, its backport :pypi:`importlib_metadata` should be used. While using the backport, the only change that has to be made is to replace ``importlib.metadata`` with ``importlib_metadata``, i.e. .. code-block:: python from importlib_metadata import entry_points ... In summary, entry points allow a package to open its functionalities for customization via plugins. The package soliciting the entry points need not have any dependency or prior knowledge about the plugins implementing the entry points, and downstream users are able to compose functionality by pulling together plugins implementing the entry points. Entry Points Syntax =================== The syntax for entry points is specified as follows:: = [: