Improve examples of fetching package version in runtime

Author: dolfinus

CHANGELOG.rst

@@ -17,7 +17,13 @@ Changelog
         :tags: docs, feature
         :tickets: 17
 
-        Add small example of ``.gitignore`` file to common issues section
+        Add small example of ``.gitignore`` file to common issues section.
+
+    .. change::
+        :tags: docs, feature
+        :tickets: 55
+
+        Improve examples of fetching package version in runtime.
 
 .. changelog::
     :version: 1.13.1

docs/command.rst

@@ -73,7 +73,7 @@ This script is a wrapper for ``setuptools_git_versioning`` module, you can just
     DE8UG: Executing 'git rev-list -n 1 "1.0.0"' at '/path/to/mypackage'
      INF0: Tag SHA-256: '8dc9881eacd373cb34c5d3f99a6ad9e2349a79c4'
      INF0: Parsing tag_formatter 'util:tag_formatter' of type 'str'
-    DE8UG: Executing 'from mypkg.util import tag_formatter'
+    DE8UG: Executing 'from my_module.util import tag_formatter'
     DE8UG: Tag after formatting: '1.0.0'
     DE8UG: Executing 'git status --short' at '/path/to/mypackage'
      INF0: Is dirty: False

docs/options/branch_formatter.rst

@@ -40,7 +40,7 @@ you'll get version number which ``pip`` cannot understand.
 To fix that you can define a callback which will receive current branch
 name and return a properly formatted one:
 
-- ``mypkg/util.py`` file:
+- ``my_module/util.py`` file:
 
     .. code:: python
 
@@ -67,7 +67,7 @@ name and return a properly formatted one:
 
     .. code:: python
 
-        from mypkg.util import format_branch_name
+        from my_module.util import format_branch_name
 
         setuptools.setup(
             ...,
@@ -92,7 +92,7 @@ name and return a properly formatted one:
         enabled = true
         dev_template = "{branch}.dev{ccount}"
         dirty_template = "{branch}.dev{ccount}"
-        branch_formatter = "mypkg.util:format_branch_name"
+        branch_formatter = "my_module.util:format_branch_name"
 
     .. note::
 

docs/options/starting_version.rst

@@ -25,7 +25,7 @@ You can change this version by setting up ``starting_version`` option in your co
         )
 
 - ``pyproject.toml`` file:
--
+
     .. code:: toml
 
         [tool.setuptools-git-versioning]

docs/options/tag_formatter.rst

@@ -42,7 +42,7 @@ you'll get version number which ``pip`` cannot understand.
 To fix that you can define a callback which will receive current tag
 name and return a properly formatted one:
 
-- ``mypkg/util.py`` file:
+- ``my_module/util.py`` file:
 
     .. code:: python
 
@@ -68,7 +68,7 @@ name and return a properly formatted one:
 
     .. code:: python
 
-        from mypkg.util import format_tag_name
+        from my_module.util import format_tag_name
 
         setuptools.setup(
             ...,
@@ -93,7 +93,7 @@ name and return a properly formatted one:
         enabled = true
         dev_template = "{tag}.dev{ccount}"
         dirty_template = "{tag}.dev{ccount}"
-        tag_formatter = "mypkg.util:format_tag_name"
+        tag_formatter = "my_module.util:format_tag_name"
 
     .. note::
 

docs/runtime_version.rst

@@ -3,20 +3,83 @@
 Retrieving package version at runtime
 -------------------------------------
 
-Using ``version_file`` or ``version_callback`` options
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using ``version_file`` option (recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The preferred way to set version number inside a package is
-to simply store it in some file or variable/function, and
-then use it in ``setup.py`` / ``pyproject.toml`` as version source.
+In case of using :ref:`version_file <version-file>` option you can directly read the ``VERSION`` file content,
+and use at as version number.
 
-It this case you can get current version without any access to ``.git`` folder
-(which is required by ``setuptools-git-versioning``).
+To resolve version number in runtime, you should move ``VERSION`` file to your module subfolder:
 
-See:
+- ``setup.py``:
+
+    Create ``MANIFEST.in`` file in the project root:
+
+    .. code::
+
+        include my_module/VERSION
+
+    Then make few changes in ``setup.py``:
+
+    .. code:: python
+
+        ...
+
+        # change VERSION file path
+        version_file = root_path / "my_module" / "VERSION"
+
+        setuptools.setup(
+            ...,
+            setuptools_git_versioning={
+                "enabled": True,
+                "version_file": version_file,
+            },
+            # read MANIFEST.in and include files mentioned here to the package
+            include_package_data=True,
+            # this package will read some included files in runtime, avoid installing it as .zip
+            zip_safe=False,
+        )
+
+- ``pyproject.toml``:
+
+    .. code:: toml
+
+        [tool.setuptools.package-data]
+        # include VERSION file to a package
+        my_module = ["VERSION"]
+        # this package will read some included files in runtime, avoid installing it as .zip
+        zip-safe = false
+
+        [tool.setuptools-git-versioning]
+        enabled = true
+        # change the file path
+        version_file = "my_module/VERSION"
+
+And then read this file:
+
+.. code:: python
+
+    # content of my_module/__init__.py
+
+    from pathlib import Path
+
+    # you can use os.path and open() as well
+    __version__ = Path(__file__).parent.joinpath("VERSION").read_text()
+
+
+Using ``version_callback`` option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In case of using :ref:`version_callback <version-callback>` option you can directly call this callback inside a module:
+
+.. code:: python
+
+    # content of my_module/__init__.py
+
+    from my_module.version import get_version
+
+    __version__ = get_version()
 
-* :ref:`version-file`
-* :ref:`version-callback`
 
 Using ``importlib``
 ~~~~~~~~~~~~~~~~~~~
@@ -66,19 +129,19 @@ Calling internals of ``setuptools_git_versioning`` module
 
 .. warning::
 
-  This way is STRONGLY DISCOURAGED. Functions in the module
-  are not a part of public API, and could be changed in the future without
-  maintaining backward compatibility.
+    This way is STRONGLY DISCOURAGED. Functions in the module
+    are not a part of public API, and could be changed in the future without
+    maintaining backward compatibility.
 
 .. warning::
 
-  Use this ONLY in CI/CD tools.
+    Use this ONLY in CI/CD tools.
 
-  NEVER use ``setuptools_git_versioning`` inside your package, because ``.git``
-  folder is not being included into it, and target OS can lack of ``git`` executable.
+    NEVER use ``setuptools_git_versioning`` inside your package, because ``.git``
+    folder is not being included into it, and target OS can lack of ``git`` executable.
 
-  ``.git`` folder and ``git`` executable presence is crucial
-  for ``setuptools-git-versioning`` to work properly.
+    ``.git`` folder and ``git`` executable presence is crucial
+    for ``setuptools-git-versioning`` to work properly.
 
 .. code:: python
 

docs/schemas/callback/version_callback.rst

@@ -25,7 +25,7 @@ because there are no tags in the ``dev`` branch.
 
 If you want to get synchronized version numbers in both ``master`` and ``dev`` branches,
 you can create a function in some file (for example, in the
-``mypkg/version.py`` file):
+``my_module/version.py`` file):
 
 .. code:: python
 
@@ -36,7 +36,7 @@ Then place it in both the branches and update your ``setup.py`` or ``pyproject.t
 
 .. code:: python
 
-    from mypkg.version import get_version
+    from my_module.version import get_version
 
     setuptools.setup(
         ...,
@@ -55,15 +55,15 @@ Then place it in both the branches and update your ``setup.py`` or ``pyproject.t
 
     [tool.setuptools-git-versioning]
     enabled = true
-    version_callback = "mypkg.version:get_version"
+    version_callback = "my_module.version:get_version"
 
 When you'll try to get current version in **any** branch, the result
 of executing this function will be returned instead of latest tag
 number.
 
 If a value of this option is not a function but just str, it also could be used:
 
--  ``mypkg/__init__.py`` file:
+-  ``my_module/__init__.py`` file:
 
     .. code:: python
 
@@ -73,13 +73,13 @@ If a value of this option is not a function but just str, it also could be used:
 
     .. code:: python
 
-        import mypkg
+        import my_module
 
         setuptools.setup(
             ...,
             setuptools_git_versioning={
                 "enabled": True,
-                "version_callback": mypkg.__version__,
+                "version_callback": my_module.__version__,
             },
         )
 
@@ -92,7 +92,7 @@ If a value of this option is not a function but just str, it also could be used:
 
         [tool.setuptools-git-versioning]
         enabled = true
-        version_callback = "mypkg:__version__"
+        version_callback = "my_module:__version__"
 
 **Please take into account that any tag in the branch is completely ignored if version_callback
 is set**.
@@ -105,3 +105,4 @@ You should explicitly call ``setuptools_git_versioning.version_from_git`` functi
 See also
 """"""""
 - :ref:`version-callback-option` option
+- :ref:`runtime-version`

docs/schemas/file/index.rst

@@ -3,12 +3,21 @@
 File-based release (recommended)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
+By default, ``setuptools-git-versioning`` can be used only within:
 
-    Prefer this schema because it allows to get a version number in the following cases:
-        * Downloading source tarball without ``.git`` folder (:issue:`77`).
-        * Shallow repo clone without tags (:issue:`75`).
-        * Getting version number from a branch which does not contain any tags (`Git-flow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`__ and its derivatives)
+* git repo, which means a ``.git`` subfolder should exist in the repo root folder
+* branch with at least one tag
+
+Otherwise it will be impossible to get project version based on the git repo commits,
+and ``setuptools-git-versioning`` will return version number ``0.0.1`` (or other value set up by :ref:`starting-version-option`).
+
+But one or all of these requirements cannot be satisfied in the following cases:
+
+* Downloading source tarball without ``.git`` folder (:issue:`77`).
+* Shallow repo clone without tags (:issue:`75`).
+* Getting version number from a branch which does not contain any tags (`Git-flow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`__ and its derivatives)
+
+To avoid getting meaningless version number prefer using versioning schema described below.
 
 .. toctree::
     :maxdepth: 1

docs/schemas/file/version_file.rst

@@ -39,16 +39,17 @@ Then place it in both the branches and update your config file:
 
     .. code:: python
 
-        import os
+        # you can use os.path instead of pathlib
+        from pathlib import Path
 
-        HERE = os.path.dirname(__file__)
-        VERSION_FILE = os.path.join(HERE, "VERSION")
+        root_path = Path(__file__).parent
+        version_file = root_path / "VERSION"
 
         setuptools.setup(
             ...,
             setuptools_git_versioning={
                 "enabled": True,
-                "version_file": VERSION_FILE,
+                "version_file": version_file,
             },
         )
 
@@ -63,10 +64,11 @@ Then place it in both the branches and update your config file:
 When you'll try to get current version in non-master branch, the content
 of this file (``1.0.0``) will be returned instead default version number.
 
-**Please take into account that version_file is ignored if tag
-is present**
+**Please take into account that version_file is ignored if any tag
+is present in the current branch.**
 
 See also
 """""""""
 - :ref:`version-callback`
 - :ref:`version-file-option` option
+- :ref:`runtime-version`

setup.py

@@ -1,26 +1,22 @@
-import os
+from pathlib import Path
 from setuptools import setup, find_packages
 from setuptools_git_versioning import version_from_git
 
-HERE = os.path.dirname(os.path.abspath(__file__))
 
+def parse_requirements(file: Path) -> list[str]:
+    lines = file.read_text().splitlines()
+    return [line.rstrip() for line in lines if line and not line.startswith("#")]
 
-def parse_requirements(file_content):
-    lines = file_content.splitlines()
-    return [line.strip() for line in lines if line and not line.startswith("#")]
 
-
-with open(os.path.join(HERE, "README.rst")) as f:
-    long_description = f.read()
-
-with open(os.path.join(HERE, "requirements.txt")) as f:
-    requirements = parse_requirements(f.read())
+here = Path(__file__).parent.resolve()
+requirements = parse_requirements(here / "requirements.txt")
+long_description = here.joinpath("README.rst").read_text()
 
 setup(
     name="setuptools-git-versioning",
     # +local version is not allowed in PyPI
     # https://github.com/pypa/pypi-legacy/issues/731#issuecomment-345461596
-    version=version_from_git(root=HERE, dev_template="{tag}.post{ccount}"),
+    version=version_from_git(root=here, dev_template="{tag}.post{ccount}"),
     author="dolfinus",
     author_email="[email protected]",
     description="Use git repo data for building a version number according PEP-440",