Version file
=============

Auto generated by setuptools-scm. setuptools-scm recommends not to put
the version file within the sdist (tarball .tar.gz).

Later learned readthedocs insists the version be available from the
package. So included the version file within the repo

The version file is a generated file. That's exactly what build plugin
were born for! During build, the version file is regenerated.

When kitting, special attention must be paid to this file!

**Define location of version file**

In pyproject.toml,

.. code-block:: text

   [project]
   dynamic = [
       "optional-dependencies",
       "dependencies",
       "version",
   ]

   [tool.setuptools.dynamic]
   version = {attr = "drain_swamp._version.__version__"}

   [tool.pipenv-unlock]
   version_file = "src/drain_swamp/_version.py"

Yes it's defined twice. One is a dotted path other is the relative path

**read and write**

From version file, get (tag) version

.. code-block:: shell

   drain-swamp tag

Write semantic version str to version file

.. code-block:: shell

   scm-version write "0.0.1"

**Check and fix** semantic version str

.. code-block:: shell

   drain-swamp pretag "0.0.1.candidate1.post4.dev3"

0.0.1rc1.post4.dev3

python equivalents

.. doctest:: pretag_dev

   >>> from drain_swamp.igor_utils import pretag
   >>> is_success, ver = pretag("0.0.1dev1")
   >>> ver
   '0.0.1.dev1'

.. doctest:: pretag_postdev

   >>> from drain_swamp.igor_utils import pretag
   >>> is_success, ver = pretag("0.0.1post3dev4")
   >>> ver
   '0.0.1.post3.dev4'

.. code-block:: shell

   drain-swamp pretag "0.0.1rc3dev2"

python equivalent

.. doctest:: pretag_release_candidate_dev

   >>> from drain_swamp.igor_utils import pretag
   >>> is_success, ver = pretag("0.0.1rc3dev2")
   >>> ver
   '0.0.1rc3.dev2'

**With epoch and local**

Notice single quotes to escape the ``!``

.. code-block:: shell

   drain-swamp pretag '1!0.0.1rc3dev2+gasdfgh.d20240501'

(python equivalent doctest friendly)

.. doctest:: pretag_escape_epoch

   >>> from drain_swamp.igor_utils import pretag
   >>> is_success, ver = pretag("1!0.0.1rc3dev2+gasdfgh.d20240501")
   >>> ver
   '0.0.1rc3.dev2'

.. code-block:: shell

   drain-swamp pretag '1!v0.0.1alpha3dev2+gasdfgh.d20240501'

(python equivalent doctest friendly)

.. doctest:: pretag_alpha

   >>> from drain_swamp.igor_utils import pretag
   >>> is_success, ver = pretag("1!v0.0.1alpha3dev2+gasdfgh.d20240501")
   >>> ver
   '0.0.1a3.dev2'

The epoch and local and prepended "v" are stripped. And the remainder is sanitized

.. seealso::

   :doc:`build package </getting_started/build-package>`

.. py:data:: __version__
   :type: str

   The semantic version, e.g. "0.0.1". This is the full semantic string which can
   include development, pre and post releases, and release candidates

.. py:data:: __version_tuple__
   :type: tuple[int | str, ...]

   Full semantic string as a tuple

Aliases --> Unused

.. py:data:: version
   :type: str

   Alias of __version__

.. py:data:: version_tuple
   :type: tuple[int | str, ...]

   Alias of __version_tuple__