simplify setuptools-scm configuration use builtin handlers

- fix(setup.py): setuptools-scm configuration use setuptools-scm builtin handlers
- docs(setup.py): setuptools-scm docs are sparse. Explain as if to a six year old

CHANGES.rst

@@ -18,10 +18,18 @@ Changelog
    - ci/kit.yml in sdist Set output tag will be branch name, not tag name see ci/release.yml
 
    Commit items for NEXT VERSION
-   .................................
+   ..............................
 
 .. scriv-start-here
 
+.. _changes_1-2-23:
+
+Version 1.2.23 — 2024-03-09
+---------------------------
+
+- fix(setup.py): setuptools-scm configuration use setuptools-scm builtin handlers
+- docs(setup.py): setuptools-scm docs are sparse. Explain as if to a six year old
+
 .. _changes_1-2-22:
 
 Version 1.2.22 — 2024-03-09

docs/conf.py

@@ -60,9 +60,9 @@
 # @@@ editable
 copyright = "2023–2024, Dave Faulkmore"
 # The short X.Y.Z version.
-version = "1.2.22"
+version = "1.2.23"
 # The full version, including alpha/beta/rc tags.
-release = "1.2.22"
+release = "1.2.23"
 # The date of release, in "monthname day, year" format.
 release_date = "March 9, 2024"
 # @@@ end

setup.py

@@ -1,52 +1,71 @@
 from __future__ import annotations
 
 from setuptools import setup
-from setuptools_scm import ScmVersion
-from setuptools_scm.version import get_local_dirty_tag
+from setuptools_scm.version import (
+    get_local_node_and_date,
+    guess_next_dev_version,
+)
 
 
 def _clean_version() -> dict[str, str]:
-    """scm is generating developer versions, rather than tagged versions
+    """``setuptools-scm`` get the current version if you're in a tagged commit.
+    When not, most of the time, tries very hard to "guess" the next version
+    dividing it in two parts, the "version" and the "local" part, with the
+    format {version}+{local}, both of them can be configured.
 
-    dict communicating between :menuselection:`setuptools_scm --> setuptools`
+    CI/CD configuration
 
-    :returns: start folder relative path. e.g. tests/ui
-    :rtype: dict[str, str]
+    Runs on every push, but setup to do nothing unless on a tagged release
 
-    .. seealso::
+    LOCAL
 
-       `Credit <https://stackoverflow.com/q/73157896>`_
+    Options
 
-    """
+    - node-and-date (default)
+    - node-and-timestamp
+    - dirty-tag
+    - no-local-version
 
-    def get_version(version: ScmVersion) -> str:
-        """Get local scheme. Aka tagged version
+    Although pypi only accepts ``no-local-version``, chose
+    ``node-and-date`` (:py:func:`get_local_node_and_date`)
 
-        :param version: Version as setuptools_scm grabs from vcs
-        :type version: :py:class:`setuptools_scm.ScmVersion`
-        :returns: local scheme
-        :rtype: str
-        """
-        # str(version.tag)
-        return version.format_with("{tag}")
+    Rationale:
 
-    def clean_scheme(version: ScmVersion) -> str:
-        """Full version from vcs
+    - when testing locally, a non-local version build would be very confusing
 
-        When readthedocs.org builds the docs, "+clean" is prepended to
-        version causing a failure to build the docs. What is "+clean"
-        for?! Remove it
+    - never have uncommitted files in workdir (+dirty or +clean)
 
-        :param version: Version as setuptools_scm grabs from vcs
-        :type version: :py:class:`setuptools_scm.ScmVersion`
-        :returns: version scheme
-        :rtype: str
-        """
-        return get_local_dirty_tag(version) if version.dirty else ""
+    VERSION
 
-    return {"local_scheme": get_version, "version_scheme": clean_scheme}
+    Try default, ``guess-next-dev``
+
+    :returns:
+
+       dict containing handlers for version_scheme and local_scheme. The
+       resulting str are combined with format, ``{version}+{local}``
+
+    :rtype: dict[str, str]
+
+    .. seealso::
+
+       Built-in
+       `[version_scheme] <https://setuptools-scm.readthedocs.io/en/latest/extending/#setuptools_scmversion_scheme>`_
+       handlers
+
+       Built-in
+       `[local_scheme] <https://setuptools-scm.readthedocs.io/en/latest/extending/#setuptools_scmlocal_scheme>`_
+       handlers
+
+       For usage, see :py:mod:`logging_strict.constants`
+
+    """
+    return {
+        "local_scheme": get_local_node_and_date,
+        "version_scheme": guess_next_dev_version,
+    }
 
 
+# dict communicating between :menuselection:`setuptools_scm --> setuptools`
 setup(
     use_scm_version=_clean_version,
 )

src/logging_strict/constants.py

@@ -22,27 +22,34 @@
 When releasing this is not what is wanted, so use
 SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT with the version
 
+- Current version
+
+  .. code-block:: shell
+
+     PYTHONWARNINGS="ignore" python setup.py --version
+
+
 - Release by tag aka final
 
   .. code-block:: shell
 
-     SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="$(git describe --tag)" python setup.py --version
+     PYTHONWARNINGS="ignore" SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="$(git describe --tag)" python setup.py --version
      SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="$(git describe --tag)" python -m build
 
 
 - alpha: a, beta: b, or candidate: rc
 
   .. code-block:: shell
 
-     SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="0.1.1a1" python setup.py --version
+     PYTHONWARNINGS="ignore" SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="0.1.1a1" python setup.py --version
      SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="0.1.1a1" python -m build
 
 
 - dev
 
   .. code-block:: shell
 
-     SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="0.1.1a1.dev1" python setup.py --version
+     PYTHONWARNINGS="ignore" SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="0.1.1a1.dev1" python setup.py --version
      SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="0.1.1a1.dev1" python -m build
 
 
@@ -52,11 +59,10 @@
 
   .. code-block:: shell
 
-     SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="0.1.1.post1" python setup.py --version
+     PYTHONWARNINGS="ignore" SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="0.1.1.post1" python setup.py --version
      SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LOGGING_STRICT="0.1.1.post1" python -m build
 
 
-
 Module private variables
 -------------------------