Dynamic versioning
===================

pyproject.toml
---------------

.. code-block:: text

   [build-system]
   requires = [
       "setuptools>=70.0.0",
       "wheel",
       "build",
       "setuptools_scm>=8",
       "drain-swamp",
       "drain-swamp-snippet",
   ]
   build-backend = "setuptools.build_meta"

   [project]
   # drain-swamp grabs package name from here
   name = "your-package-name"

   # See getting start --> Dependencies
   dynamic = [
       "optional-dependencies",
       "dependencies",
       "version",
   ]

   # drain-swamp sources first name from here
   authors = [  # Contact by mastodon please
       {name = "Dave Faulkmore", email = "faulkmore@protonmail.com"},
   ]

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

   [tool.setuptools.packages.find]
   where = ["src"]
   include = ["your_package_name*"]

   [tool.setuptools.dynamic]
   # @@@ editable little_shop_of_horrors_shrine_candles
   dependencies = { file = ["requirements/prod.lnk"] }
   optional-dependencies.pip = { file = ["requirements/pip.lnk"] }
   optional-dependencies.manage = { file = ["requirements/manage.lnk"] }
   # @@@ end

   [tool.drain-swamp]
   copyright_start_year = 2024

   [tool.pipenv-unlock]
   # wraps-build-backend = "setuptools.build_meta"
   version_file = "src/complete_awesome_perfect/_version.py"
   folders = [
       "ci",
   ]

   required = { target = "prod", relative_path = "requirements/prod.in" }

   # underscore: hyphen
   optionals = [
       { target = "pip", relative_path = "requirements/pip.in" },
       { target = "manage", relative_path = "requirements/manage.in" },
   ]

Change ``drain_swamp`` to your package name (underscores, not hyphens)

Provide defaults
"""""""""""""""""

.. code-block:: text

   [tool.drain-swamp]
   copyright_start_year = 2024  # this is an int, not a str

Default value for copyright_start_year is 1970

\_version.py
--------------

Here is an example ``_version.py`` file. Might need this, before the
first commit or tagged release

.. code-block:: text

   # file generated by setuptools_scm
   # don't change, don't track in version control
   TYPE_CHECKING = False
   if TYPE_CHECKING:
       from typing import Tuple, Union
       VERSION_TUPLE = Tuple[Union[int, str], ...]
   else:
       VERSION_TUPLE = object

   version: str
   __version__: str
   __version_tuple__: VERSION_TUPLE
   version_tuple: VERSION_TUPLE

   __version__ = version = '0.0.2'
   __version_tuple__ = version_tuple = (0, 0, 2)

Always automatically generated, so don't bother fixing the static typing

Keep an eye on ``src/[package_name]/_version.py``

Beyond ``[major].[minor].[micro]`` learn about when to be using
alpha/beta/post/rc releases.

static typing
--------------

Here is ``_version.pyi`` so don't duplicate efforts.

.. code-block:: text

   from typing import Final

   version: Final[str]
   __version__: Final[str]
   __version_tuple__: Final[tuple[int | str, ...]]
   version_tuple: Final[tuple[int | str, ...]]