#$@%#$%!

Ngiler SH3LL 360
: / opt / alt / python311 / share / doc / alt-python311-setuptools / docs /

Information Server
MySQL : OFF Perl : OFF CURL : ON WGET : OFF PKEXEC : OFF

Directive	Local Value
IP Address	162.0.209.101
System	Linux premium169.web-hosting.com 4.18.0-553.50.1.lve.el8.x86_64 #1 SMP Thu Apr 17 19:10:24 UTC 2025 x86_64
User	luxeelil
PHP Version	8.0.30
Software	LiteSpeed
Doc root	Writable

Edit File : setuptools.rst \| Size : 6.65 KB
================================================== Building and Distributing Packages with Setuptools ================================================== ``Setuptools`` is a collection of enhancements to the Python ``distutils`` that allow developers to more easily build and distribute Python packages, especially ones that have dependencies on other packages. Packages built and distributed using ``setuptools`` look to the user like ordinary Python packages based on the ``distutils``. Feature Highlights: * Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ - a single-file importable distribution format * Enhanced support for accessing data files hosted in zipped packages. * Automatically include all packages in your source tree, without listing them individually in setup.py * Automatically include all relevant files in your source distributions, without needing to create a \|MANIFEST.in\|_ file, and without having to force regeneration of the ``MANIFEST`` file when your source tree changes [#manifest]_. * Automatically generate wrapper scripts or Windows (console and GUI) .exe files for any number of "main" functions in your project. (Note: this is not a py2exe replacement; the .exe files rely on the local Python installation.) * Transparent Cython support, so that your setup.py can list ``.pyx`` files and still work even when the end-user doesn't have Cython installed (as long as you include the Cython-generated C in your source distribution) * Command aliases - create project-specific, per-user, or site-wide shortcut names for commonly used commands and options * Deploy your project in "development mode", such that it's available on ``sys.path``, yet can still be edited directly from its source checkout. * Easily extend the distutils with new commands or ``setup()`` arguments, and distribute/reuse your extensions for multiple projects, without copying code. * Create extensible applications and frameworks that automatically discover extensions, using simple "entry points" declared in a project's setup script. * Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards compatible to the existing ``find_packages()`` for Python >= 3.3. ----------------- Developer's Guide ----------------- The developer's guide has been updated. See the :doc:`most recent version <userguide/index>`. TRANSITIONAL NOTE ~~~~~~~~~~~~~~~~~ Setuptools automatically calls ``declare_namespace()`` for you at runtime, but future versions may not. This is because the automatic declaration feature has some negative side effects, such as needing to import all namespace packages during the initialization of the ``pkg_resources`` runtime, and also the need for ``pkg_resources`` to be explicitly imported before any namespace packages work at all. In some future releases, you'll be responsible for including your own declaration lines, and the automatic declaration feature will be dropped to get rid of the negative side effects. During the remainder of the current development cycle, therefore, setuptools will warn you about missing ``declare_namespace()`` calls in your ``__init__.py`` files, and you should correct these as soon as possible before the compatibility support is removed. Namespace packages without declaration lines will not work correctly once a user has upgraded to a later version, so it's important that you make this change now in order to avoid having your code break in the field. Our apologies for the inconvenience, and thank you for your patience. setup.cfg-only projects ======================= .. versionadded:: 40.9.0 If ``setup.py`` is missing from the project directory when a :pep:`517` build is invoked, ``setuptools`` emulates a dummy ``setup.py`` file containing only a ``setuptools.setup()`` call. .. note:: :pep:`517` doesn't support editable installs so this is currently incompatible with ``pip install -e .``. This means that you can have a Python project with all build configuration specified in ``setup.cfg``, without a ``setup.py`` file, if you can rely on your project always being built by a :pep:`517`/:pep:`518` compatible frontend. To use this feature: * Specify build requirements and :pep:`517` build backend in ``pyproject.toml``. For example: .. code-block:: toml [build-system] requires = [ "setuptools >= 40.9.0", ] build-backend = "setuptools.build_meta" * Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``build``. .. warning:: As :pep:`517` is new, support is not universal, and frontends that do support it may still have bugs. For compatibility, you may want to put a ``setup.py`` file containing only a ``setuptools.setup()`` invocation. Configuration API ================= Some automation tools may wish to access data from a configuration file. ``Setuptools`` exposes a ``read_configuration()`` function for parsing ``metadata`` and ``options`` sections into a dictionary. .. code-block:: python from setuptools.config import read_configuration conf_dict = read_configuration("/home/user/dev/package/setup.cfg") By default, ``read_configuration()`` will read only the file provided in the first argument. To include values from other configuration files which could be in various places, set the ``find_others`` keyword argument to ``True``. If you have only a configuration file but not the whole package, you can still try to get data out of it with the help of the ``ignore_option_errors`` keyword argument. When it is set to ``True``, all options with errors possibly produced by directives, such as ``attr:`` and others, will be silently ignored. As a consequence, the resulting dictionary will include no such options. Forum and Bug Tracker ===================== Please use `GitHub Discussions`_ for questions and discussion about setuptools, and the `setuptools bug tracker`_ ONLY for issues you have confirmed via the forum are actual bugs, and which you have reduced to a minimal set of steps to reproduce. .. _GitHub Discussions: https://github.com/pypa/setuptools/discussions .. _setuptools bug tracker: https://github.com/pypa/setuptools/ ---- .. [#manifest] The default behaviour for ``setuptools`` will work well for pure Python packages, or packages with simple C extensions (that don't require any special C header). See :ref:`Controlling files in the distribution` and :doc:`userguide/datafiles` for more information about complex scenarios, if you want to include other types of files. .. \|MANIFEST.in\| replace:: ``MANIFEST.in`` .. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/ Back

Edit File : setuptools.rst | Size : 6.65 KB

==================================================
Building and Distributing Packages with Setuptools
==================================================

``Setuptools`` is a collection of enhancements to the Python ``distutils``
that allow developers to more easily build and
distribute Python packages, especially ones that have dependencies on other
packages.

Packages built and distributed using ``setuptools`` look to the user like
ordinary Python packages based on the ``distutils``.

Feature Highlights:

* Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ -
  a single-file importable distribution format

* Enhanced support for accessing data files hosted in zipped packages.

* Automatically include all packages in your source tree, without listing them
  individually in setup.py

* Automatically include all relevant files in your source distributions,
  without needing to create a |MANIFEST.in|_ file, and without having to force
  regeneration of the ``MANIFEST`` file when your source tree changes
  [#manifest]_.

* Automatically generate wrapper scripts or Windows (console and GUI) .exe
  files for any number of "main" functions in your project.  (Note: this is not
  a py2exe replacement; the .exe files rely on the local Python installation.)

* Transparent Cython support, so that your setup.py can list ``.pyx`` files and
  still work even when the end-user doesn't have Cython installed (as long as
  you include the Cython-generated C in your source distribution)

* Command aliases - create project-specific, per-user, or site-wide shortcut
  names for commonly used commands and options

* Deploy your project in "development mode", such that it's available on
  ``sys.path``, yet can still be edited directly from its source checkout.

* Easily extend the distutils with new commands or ``setup()`` arguments, and
  distribute/reuse your extensions for multiple projects, without copying code.

* Create extensible applications and frameworks that automatically discover
  extensions, using simple "entry points" declared in a project's setup script.

* Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards
  compatible to the existing ``find_packages()`` for Python >= 3.3.

-----------------
Developer's Guide
-----------------

The developer's guide has been updated. See the :doc:`most recent version <userguide/index>`.

TRANSITIONAL NOTE
~~~~~~~~~~~~~~~~~

Setuptools automatically calls ``declare_namespace()`` for you at runtime,
but future versions may *not*.  This is because the automatic declaration
feature has some negative side effects, such as needing to import all namespace
packages during the initialization of the ``pkg_resources`` runtime, and also
the need for ``pkg_resources`` to be explicitly imported before any namespace
packages work at all.  In some future releases, you'll be responsible
for including your own declaration lines, and the automatic declaration feature
will be dropped to get rid of the negative side effects.

During the remainder of the current development cycle, therefore, setuptools
will warn you about missing ``declare_namespace()`` calls in your
``__init__.py`` files, and you should correct these as soon as possible
before the compatibility support is removed.
Namespace packages without declaration lines will not work
correctly once a user has upgraded to a later version, so it's important that
you make this change now in order to avoid having your code break in the field.
Our apologies for the inconvenience, and thank you for your patience.

setup.cfg-only projects
=======================

.. versionadded:: 40.9.0

If ``setup.py`` is missing from the project directory when a :pep:`517`
build is invoked, ``setuptools`` emulates a dummy ``setup.py`` file containing
only a ``setuptools.setup()`` call.

.. note::

:pep:`517` doesn't support editable installs so this is currently
    incompatible with ``pip install -e .``.

This means that you can have a Python project with all build configuration
specified in ``setup.cfg``, without a ``setup.py`` file, if you **can rely
on** your project always being built by a :pep:`517`/:pep:`518` compatible
frontend.

To use this feature:

* Specify build requirements and :pep:`517` build backend in
  ``pyproject.toml``.
  For example:

.. code-block:: toml

[build-system]
      requires = [
        "setuptools >= 40.9.0",
      ]
      build-backend = "setuptools.build_meta"

* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``build``.

.. warning::

As :pep:`517` is new, support is not universal, and frontends that
      do support it may still have bugs. For compatibility, you may want to
      put a ``setup.py`` file containing only a ``setuptools.setup()``
      invocation.

Configuration API
=================

Some automation tools may wish to access data from a configuration file.

``Setuptools`` exposes a ``read_configuration()`` function for
parsing ``metadata`` and ``options`` sections into a dictionary.

.. code-block:: python

from setuptools.config import read_configuration

conf_dict = read_configuration("/home/user/dev/package/setup.cfg")

By default, ``read_configuration()`` will read only the file provided
in the first argument. To include values from other configuration files
which could be in various places, set the ``find_others`` keyword argument
to ``True``.

If you have only a configuration file but not the whole package, you can still
try to get data out of it with the help of the ``ignore_option_errors`` keyword
argument. When it is set to ``True``, all options with errors possibly produced
by directives, such as ``attr:`` and others, will be silently ignored.
As a consequence, the resulting dictionary will include no such options.

Forum and Bug Tracker
=====================

Please use `GitHub Discussions`_ for questions and discussion about
setuptools, and the `setuptools bug tracker`_ ONLY for issues you have
confirmed via the forum are actual bugs, and which you have reduced to a minimal
set of steps to reproduce.

.. _GitHub Discussions: https://github.com/pypa/setuptools/discussions
.. _setuptools bug tracker: https://github.com/pypa/setuptools/

----

.. [#manifest] The default behaviour for ``setuptools`` will work well for pure
   Python packages, or packages with simple C extensions (that don't require
   any special C header). See :ref:`Controlling files in the distribution` and
   :doc:`userguide/datafiles` for more information about complex scenarios, if
   you want to include other types of files.

.. |MANIFEST.in| replace:: ``MANIFEST.in``
.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/

Back