WIP: updated single_source_version with a much simpler page.

source/single_source_version.rst

@@ -7,111 +7,45 @@ Single-sourcing the Project Version
 :Page Status: Complete
 :Last Reviewed: 2015-09-08
 
+One of the challenges in building packages is that the version string can be required in multiple places.
 
-There are a few techniques to store the version in your project code without duplicating the value stored in
-``setup.py``:
+* It needs to be specified when building the package (e.g. in pyproject.toml)
+   - That will assure that it is properly assigned in the distribution file name, and in teh installed package.
 
-#.  Read the file in ``setup.py`` and parse the version with a regex. Example (
-    from `pip setup.py <https://github.com/pypa/pip/blob/1.5.6/setup.py#L33>`_)::
+* Some projects require that there be a version string available as an attribute in the importable module, e.g::
 
-        def read(*names, **kwargs):
-            with io.open(
-                os.path.join(os.path.dirname(__file__), *names),
-                encoding=kwargs.get("encoding", "utf8")
-            ) as fp:
-                return fp.read()
+    import a_package
+    print(a_package.__version__)
 
-        def find_version(*file_paths):
-            version_file = read(*file_paths)
-            version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]",
-                                      version_file, re.M)
-            if version_match:
-                return version_match.group(1)
-            raise RuntimeError("Unable to find version string.")
+While different projects have different needs, it's important to make sure that there is a single source of truth for the version number.
 
-        setup(
-           ...
-           version=find_version("package", "__init__.py")
-           ...
-        )
+In general, the options are:
 
-    .. note::
+1) If the code is in a version control system (VCS), e.g. git, then the version can be extracted from the VCS.
 
-        This technique has the disadvantage of having to deal with complexities of regular expressions.
+2) The version can be hard-coded into the `pyproject.toml` file -- and the build system can copy it into other locations it may be required.
 
-#.  Use an external build tool that either manages updating both locations, or
-    offers an API that both locations can use.
+3) The version string can be hard-coded into the source code -- either in a special purpose file, such as `_version.txt`, or as a attribute in the `__init__.py`, and the build system can extract it at build time.
 
-    Few tools you could use, in no particular order, and not necessarily complete:
-    `bumpversion <https://pypi.python.org/pypi/bumpversion>`_,
-    `changes <https://pypi.python.org/pypi/changes>`_, `zest.releaser <https://pypi.python.org/pypi/zest.releaser>`_.
+If the version string is not in the source, it can be extracted at runtime with code in `__init__.py`, such as::
 
+    import importlib.metadata
+    __version__ = importlib.metadata.version('the_distribution_name')
 
-#.  Set the value to a ``__version__`` global variable in a dedicated module in
-    your project (e.g. ``version.py``), then have ``setup.py`` read and ``exec`` the
-    value into a variable.
 
-    Using ``execfile``:
+Consult your build system documentation for how to implement your preferred method.
 
-    ::
+Put links in to build system docs?
+-- I have no idea which are currently robust and maintained -- do we want to get into seeming endorsing particular tools in this doc?
 
-        execfile('...sample/version.py')
-        # now we have a `__version__` variable
-        # later on we use: __version__
 
-    Using ``exec``:
+* setuptools:
 
-    ::
+* hatch:
 
-        version = {}
-        with open("...sample/version.py") as fp:
-            exec(fp.read(), version)
-        # later on we use: version['__version__']
+* poetry:
 
-    Example using this technique: `warehouse <https://github.com/pypa/warehouse/blob/master/warehouse/__about__.py>`_.
+* PyBuilder:
 
-#.  Place the value in a simple ``VERSION`` text file and have both ``setup.py``
-    and the project code read it.
+* Others?
 
-    ::
-
-        with open(os.path.join(mypackage_root_dir, 'VERSION')) as version_file:
-            version = version_file.read().strip()
-
-    An advantage with this technique is that it's not specific to Python.  Any
-    tool can read the version.
-
-    .. warning::
-
-        With this approach you must make sure that the ``VERSION`` file is included in
-        all your source and binary distributions.
-
-#.  Set the value in ``setup.py``, and have the project code use the
-    ``pkg_resources`` API.
-
-    ::
-
-        import pkg_resources
-        assert pkg_resources.get_distribution('pip').version == '1.2.0'
-
-    Be aware that the ``pkg_resources`` API only knows about what's in the
-    installation metadata, which is not necessarily the code that's currently
-    imported.
-
-
-#.  Set the value to ``__version__`` in ``sample/__init__.py`` and import
-    ``sample`` in ``setup.py``.
-
-    ::
-
-        import sample
-        setup(
-            ...
-            version=sample.__version__
-            ...
-        )
-
-    Although this technique is common, beware that it will fail if
-    ``sample/__init__.py`` imports packages from ``install_requires``
-    dependencies, which will very likely not be installed yet when ``setup.py``
-    is run.