Merge branch 'main' into feature/local-schemesfeature/local-schemes

1 files changed, 336 insertions, 0 deletions

diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst
new file mode 100644
index 00000000..c26b9d49
--- /dev/null
+++ b/docs/references/keywords.rst
@@ -0,0 +1,336 @@
+========
+Keywords
+========
+
+``name``
+    A string specifying the name of the package.
+
+``version``
+    A string specifying the version number of the package.
+
+``description``
+    A string describing the package in a single line.
+
+``long_description``
+    A string providing a longer description of the package.
+
+``long_description_content_type``
+    A string specifying the content type is used for the ``long_description``
+    (e.g. ``text/markdown``)
+
+``author``
+    A string specifying the author of the package.
+
+``author_email``
+    A string specifying the email address of the package author.
+
+``maintainer``
+    A string specifying the name of the current maintainer, if different from
+    the author. Note that if the maintainer is provided, setuptools will use it
+    as the author in ``PKG-INFO``.
+
+``maintainer_email``
+    A string specifying the email address of the current maintainer, if
+    different from the author.
+
+``url``
+    A string specifying the URL for the package homepage.
+
+``download_url``
+    A string specifying the URL to download the package.
+
+``packages``
+    A list of strings specifying the packages that setuptools will manipulate.
+
+``py_modules``
+    A list of strings specifying the modules that setuptools will manipulate.
+
+``scripts``
+    A list of strings specifying the standalone script files to be built and
+    installed.
+
+``ext_package``
+    A string specifying the base package name for the extensions provided by
+    this package.
+
+``ext_modules``
+    A list of instances of ``setuptools.Extension`` providing the list of
+    Python extensions to be built.
+
+``classifiers``
+    A list of strings describing the categories for the package.
+
+``distclass``
+    A subclass of ``Distribution`` to use.
+
+``script_name``
+    A string specifying the name of the setup.py script -- defaults to
+    ``sys.argv[0]``
+
+``script_args``
+    A list of strings defining the arguments to supply to the setup script.
+
+``options``
+    A dictionary providing the default options for the setup script.
+
+``license``
+    A string specifying the license of the package.
+
+``license_file``
+
+    .. warning::
+        ``license_file`` is deprecated. Use ``license_files`` instead.
+
+``license_files``
+
+    A list of glob patterns for license related files that should be included.
+    If neither ``license_file`` nor ``license_files`` is specified, this option
+    defaults to ``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*``, and ``AUTHORS*``.
+
+``keywords``
+    A list of strings or a comma-separated string providing descriptive
+    meta-data. See: `PEP 0314`_.
+
+.. _PEP 0314: https://www.python.org/dev/peps/pep-0314/
+
+``platforms``
+    A list of strings or comma-separated string.
+
+``cmdclass``
+    A dictionary providing a mapping of command names to ``Command``
+    subclasses.
+
+``data_files``
+
+    .. warning::
+        ``data_files`` is deprecated. It does not work with wheels, so it
+        should be avoided.
+
+    A list of strings specifying the data files to install.
+
+``package_dir``
+    A dictionary providing a mapping of package to directory names.
+
+``requires``
+
+   .. warning::
+      ``requires`` is superseded by ``install_requires`` and should not be used
+      anymore.
+
+``obsoletes``
+
+   .. warning::
+      ``obsoletes`` is currently ignored by ``pip``.
+
+   List of strings describing packages which this package renders obsolete,
+   meaning that the two projects should not be installed at the same time.
+
+   Version declarations can be supplied. Version numbers must be in the format
+   specified in Version specifiers (e.g. ``foo (<3.0)``).
+
+   This field may be followed by an environment marker after a semicolon (e.g.
+   ``foo; os_name == "posix"``)
+
+   The most common use of this field will be in case a project name changes,
+   e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install
+   Torqued Python, the Gorgon distribution should be removed.
+
+``provides``
+
+   .. warning::
+      ``provides`` is currently ignored by ``pip``.
+
+   List of strings describing package- and virtual package names contained
+   within this package.
+
+   A package may provide additional names, e.g. to indicate that multiple
+   projects have been bundled together. For instance, source distributions of
+   the ZODB project have historically included the transaction project, which
+   is now available as a separate distribution. Installing such a source
+   distribution satisfies requirements for both ZODB and transaction.
+
+   A package may also provide a “virtual” project name, which does not
+   correspond to any separately-distributed project: such a name might be used
+   to indicate an abstract capability which could be supplied by one of
+   multiple projects. E.g., multiple projects might supply RDBMS bindings for
+   use by a given ORM: each project might declare that it provides
+   ORM-bindings, allowing other projects to depend only on having at most one
+   of them installed.
+
+   A version declaration may be supplied and must follow the rules described in
+   Version specifiers. The distribution’s version number will be implied if
+   none is specified (e.g. ``foo (<3.0)``).
+
+   Each package may be followed by an environment marker after a semicolon
+   (e.g. ``foo; os_name == "posix"``).
+
+.. Below are setuptools keywords, above are distutils
+
+``include_package_data``
+    If set to ``True``, this tells ``setuptools`` to automatically include any
+    data files it finds inside your package directories that are specified by
+    your ``MANIFEST.in`` file.  For more information, see the section on
+    :ref:`Including Data Files`.
+
+``exclude_package_data``
+    A dictionary mapping package names to lists of glob patterns that should
+    be *excluded* from your package directories.  You can use this to trim back
+    any excess files included by ``include_package_data``.  For a complete
+    description and examples, see the section on :ref:`Including Data Files`.
+
+``package_data``
+    A dictionary mapping package names to lists of glob patterns.  For a
+    complete description and examples, see the section on :ref:`Including Data
+    Files`.  You do not need to use this option if you are using
+    ``include_package_data``, unless you need to add e.g. files that are
+    generated by your setup script and build process.  (And are therefore not
+    in source control or are files that you don't want to include in your
+    source distribution.)
+
+``zip_safe``
+    A boolean (True or False) flag specifying whether the project can be
+    safely installed and run from a zip file.  If this argument is not
+    supplied, the ``bdist_egg`` command will have to analyze all of your
+    project's contents for possible problems each time it builds an egg.
+
+``install_requires``
+    A string or list of strings specifying what other distributions need to
+    be installed when this one is.  See the section on :ref:`Declaring
+    Dependencies` for details and examples of the format of this argument.
+
+``entry_points``
+    A dictionary mapping entry point group names to strings or lists of strings
+    defining the entry points.  Entry points are used to support dynamic
+    discovery of services or plugins provided by a project.  See :ref:`Dynamic
+    Discovery of Services and Plugins` for details and examples of the format
+    of this argument.  In addition, this keyword is used to support
+    :ref:`Automatic Script Creation <entry_points>`.
+
+``extras_require``
+    A dictionary mapping names of "extras" (optional features of your project)
+    to strings or lists of strings specifying what other distributions must be
+    installed to support those features.  See the section on :ref:`Declaring
+    Dependencies` for details and examples of the format of this argument.
+
+``python_requires``
+    A string corresponding to a version specifier (as defined in PEP 440) for
+    the Python version, used to specify the Requires-Python defined in PEP 345.
+
+``setup_requires``
+
+    .. warning::
+        Using ``setup_requires`` is discouraged in favor of `PEP-518`_
+
+    A string or list of strings specifying what other distributions need to
+    be present in order for the *setup script* to run.  ``setuptools`` will
+    attempt to obtain these (even going so far as to download them using
+    ``EasyInstall``) before processing the rest of the setup script or commands.
+    This argument is needed if you are using distutils extensions as part of
+    your build process; for example, extensions that process setup() arguments
+    and turn them into EGG-INFO metadata files.
+
+    (Note: projects listed in ``setup_requires`` will NOT be automatically
+    installed on the system where the setup script is being run.  They are
+    simply downloaded to the ./.eggs directory if they're not locally available
+    already.  If you want them to be installed, as well as being available
+    when the setup script is run, you should add them to ``install_requires``
+    **and** ``setup_requires``.)
+
+.. _PEP-518: http://www.python.org/dev/peps/pep-0518/
+
+``dependency_links``
+
+    .. warning::
+        ``dependency_links`` is deprecated. It is not supported anymore by pip.
+
+    A list of strings naming URLs to be searched when satisfying dependencies.
+    These links will be used if needed to install packages specified by
+    ``setup_requires`` or ``tests_require``.  They will also be written into
+    the egg's metadata for use by tools like EasyInstall to use when installing
+    an ``.egg`` file.
+
+``namespace_packages``
+    A list of strings naming the project's "namespace packages".  A namespace
+    package is a package that may be split across multiple project
+    distributions.  For example, Zope 3's ``zope`` package is a namespace
+    package, because subpackages like ``zope.interface`` and ``zope.publisher``
+    may be distributed separately.  The egg runtime system can automatically
+    merge such subpackages into a single parent package at runtime, as long
+    as you declare them in each project that contains any subpackages of the
+    namespace package, and as long as the namespace package's ``__init__.py``
+    does not contain any code other than a namespace declaration.  See the
+    section on :ref:`Namespace Packages` for more information.
+
+``test_suite``
+    A string naming a ``unittest.TestCase`` subclass (or a package or module
+    containing one or more of them, or a method of such a subclass), or naming
+    a function that can be called with no arguments and returns a
+    ``unittest.TestSuite``.  If the named suite is a module, and the module
+    has an ``additional_tests()`` function, it is called and the results are
+    added to the tests to be run.  If the named suite is a package, any
+    submodules and subpackages are recursively added to the overall test suite.
+
+    Specifying this argument enables use of the :ref:`test` command to run the
+    specified test suite, e.g. via ``setup.py test``.  See the section on the
+    :ref:`test` command below for more details.
+
+    New in 41.5.0: Deprecated the test command.
+
+``tests_require``
+    If your project's tests need one or more additional packages besides those
+    needed to install it, you can use this option to specify them.  It should
+    be a string or list of strings specifying what other distributions need to
+    be present for the package's tests to run.  When you run the ``test``
+    command, ``setuptools`` will  attempt to obtain these (even going
+    so far as to download them using ``EasyInstall``).  Note that these
+    required projects will *not* be installed on the system where the tests
+    are run, but only downloaded to the project's setup directory if they're
+    not already installed locally.
+
+    New in 41.5.0: Deprecated the test command.
+
+.. _test_loader:
+
+``test_loader``
+    If you would like to use a different way of finding tests to run than what
+    setuptools normally uses, you can specify a module name and class name in
+    this argument.  The named class must be instantiable with no arguments, and
+    its instances must support the ``loadTestsFromNames()`` method as defined
+    in the Python ``unittest`` module's ``TestLoader`` class.  Setuptools will
+    pass only one test "name" in the ``names`` argument: the value supplied for
+    the ``test_suite`` argument.  The loader you specify may interpret this
+    string in any way it likes, as there are no restrictions on what may be
+    contained in a ``test_suite`` string.
+
+    The module name and class name must be separated by a ``:``.  The default
+    value of this argument is ``"setuptools.command.test:ScanningLoader"``.  If
+    you want to use the default ``unittest`` behavior, you can specify
+    ``"unittest:TestLoader"`` as your ``test_loader`` argument instead.  This
+    will prevent automatic scanning of submodules and subpackages.
+
+    The module and class you specify here may be contained in another package,
+    as long as you use the ``tests_require`` option to ensure that the package
+    containing the loader class is available when the ``test`` command is run.
+
+    New in 41.5.0: Deprecated the test command.
+
+``eager_resources``
+    A list of strings naming resources that should be extracted together, if
+    any of them is needed, or if any C extensions included in the project are
+    imported.  This argument is only useful if the project will be installed as
+    a zipfile, and there is a need to have all of the listed resources be
+    extracted to the filesystem *as a unit*.  Resources listed here
+    should be '/'-separated paths, relative to the source root, so to list a
+    resource ``foo.png`` in package ``bar.baz``, you would include the string
+    ``bar/baz/foo.png`` in this argument.
+
+    If you only need to obtain resources one at a time, or you don't have any C
+    extensions that access other files in the project (such as data files or
+    shared libraries), you probably do NOT need this argument and shouldn't
+    mess with it.  For more details on how this argument works, see the section
+    below on :ref:`Automatic Resource Extraction`.
+
+``project_urls``
+    An arbitrary map of URL names to hyperlinks, allowing more extensible
+    documentation of where various resources can be found than the simple
+    ``url`` and ``download_url`` options provide.