diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_templates/indexsidebar.html | 2 | ||||
| -rw-r--r-- | docs/index.txt | 6 | ||||
| -rw-r--r-- | docs/pkg_resources.txt | 11 | ||||
| -rw-r--r-- | docs/setuptools.txt | 205 |
4 files changed, 216 insertions, 8 deletions
diff --git a/docs/_templates/indexsidebar.html b/docs/_templates/indexsidebar.html index a27c85fe..3b127602 100644 --- a/docs/_templates/indexsidebar.html +++ b/docs/_templates/indexsidebar.html @@ -5,4 +5,4 @@ <h3>Questions? Suggestions? Contributions?</h3> -<p>Visit the <a href="https://bitbucket.org/pypa/setuptools">Setuptools project page</a> </p> +<p>Visit the <a href="https://github.com/pypa/setuptools">Setuptools project page</a> </p> diff --git a/docs/index.txt b/docs/index.txt index 6ac37252..74aabb5e 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -16,10 +16,10 @@ Documentation content: .. toctree:: :maxdepth: 2 - history - roadmap - python3 setuptools easy_install pkg_resources + python3 development + roadmap + history diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.txt index 7b979ec3..e8412b33 100644 --- a/docs/pkg_resources.txt +++ b/docs/pkg_resources.txt @@ -831,10 +831,9 @@ correspond exactly to the constructor argument names: ``name``, ``module_name``, ``attrs``, ``extras``, and ``dist`` are all available. In addition, the following methods are provided: -``load(require=True, env=None, installer=None)`` - Load the entry point, returning the advertised Python object, or raise - ``ImportError`` if it cannot be obtained. If `require` is a true value, - then ``require(env, installer)`` is called before attempting the import. +``load()`` + Load the entry point, returning the advertised Python object. Effectively + calls ``self.require()`` then returns ``self.resolve()``. ``require(env=None, installer=None)`` Ensure that any "extras" needed by the entry point are available on @@ -846,6 +845,10 @@ addition, the following methods are provided: taking a ``Requirement`` instance and returning a matching importable ``Distribution`` instance or None. +``resolve()`` + Resolve the entry point from its module and attrs, returning the advertised + Python object. Raises ``ImportError`` if it cannot be obtained. + ``__str__()`` The string form of an ``EntryPoint`` is a string that could be passed to ``EntryPoint.parse()`` to produce an equivalent ``EntryPoint``. diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 5ce2c7b1..2f78b133 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -2398,6 +2398,211 @@ The ``upload_docs`` command has the following options: https://pypi.python.org/pypi (i.e., the main PyPI installation). +----------------------------------------- +Configuring setup() using setup.cfg files +----------------------------------------- + +``Setuptools`` allows using configuration files (usually `setup.cfg`) +to define package’s metadata and other options which are normally supplied +to ``setup()`` function. + +This approach not only allows automation scenarios, but also reduces +boilerplate code in some cases. + +.. note:: + Implementation presents limited compatibility with distutils2-like + ``setup.cfg`` sections (used by ``pbr`` and ``d2to1`` packages). + + Namely: only metadata related keys from ``metadata`` section are supported + (except for ``description-file``); keys from ``files``, ``entry_points`` + and ``backwards_compat`` are not supported. + + +.. code-block:: ini + + [metadata] + name = my_package + version = attr: src.VERSION + description = My package description + long_description = file: README.rst + keywords = one, two + license = BSD 3-Clause License + + [metadata.classifiers] + Framework :: Django + Programming Language :: Python :: 3.5 + + [options] + zip_safe = False + include_package_data = True + packages = find: + scripts = + bin/first.py + bin/second.py + + [options.package_data] + * = *.txt, *.rst + hello = *.msg + + [options.extras_require] + pdf = ReportLab>=1.2; RXP + rest = docutils>=0.3; pack ==1.1, ==1.3 + + [options.packages.find] + exclude = + src.subpackage1 + src.subpackage2 + + +Metadata and options could be set in sections with the same names. + +* Keys are the same as keyword arguments one provides to ``setup()`` function. + +* Complex values could be placed comma-separated or one per line + in *dangling* sections. The following are the same: + + .. code-block:: ini + + [metadata] + keywords = one, two + + [metadata] + keywords = + one + two + +* In some cases complex values could be provided in subsections for clarity. + +* Some keys allow ``file:``, ``attr:`` and ``find:`` directives to cover + common usecases. + +* Unknown keys are ignored. + + +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 comma-separated values string +* ``list-semi`` - dangling list or semicolon-separated values string +* ``bool`` - ``True`` is 1, yes, true +* ``dict`` - list-comma where keys from values are separated by = +* ``section`` - values could be read from a dedicated (sub)section + + +Special directives: + +* ``attr:`` - value could be read from module attribute +* ``file:`` - value could be read from a file + + +.. note:: + ``file:`` directive is sandboxed and won't reach anything outside + directory with ``setup.py``. + + +Metadata +-------- + +.. note:: + Aliases given below are supported for compatibility reasons, + but not advised. + +================= ================= ===== +Key Aliases Accepted value type +================= ================= ===== +name str +version attr:, str +url home-page str +download_url download-url str +author str +author_email author-email str +maintainer str +maintainer_email maintainer-email str +classifiers classifier file:, section, list-comma +license file:, str +description summary file:, str +long_description long-description file:, str +keywords list-comma +platforms platform list-comma +provides list-comma +requires list-comma +obsoletes list-comma +================= ================= ===== + +.. note:: + + **version** - ``attr:`` supports callables; supports iterables; + unsupported types are casted using ``str()``. + + +Options +------- + +======================= ===== +Key Accepted value type +======================= ===== +zip_safe bool +setup_requires list-semi +install_requires list-semi +extras_require section +entry_points file:, section +use_2to3 bool +use_2to3_fixers list-comma +use_2to3_exclude_fixers list-comma +convert_2to3_doctests list-comma +scripts list-comma +eager_resources list-comma +dependency_links list-comma +tests_require list-semi +include_package_data bool +packages find:, list-comma +package_dir dict +package_data section +exclude_package_data section +namespace_packages list-comma +======================= ===== + +.. note:: + + **packages** - ``find:`` directive can be further configured + in a dedicated subsection `options.packages.find`. This subsection + accepts the same keys as `setuptools.find` function: + `where`, `include`, `exclude`. + + +Configuration API +================= + +Some automation tools may wish to access data from a configuration file. + +``Setuptools`` exposes ``read_configuration()`` function allowing +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 file provided +in the first argument. To include values from other configuration files +which could be in various places set `find_others` function 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 `ignore_option_errors` function +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. + + -------------------------------- Extending and Reusing Setuptools -------------------------------- |