<commit_before>setuptools_scm
==============

``setuptools_scm`` handles managing your Python package versions
in SCM metadata instead of declaring them as the version argument
or in a SCM managed file.

Additionally ``setuptools_scm`` provides setuptools with a list of files that are managed by the SCM
(i.e. it automatically adds all of the SCM-managed files to the sdist).
Unwanted files must be excluded by discarding them via ``MANIFEST.in``.

``setuptools_scm`` support the following scm out of the box:

* git
* mercurial



.. image:: https://github.com/pypa/setuptools_scm/workflows/python%20tests+artifacts+release/badge.svg
    :target: https://github.com/pypa/setuptools_scm/actions

.. image:: https://tidelift.com/badges/package/pypi/setuptools-scm
   :target: https://tidelift.com/subscription/pkg/pypi-setuptools-scm?utm_source=pypi-setuptools-scm&utm_medium=readme


``pyproject.toml`` usage
------------------------

The preferred way to configure ``setuptools_scm`` is to author
settings in a ``tool.setuptools_scm`` section of ``pyproject.toml``.

This feature requires Setuptools 42 or later, released in Nov, 2019.
If your project needs to support build from sdist on older versions
of Setuptools, you will need to also implement the ``setup.py usage``
for those legacy environments.

First, ensure that ``setuptools_scm`` is present during the project's
built step by specifying it as one of the build requirements.

.. code:: toml

    # pyproject.toml
    [build-system]
    requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.0"]

Note that the ``toml`` extra must be supplied.

That will be sufficient to require ``setuptools_scm`` for projects
that support PEP 518 (`pip <https://pypi.org/project/pip>`_ and
`pep517 <https://pypi.org/project/pep517/>`_). Many tools,
especially those that invoke ``setup.py`` for any reason, may
continue to rely on ``setup_requires``. For maximum compatibility
with those uses, consider also including a ``setup_requires`` directive
(described below in ``setup.py usage`` and ``setup.cfg``).

To enable version inference, add this section to your pyproject.toml:

.. code:: toml

    # pyproject.toml
    [tool.setuptools_scm]

Including this section is comparable to supplying
``use_scm_version=True`` in ``setup.py``. Additionally,
include arbitrary keyword arguments in that section
to be supplied to ``get_version()``. For example:

.. code:: toml

    # pyproject.toml

    [tool.setuptools_scm]
    write_to = "pkg/version.py"


``setup.py`` usage
------------------

The following settings are considered legacy behavior and
superseded by the ``pyproject.toml`` usage, but for maximal
compatibility, projects may also supply the configuration in
this older form.

To use ``setuptools_scm`` just modify your project's ``setup.py`` file
like this:

* Add ``setuptools_scm`` to the ``setup_requires`` parameter.
* Add the ``use_scm_version`` parameter and set it to ``True``.

For example:

.. code:: python

    from setuptools import setup
    setup(
        ...,
        use_scm_version=True,
        setup_requires=['setuptools_scm'],
        ...,
    )

Arguments to ``get_version()`` (see below) may be passed as a dictionary to
``use_scm_version``. For example:

.. code:: python

    from setuptools import setup
    setup(
        ...,
        use_scm_version = {
            "root": "..",
            "relative_to": __file__,
            "local_scheme": "node-and-timestamp"
        },
        setup_requires=['setuptools_scm'],
        ...,
    )

You can confirm the version number locally via ``setup.py``:

.. code-block:: shell

    $ python setup.py --version

.. note::

   If you see unusual version numbers for packages but ``python setup.py
   --version`` reports the expected version number, ensure ``[egg_info]`` is
   not defined in ``setup.cfg``.


``setup.cfg`` usage
-------------------

as ``setup_requires`` is deprecated in favour of ``pyproject.toml``
usage in ``setup.cfg`` is considered deprecated,
please use ``pyproject.toml`` whenever possible.

Programmatic usage
------------------

In order to use ``setuptools_scm`` from code that is one directory deeper
than the project's root, you can use:

.. code:: python

    from setuptools_scm import get_version
    version = get_version(root='..', relative_to=__file__)

See `setup.py Usage`_ above for how to use this within ``setup.py``.


Retrieving package version at runtime
-------------------------------------

If you have opted not to hardcode the version number inside the package,
you can retrieve it at runtime from PEP-0566_ metadata using
``importlib.metadata`` from the standard library (added in Python 3.8)
or the `importlib_metadata`_ backport:

.. code:: python

    from importlib.metadata import version, PackageNotFoundError

    try:
        __version__ = version("package-name")
    except PackageNotFoundError:
        # package is not installed
        pass

Alternatively, you can use ``pkg_resources`` which is included in
``setuptools``:

.. code:: python

   from pkg_resources import get_distribution, DistributionNotFound

   try:
       __version__ = get_distribution("package-name").version
   except DistributionNotFound:
        # package is not installed
       pass

However, this does place a runtime dependency on ``setuptools`` and can add up to
a few 100ms overhead for the package import time.

.. _PEP-0566: https://www.python.org/dev/peps/pep-0566/
.. _importlib_metadata: https://pypi.org/project/importlib-metadata/


Usage from Sphinx
-----------------

It is discouraged to use ``setuptools_scm`` from Sphinx itself,
instead use ``pkg_resources`` after editable/real installation:

.. code:: python

    from importlib.metadata import version

    release = version("package-name")
    version = '.'.join(release.split('.')[:2])

The underlying reason is, that services like *Read the Docs* sometimes change
the working directory for good reasons and using the installed metadata
prevents using needless volatile data there.

Notable Plugins
---------------

`setuptools_scm_git_archive <https://pypi.python.org/pypi/setuptools_scm_git_archive>`_
    Provides partial support for obtaining versions from git archives that
    belong to tagged versions. The only reason for not including it in
    ``setuptools_scm`` itself is Git/GitHub not supporting sufficient metadata
    for untagged/followup commits, which is preventing a consistent UX.<commit_msg>README: remove incorrect mention of pkg_resources<commit_after>setuptools_scm
==============

``setuptools_scm`` handles managing your Python package versions
in SCM metadata instead of declaring them as the version argument
or in a SCM managed file.

Additionally ``setuptools_scm`` provides setuptools with a list of files that are managed by the SCM
(i.e. it automatically adds all of the SCM-managed files to the sdist).
Unwanted files must be excluded by discarding them via ``MANIFEST.in``.

``setuptools_scm`` support the following scm out of the box:

* git
* mercurial



.. image:: https://github.com/pypa/setuptools_scm/workflows/python%20tests+artifacts+release/badge.svg
    :target: https://github.com/pypa/setuptools_scm/actions

.. image:: https://tidelift.com/badges/package/pypi/setuptools-scm
   :target: https://tidelift.com/subscription/pkg/pypi-setuptools-scm?utm_source=pypi-setuptools-scm&utm_medium=readme


``pyproject.toml`` usage
------------------------

The preferred way to configure ``setuptools_scm`` is to author
settings in a ``tool.setuptools_scm`` section of ``pyproject.toml``.

This feature requires Setuptools 42 or later, released in Nov, 2019.
If your project needs to support build from sdist on older versions
of Setuptools, you will need to also implement the ``setup.py usage``
for those legacy environments.

First, ensure that ``setuptools_scm`` is present during the project's
built step by specifying it as one of the build requirements.

.. code:: toml

    # pyproject.toml
    [build-system]
    requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.0"]

Note that the ``toml`` extra must be supplied.

That will be sufficient to require ``setuptools_scm`` for projects
that support PEP 518 (`pip <https://pypi.org/project/pip>`_ and
`pep517 <https://pypi.org/project/pep517/>`_). Many tools,
especially those that invoke ``setup.py`` for any reason, may
continue to rely on ``setup_requires``. For maximum compatibility
with those uses, consider also including a ``setup_requires`` directive
(described below in ``setup.py usage`` and ``setup.cfg``).

To enable version inference, add this section to your pyproject.toml:

.. code:: toml

    # pyproject.toml
    [tool.setuptools_scm]

Including this section is comparable to supplying
``use_scm_version=True`` in ``setup.py``. Additionally,
include arbitrary keyword arguments in that section
to be supplied to ``get_version()``. For example:

.. code:: toml

    # pyproject.toml

    [tool.setuptools_scm]
    write_to = "pkg/version.py"


``setup.py`` usage
------------------

The following settings are considered legacy behavior and
superseded by the ``pyproject.toml`` usage, but for maximal
compatibility, projects may also supply the configuration in
this older form.

To use ``setuptools_scm`` just modify your project's ``setup.py`` file
like this:

* Add ``setuptools_scm`` to the ``setup_requires`` parameter.
* Add the ``use_scm_version`` parameter and set it to ``True``.

For example:

.. code:: python

    from setuptools import setup
    setup(
        ...,
        use_scm_version=True,
        setup_requires=['setuptools_scm'],
        ...,
    )

Arguments to ``get_version()`` (see below) may be passed as a dictionary to
``use_scm_version``. For example:

.. code:: python

    from setuptools import setup
    setup(
        ...,
        use_scm_version = {
            "root": "..",
            "relative_to": __file__,
            "local_scheme": "node-and-timestamp"
        },
        setup_requires=['setuptools_scm'],
        ...,
    )

You can confirm the version number locally via ``setup.py``:

.. code-block:: shell

    $ python setup.py --version

.. note::

   If you see unusual version numbers for packages but ``python setup.py
   --version`` reports the expected version number, ensure ``[egg_info]`` is
   not defined in ``setup.cfg``.


``setup.cfg`` usage
-------------------

as ``setup_requires`` is deprecated in favour of ``pyproject.toml``
usage in ``setup.cfg`` is considered deprecated,
please use ``pyproject.toml`` whenever possible.

Programmatic usage
------------------

In order to use ``setuptools_scm`` from code that is one directory deeper
than the project's root, you can use:

.. code:: python

    from setuptools_scm import get_version
    version = get_version(root='..', relative_to=__file__)

See `setup.py Usage`_ above for how to use this within ``setup.py``.


Retrieving package version at runtime
-------------------------------------

If you have opted not to hardcode the version number inside the package,
you can retrieve it at runtime from PEP-0566_ metadata using
``importlib.metadata`` from the standard library (added in Python 3.8)
or the `importlib_metadata`_ backport:

.. code:: python

    from importlib.metadata import version, PackageNotFoundError

    try:
        __version__ = version("package-name")
    except PackageNotFoundError:
        # package is not installed
        pass

Alternatively, you can use ``pkg_resources`` which is included in
``setuptools``:

.. code:: python

   from pkg_resources import get_distribution, DistributionNotFound

   try:
       __version__ = get_distribution("package-name").version
   except DistributionNotFound:
        # package is not installed
       pass

However, this does place a runtime dependency on ``setuptools`` and can add up to
a few 100ms overhead for the package import time.

.. _PEP-0566: https://www.python.org/dev/peps/pep-0566/
.. _importlib_metadata: https://pypi.org/project/importlib-metadata/


Usage from Sphinx
-----------------

It is discouraged to use ``setuptools_scm`` from Sphinx itself,
instead use ``importlib.metadata`` after editable/real installation:

.. code:: python

    from importlib.metadata import version

    release = version("package-name")
    version = '.'.join(release.split('.')[:2])

The underlying reason is, that services like *Read the Docs* sometimes change
the working directory for good reasons and using the installed metadata
prevents using needless volatile data there.

Notable Plugins
---------------

`setuptools_scm_git_archive <https://pypi.python.org/pypi/setuptools_scm_git_archive>`_
    Provides partial support for obtaining versions from git archives that
    belong to tagged versions. The only reason for not including it in
    ``setuptools_scm`` itself is Git/GitHub not supporting sufficient metadata
    for untagged/followup commits, which is preventing a consistent UX.
{'fraction_non_alphanumeric': 0.12148308024358283, 'fraction_numerical': 0.006012487473984429, 'mean_word_length': 3.5347780496329952, 'pattern_counts': {'":': 6, '<': 9, '<?xml version=': 0, '>': 13, 'https://': 18, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2032827', 'n_tokens_mistral': 3883, 'n_tokens_neox': 3679, 'n_words': 1362}