version-query 1.6.3.dev0__tar.gz → 1.7.0__tar.gz

{version_query-1.6.3.dev0/version_query.egg-info → version_query-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: version-query
-Version: 1.6.3.dev0
+Version: 1.7.0
 Summary: Zero-overhead package versioning for Python.
 Home-page: https://github.com/mbdevpl/version-query
 Download-URL: 
@@ -81,7 +81,7 @@ Zero-overhead package versioning for Python.
     :alt: grade from Codacy
 
 .. image:: https://img.shields.io/github/license/mbdevpl/version-query.svg
-    :target: https://github.com/mbdevpl/version-query/blob/v1.6.3.dev0/NOTICE
+    :target: https://github.com/mbdevpl/version-query/blob/v1.7.0/NOTICE
     :alt: license
 
 Package versioning toolkit for Python which relies on git tags, git history traversal
@@ -94,34 +94,43 @@ for easier development, testing and pre-release deployment?!
 
 Search no more!
 
-As long as you mark your releases using git tags, instead of hardcoding:
+As long as you use git and you mark your releases using git tags, version-query will do the rest.
 
-.. code:: python
+It's 21st century, stop hardcoding version numbers!
 
-    __version__ = '1.5.0.dev2'
+.. contents::
+    :backlinks: none
 
-You can do:
 
-.. code:: python
+Overview
+========
 
-    from version_query import predict_version_str
+There are two main ways of using version-query - at runtime or at build time.
 
-    __version__ = predict_version_str()
+Using at runtime
+----------------
 
-It's 21st century, stop hardcoding version numbers!
+When using this way, version-query is needed as a runtime dependency of your package.
 
-This will set the version to release version when you really release a new version,
-and it will automatically generate a suitable development version at development/pre-release phase.
+If, for example, you have a constant storing the version of your package in some Python module:
 
+.. code:: python
 
-.. contents::
-    :backlinks: none
+    VERSION = '1.5.0.dev2'
 
+You can do the following instead of hardcoding it:
 
-Overview
-========
+.. code:: python
 
-At development time, the current version number is automatically generated based on:
+    from version_query import predict_version_str
+
+    VERSION = predict_version_str()
+
+This will set the version to release version when you really release a new version,
+and it will automatically generate a suitable development version at development/pre-release phase.
+
+When your package is imported while running from inside the repository, such as during development,
+the current version number is automatically generated based on:
 
 *   tags
 *   current commit SHA
@@ -134,16 +143,88 @@ or at runtime) then the script relies on metadata generated at packaging time.
 That's why, regardless if package is installed from PyPI (from source or wheel distribution)
 or cloned from GitHub, the version query will work.
 
-Additionally, version numbers in version-query are mutable objects and they can be conveniently
-incremented, compared with each other, as well as converted to/from other popular
-versioning formats.
+Using at build time
+-------------------
+
+This is the way to go if you want to use version-query only as a dependency when building
+the package, in such case it's not necessary to to add it to runtime dependencies.
+
+There are many build systems available for Python, and version-query may not be compatible
+with all of them. Below are some examples.
+
+setuptools with ``setup.py`` script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a legacy way of building Python packages, but it is still widely used.
+
+In such setup, you just need to add the following to your ``setup.py`` file:
+
+.. code:: python
+
+    import setuptools
+    from version_query import predict_version_str
+
+
+    setuptools.setup(
+        ...,
+        version=predict_version_str()
+    )
+
+If you are already using version-query at runtime in your package to set a constant
+(for example ``my_package.VERSION``, please see "Using at runtime" section above for details),
+you may instead reuse the same constant in your ``setup.py`` file:
+
+.. code:: python
+
+    import setuptools
+
+    from my_package import VERSION
+
+
+    setuptools.setup(
+        ...,
+        version=VERSION
+    )
+
+dynamic version attribute in ``pyproject.toml``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A more modern approach in Python is to use ``pyproject.toml`` for building packages.
+
+Some build systems that use ``pyproject.toml`` support setting the version dynamically
+by allowing users to point to an attribute of some module in order to get the version.
+
+One of such packages is setuptools. When using it, one can do the following:
+
+.. code:: toml
+
+    [project]
+    dynamic = ["version"]
+    ...
+
+    [build-system]
+    requires = ["setuptools >= 70.0"]
+    build-backend = "setuptools.build_meta"
+
+    [tool.setuptools.dynamic]
+    version = {attr = "version_query.local_git_version.PREDICTED"}
+
+Depending on how you build your package, the build system may copy files to a temporary folder
+when building. In such case, you need to set ``PROJECT_FOLDER`` environment variable
+to the current working directory before running the build command.
+
+For example, when using ``build`` package:
+
+.. code:: bash
+
+    PROJECT_FOLDER=$(pwd) python3 -m build
 
 Versioning scheme
 =================
 
 Version scheme used by version-query is a relaxed mixture of:
 
-*   `Semantic Versioning 2.0.0 <http://semver.org/>`_ and
+*   `Semantic Versioning 2.0.0 <http://semver.org/>`__ and
 
 *   `PEP 440 -- Version Identification and Dependency Specification <https://www.python.org/dev/peps/pep-0440/>`_.
 
@@ -328,7 +409,7 @@ The base specification of the comparison scheme is:
 
 *   `PEP 508 -- Dependency specification for Python Software Packages <https://www.python.org/dev/peps/pep-0508/>`_ as well as
 
-*   `Semantic Versioning 2.0.0 <http://semver.org/>`_.
+*   `Semantic Versioning 2.0.0 <http://semver.org/>`__.
 
 With the notable difference to both that all version components are taken into account when
 establishing version precedence.
@@ -426,7 +507,7 @@ The Version objects are mutable, hashable and comparable.
     version = version_query.query_caller(stack_level=1)
     version = version_query.predict_caller(2)
 
-Version object can be obtained for any supported path, as well as for any python code
+Version object can be obtained for any supported path, as well as for any Python code
 currently being executed -- as long as it is located in a supported location.
 
 
@@ -491,8 +572,8 @@ Requirements
 
 Python version 3.9 or later.
 
-Python libraries as specified in `requirements.txt <https://github.com/mbdevpl/version-query/blob/v1.6.3.dev0/requirements.txt>`_.
+Python libraries as specified in `requirements.txt <https://github.com/mbdevpl/version-query/blob/v1.7.0/requirements.txt>`_.
 
-Building and running tests additionally requires packages listed in `requirements_test.txt <https://github.com/mbdevpl/version-query/blob/v1.6.3.dev0/requirements_test.txt>`_.
+Building and running tests additionally requires packages listed in `requirements_test.txt <https://github.com/mbdevpl/version-query/blob/v1.7.0/requirements_test.txt>`_.
 
 Tested on Linux, macOS and Windows.

{version_query-1.6.3.dev0 → version_query-1.7.0}/README.rst

@@ -41,34 +41,43 @@ for easier development, testing and pre-release deployment?!
 
 Search no more!
 
-As long as you mark your releases using git tags, instead of hardcoding:
+As long as you use git and you mark your releases using git tags, version-query will do the rest.
 
-.. code:: python
+It's 21st century, stop hardcoding version numbers!
 
-    __version__ = '1.5.0.dev2'
+.. contents::
+    :backlinks: none
 
-You can do:
 
-.. code:: python
+Overview
+========
 
-    from version_query import predict_version_str
+There are two main ways of using version-query - at runtime or at build time.
 
-    __version__ = predict_version_str()
+Using at runtime
+----------------
 
-It's 21st century, stop hardcoding version numbers!
+When using this way, version-query is needed as a runtime dependency of your package.
 
-This will set the version to release version when you really release a new version,
-and it will automatically generate a suitable development version at development/pre-release phase.
+If, for example, you have a constant storing the version of your package in some Python module:
 
+.. code:: python
 
-.. contents::
-    :backlinks: none
+    VERSION = '1.5.0.dev2'
 
+You can do the following instead of hardcoding it:
 
-Overview
-========
+.. code:: python
 
-At development time, the current version number is automatically generated based on:
+    from version_query import predict_version_str
+
+    VERSION = predict_version_str()
+
+This will set the version to release version when you really release a new version,
+and it will automatically generate a suitable development version at development/pre-release phase.
+
+When your package is imported while running from inside the repository, such as during development,
+the current version number is automatically generated based on:
 
 *   tags
 *   current commit SHA
@@ -81,16 +90,88 @@ or at runtime) then the script relies on metadata generated at packaging time.
 That's why, regardless if package is installed from PyPI (from source or wheel distribution)
 or cloned from GitHub, the version query will work.
 
-Additionally, version numbers in version-query are mutable objects and they can be conveniently
-incremented, compared with each other, as well as converted to/from other popular
-versioning formats.
+Using at build time
+-------------------
+
+This is the way to go if you want to use version-query only as a dependency when building
+the package, in such case it's not necessary to to add it to runtime dependencies.
+
+There are many build systems available for Python, and version-query may not be compatible
+with all of them. Below are some examples.
+
+setuptools with ``setup.py`` script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a legacy way of building Python packages, but it is still widely used.
+
+In such setup, you just need to add the following to your ``setup.py`` file:
+
+.. code:: python
+
+    import setuptools
+    from version_query import predict_version_str
+
+
+    setuptools.setup(
+        ...,
+        version=predict_version_str()
+    )
+
+If you are already using version-query at runtime in your package to set a constant
+(for example ``my_package.VERSION``, please see "Using at runtime" section above for details),
+you may instead reuse the same constant in your ``setup.py`` file:
+
+.. code:: python
+
+    import setuptools
+
+    from my_package import VERSION
+
+
+    setuptools.setup(
+        ...,
+        version=VERSION
+    )
+
+dynamic version attribute in ``pyproject.toml``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A more modern approach in Python is to use ``pyproject.toml`` for building packages.
+
+Some build systems that use ``pyproject.toml`` support setting the version dynamically
+by allowing users to point to an attribute of some module in order to get the version.
+
+One of such packages is setuptools. When using it, one can do the following:
+
+.. code:: toml
+
+    [project]
+    dynamic = ["version"]
+    ...
+
+    [build-system]
+    requires = ["setuptools >= 70.0"]
+    build-backend = "setuptools.build_meta"
+
+    [tool.setuptools.dynamic]
+    version = {attr = "version_query.local_git_version.PREDICTED"}
+
+Depending on how you build your package, the build system may copy files to a temporary folder
+when building. In such case, you need to set ``PROJECT_FOLDER`` environment variable
+to the current working directory before running the build command.
+
+For example, when using ``build`` package:
+
+.. code:: bash
+
+    PROJECT_FOLDER=$(pwd) python3 -m build
 
 Versioning scheme
 =================
 
 Version scheme used by version-query is a relaxed mixture of:
 
-*   `Semantic Versioning 2.0.0 <http://semver.org/>`_ and
+*   `Semantic Versioning 2.0.0 <http://semver.org/>`__ and
 
 *   `PEP 440 -- Version Identification and Dependency Specification <https://www.python.org/dev/peps/pep-0440/>`_.
 
@@ -275,7 +356,7 @@ The base specification of the comparison scheme is:
 
 *   `PEP 508 -- Dependency specification for Python Software Packages <https://www.python.org/dev/peps/pep-0508/>`_ as well as
 
-*   `Semantic Versioning 2.0.0 <http://semver.org/>`_.
+*   `Semantic Versioning 2.0.0 <http://semver.org/>`__.
 
 With the notable difference to both that all version components are taken into account when
 establishing version precedence.
@@ -373,7 +454,7 @@ The Version objects are mutable, hashable and comparable.
     version = version_query.query_caller(stack_level=1)
     version = version_query.predict_caller(2)
 
-Version object can be obtained for any supported path, as well as for any python code
+Version object can be obtained for any supported path, as well as for any Python code
 currently being executed -- as long as it is located in a supported location.
 
 

{version_query-1.6.3.dev0 → version_query-1.7.0}/test/examples.py

@@ -9,8 +9,6 @@ import typing as t
 
 from version_query.version import VersionComponent
 
-_HERE = pathlib.Path(__file__).resolve().parent
-
 _GIT_REPOS_ROOT = pathlib.Path(os.environ.get('EXAMPLE_PROJECTS_PATH', '..')).resolve()
 
 GIT_REPO_EXAMPLES = list(_ for _ in _GIT_REPOS_ROOT.glob('**/.git') if _.is_dir())

version_query-1.7.0/test/test_cli.py

@@ -0,0 +1,81 @@
+"""Tests of the CLI."""
+
+import contextlib
+import io
+import logging
+import runpy
+import sys
+import unittest
+
+from version_query.version import VersionComponent
+from version_query.query import \
+    query_caller, query_version_str, predict_caller, predict_version_str
+
+_LOG = logging.getLogger(__name__)
+
+
+@contextlib.contextmanager
+def temporarily_set_logger_level(logger_name: str, level: int):
+    """Change logger level on enter and restore on exit of this context."""
+    logger = logging.getLogger(logger_name)
+    level_ = logger.level
+    logger.setLevel(level)
+    try:
+        yield
+    finally:
+        logger.setLevel(level_)
+
+
+def preserve_logger_level(logger_name: str):
+    return temporarily_set_logger_level(logger_name, logging.getLogger(logger_name).level)
+
+
+def run_module(name: str, *args, run_name: str = '__main__') -> None:
+    backup_sys_argv = sys.argv
+    sys.argv = [name + '.py'] + list(args)
+    runpy.run_module(name, run_name=run_name, alter_sys=True)
+    sys.argv = backup_sys_argv
+
+
+class Tests(unittest.TestCase):
+
+    def test_not_as_main(self):  # pylint: disable = no-self-use
+        run_module('version_query', run_name='__not_main__')
+
+    def test_help(self):
+        sio = io.StringIO()
+        with contextlib.redirect_stderr(sio), preserve_logger_level('version_query'), \
+                self.assertRaises(SystemExit):
+            run_module('version_query')
+        _LOG.info('%s', sio.getvalue())
+
+    def test_bad_usage(self):
+        sio = io.StringIO()
+        with contextlib.redirect_stderr(sio), preserve_logger_level('version_query'), \
+                self.assertRaises(ValueError):
+            run_module('version_query', '-p', '-i', '.')
+        _LOG.info('%s', sio.getvalue())
+
+    def test_here(self):
+        sio = io.StringIO()
+        with temporarily_set_logger_level('version_query', logging.ERROR), \
+                contextlib.redirect_stdout(sio):
+            run_module('version_query', '.')
+        self.assertEqual(sio.getvalue().rstrip(), query_caller().to_str())
+        self.assertEqual(sio.getvalue().rstrip(), query_version_str())
+
+    def test_increment_here(self):
+        sio = io.StringIO()
+        with temporarily_set_logger_level('version_query', logging.ERROR), \
+                contextlib.redirect_stdout(sio):
+            run_module('version_query', '-i', '.')
+        self.assertEqual(sio.getvalue().rstrip(),
+                         query_caller().increment(VersionComponent.Patch).to_str())
+
+    def test_predict_here(self):
+        sio = io.StringIO()
+        with temporarily_set_logger_level('version_query', logging.ERROR), \
+                contextlib.redirect_stdout(sio):
+            run_module('version_query', '-p', '.')
+        self.assertEqual(sio.getvalue().rstrip(), predict_caller().to_str())
+        self.assertEqual(sio.getvalue().rstrip(), predict_version_str())

version_query-1.7.0/test/test_local_git_version.py

@@ -0,0 +1,21 @@
+"""Tests of local_git_version module."""
+
+import logging
+
+import unittest
+
+
+from version_query.local_git_version import QUERIED, PREDICTED
+
+_LOG = logging.getLogger(__name__)
+
+
+class Tests(unittest.TestCase):
+
+    def test_queried(self):
+        _LOG.debug('QUERIED: %s', QUERIED)
+        self.assertIsInstance(QUERIED, str)
+
+    def test_predicted(self):
+        _LOG.debug('PREDICTED: %s', PREDICTED)
+        self.assertIsInstance(PREDICTED, str)

{version_query-1.6.3.dev0 → version_query-1.7.0}/test/test_query.py

@@ -1,49 +1,37 @@
 """Tests of querying tools."""
 
-import contextlib
 import importlib
-import io
 import logging
 import os
 import pathlib
 import sys
 import tempfile
 import unittest
-import unittest.mock
 
 from boilerplates.packaging_tests import run_module
 
-from version_query.version import VersionComponent, Version
+from version_query.version import Version
 from version_query.git_query import query_git_repo, predict_git_repo
 from version_query.py_query import query_metadata_json, query_pkg_info, query_package_folder
-from version_query.query import \
-    query_folder, query_caller, query_version_str, predict_caller, predict_version_str
+from version_query.query import query_folder, query_caller
 from .examples import \
     PY_LIB_DIR, GIT_REPO_EXAMPLES, METADATA_JSON_EXAMPLE_PATHS, PKG_INFO_EXAMPLE_PATHS, \
     PACKAGE_FOLDER_EXAMPLES
+from .test_cli import preserve_logger_level
 
 _LOG = logging.getLogger(__name__)
 
-IGNORED_FOLDER_NAMES = ['opencv']
 
+class Tests(unittest.TestCase):
+    """Test querying tools from several modules.
 
-@contextlib.contextmanager
-def temporarily_set_logger_level(logger_name: str, level: int):
-    """Change logger level on enter and restore on exit of this context."""
-    logger = logging.getLogger(logger_name)
-    level_ = logger.level
-    logger.setLevel(level)
-    try:
-        yield
-    finally:
-        logger.setLevel(level_)
-
-
-def preserve_logger_level(logger_name: str):
-    return temporarily_set_logger_level(logger_name, logging.getLogger(logger_name).level)
-
+    Note:
 
-class Tests(unittest.TestCase):
+    Tests that run setup script directly fail due to conflict between distutils used internally
+    by setuptools and distutils used internally by pip. For more information, see:
+    - https://github.com/pypa/setuptools/issues/3297
+    - https://github.com/pypa/pip/issues/8761
+    """
 
     def _check_examples_count(self, description, examples):
         lvl = logging.WARNING if len(examples) < 10 else logging.INFO
@@ -63,8 +51,6 @@ class Tests(unittest.TestCase):
 
     def _query_test_case(self, paths, query_function):
         for path in paths:
-            if any(_ in path.parts for _ in IGNORED_FOLDER_NAMES) or not path.exists():
-                continue
             with self.subTest(path=path, query_function=query_function):
                 _LOG.debug('testing %s() on %s', query_function.__name__, path)
                 try:
@@ -110,6 +96,7 @@ class Tests(unittest.TestCase):
 
     @unittest.skipUnless(
             os.environ.get('TEST_PACKAGING') or os.environ.get('CI'), 'skipping packaging test')
+    @unittest.skipIf(sys.version_info < (3, 12), 'requires Python 3.12+')
     def test_query_pkg_info_current(self):
         with preserve_logger_level('version_query'):
             run_module('setup', 'build')
@@ -143,6 +130,7 @@ class Tests(unittest.TestCase):
 
     @unittest.skipUnless(
             os.environ.get('TEST_PACKAGING') or os.environ.get('CI'), 'skipping packaging test')
+    @unittest.skipIf(sys.version_info < (3, 12), 'requires Python 3.12+')
     def test_query_package_folder_current(self):
         with preserve_logger_level('version_query'):
             run_module('setup', 'build')
@@ -164,46 +152,3 @@ class Tests(unittest.TestCase):
         version = query_caller()
         _LOG.debug('caller: %s', version)
         self.assertIsInstance(version, Version)
-
-    def test_not_as_main(self):  # pylint: disable = no-self-use
-        run_module('version_query', run_name=None)
-
-    def test_help(self):
-        sio = io.StringIO()
-        with contextlib.redirect_stderr(sio):
-            with preserve_logger_level('version_query'):
-                with self.assertRaises(SystemExit):
-                    run_module('version_query')
-        _LOG.info('%s', sio.getvalue())
-
-    def test_bad_usage(self):
-        sio = io.StringIO()
-        with contextlib.redirect_stderr(sio):
-            with preserve_logger_level('version_query'):
-                with self.assertRaises(ValueError):
-                    run_module('version_query', '-p', '-i', '.')
-        _LOG.info('%s', sio.getvalue())
-
-    def test_here(self):
-        with temporarily_set_logger_level('version_query', logging.INFO):
-            sio = io.StringIO()
-            with contextlib.redirect_stdout(sio):
-                run_module('version_query', '.')
-            self.assertEqual(sio.getvalue().rstrip(), query_caller().to_str())
-            self.assertEqual(sio.getvalue().rstrip(), query_version_str())
-
-    def test_increment_here(self):
-        sio = io.StringIO()
-        with contextlib.redirect_stdout(sio):
-            with preserve_logger_level('version_query'):
-                run_module('version_query', '-i', '.')
-        self.assertEqual(sio.getvalue().rstrip(),
-                         query_caller().increment(VersionComponent.Patch).to_str())
-
-    def test_predict_here(self):
-        with temporarily_set_logger_level('version_query', logging.INFO):
-            sio = io.StringIO()
-            with contextlib.redirect_stdout(sio):
-                run_module('version_query', '-p', '.')
-            self.assertEqual(sio.getvalue().rstrip(), predict_caller().to_str())
-            self.assertEqual(sio.getvalue().rstrip(), predict_version_str())

version_query-1.7.0/version_query/local_git_version.py

@@ -0,0 +1,22 @@
+"""Use this module when reading the version from an attribute is needed without Python code.
+
+For example, when using setuptools in pyproject.toml,
+one can set the version dynamically as follows:
+
+[project]
+dynamic = ["version"]
+...
+
+[tool.setuptools.dynamic]
+version = {attr = "version_query.local_git_version.PREDICTED"}
+"""
+
+import os
+import pathlib
+
+from .git_query import query_git_repo, predict_git_repo
+
+_CURRENT_FOLDER: pathlib.Path = pathlib.Path()
+_PROJECT_FOLDER: pathlib.Path = pathlib.Path(os.environ.get('PROJECT_FOLDER', _CURRENT_FOLDER))
+QUERIED: str = query_git_repo(_PROJECT_FOLDER).to_str()
+PREDICTED: str = predict_git_repo(_PROJECT_FOLDER).to_str()

{version_query-1.6.3.dev0 → version_query-1.7.0/version_query.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: version-query
-Version: 1.6.3.dev0
+Version: 1.7.0
 Summary: Zero-overhead package versioning for Python.
 Home-page: https://github.com/mbdevpl/version-query
 Download-URL: 
@@ -81,7 +81,7 @@ Zero-overhead package versioning for Python.
     :alt: grade from Codacy
 
 .. image:: https://img.shields.io/github/license/mbdevpl/version-query.svg
-    :target: https://github.com/mbdevpl/version-query/blob/v1.6.3.dev0/NOTICE
+    :target: https://github.com/mbdevpl/version-query/blob/v1.7.0/NOTICE
     :alt: license
 
 Package versioning toolkit for Python which relies on git tags, git history traversal
@@ -94,34 +94,43 @@ for easier development, testing and pre-release deployment?!
 
 Search no more!
 
-As long as you mark your releases using git tags, instead of hardcoding:
+As long as you use git and you mark your releases using git tags, version-query will do the rest.
 
-.. code:: python
+It's 21st century, stop hardcoding version numbers!
 
-    __version__ = '1.5.0.dev2'
+.. contents::
+    :backlinks: none
 
-You can do:
 
-.. code:: python
+Overview
+========
 
-    from version_query import predict_version_str
+There are two main ways of using version-query - at runtime or at build time.
 
-    __version__ = predict_version_str()
+Using at runtime
+----------------
 
-It's 21st century, stop hardcoding version numbers!
+When using this way, version-query is needed as a runtime dependency of your package.
 
-This will set the version to release version when you really release a new version,
-and it will automatically generate a suitable development version at development/pre-release phase.
+If, for example, you have a constant storing the version of your package in some Python module:
 
+.. code:: python
 
-.. contents::
-    :backlinks: none
+    VERSION = '1.5.0.dev2'
 
+You can do the following instead of hardcoding it:
 
-Overview
-========
+.. code:: python
 
-At development time, the current version number is automatically generated based on:
+    from version_query import predict_version_str
+
+    VERSION = predict_version_str()
+
+This will set the version to release version when you really release a new version,
+and it will automatically generate a suitable development version at development/pre-release phase.
+
+When your package is imported while running from inside the repository, such as during development,
+the current version number is automatically generated based on:
 
 *   tags
 *   current commit SHA
@@ -134,16 +143,88 @@ or at runtime) then the script relies on metadata generated at packaging time.
 That's why, regardless if package is installed from PyPI (from source or wheel distribution)
 or cloned from GitHub, the version query will work.
 
-Additionally, version numbers in version-query are mutable objects and they can be conveniently
-incremented, compared with each other, as well as converted to/from other popular
-versioning formats.
+Using at build time
+-------------------
+
+This is the way to go if you want to use version-query only as a dependency when building
+the package, in such case it's not necessary to to add it to runtime dependencies.
+
+There are many build systems available for Python, and version-query may not be compatible
+with all of them. Below are some examples.
+
+setuptools with ``setup.py`` script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a legacy way of building Python packages, but it is still widely used.
+
+In such setup, you just need to add the following to your ``setup.py`` file:
+
+.. code:: python
+
+    import setuptools
+    from version_query import predict_version_str
+
+
+    setuptools.setup(
+        ...,
+        version=predict_version_str()
+    )
+
+If you are already using version-query at runtime in your package to set a constant
+(for example ``my_package.VERSION``, please see "Using at runtime" section above for details),
+you may instead reuse the same constant in your ``setup.py`` file:
+
+.. code:: python
+
+    import setuptools
+
+    from my_package import VERSION
+
+
+    setuptools.setup(
+        ...,
+        version=VERSION
+    )
+
+dynamic version attribute in ``pyproject.toml``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A more modern approach in Python is to use ``pyproject.toml`` for building packages.
+
+Some build systems that use ``pyproject.toml`` support setting the version dynamically
+by allowing users to point to an attribute of some module in order to get the version.
+
+One of such packages is setuptools. When using it, one can do the following:
+
+.. code:: toml
+
+    [project]
+    dynamic = ["version"]
+    ...
+
+    [build-system]
+    requires = ["setuptools >= 70.0"]
+    build-backend = "setuptools.build_meta"
+
+    [tool.setuptools.dynamic]
+    version = {attr = "version_query.local_git_version.PREDICTED"}
+
+Depending on how you build your package, the build system may copy files to a temporary folder
+when building. In such case, you need to set ``PROJECT_FOLDER`` environment variable
+to the current working directory before running the build command.
+
+For example, when using ``build`` package:
+
+.. code:: bash
+
+    PROJECT_FOLDER=$(pwd) python3 -m build
 
 Versioning scheme
 =================
 
 Version scheme used by version-query is a relaxed mixture of:
 
-*   `Semantic Versioning 2.0.0 <http://semver.org/>`_ and
+*   `Semantic Versioning 2.0.0 <http://semver.org/>`__ and
 
 *   `PEP 440 -- Version Identification and Dependency Specification <https://www.python.org/dev/peps/pep-0440/>`_.
 
@@ -328,7 +409,7 @@ The base specification of the comparison scheme is:
 
 *   `PEP 508 -- Dependency specification for Python Software Packages <https://www.python.org/dev/peps/pep-0508/>`_ as well as
 
-*   `Semantic Versioning 2.0.0 <http://semver.org/>`_.
+*   `Semantic Versioning 2.0.0 <http://semver.org/>`__.
 
 With the notable difference to both that all version components are taken into account when
 establishing version precedence.
@@ -426,7 +507,7 @@ The Version objects are mutable, hashable and comparable.
     version = version_query.query_caller(stack_level=1)
     version = version_query.predict_caller(2)
 
-Version object can be obtained for any supported path, as well as for any python code
+Version object can be obtained for any supported path, as well as for any Python code
 currently being executed -- as long as it is located in a supported location.
 
 
@@ -491,8 +572,8 @@ Requirements
 
 Python version 3.9 or later.
 
-Python libraries as specified in `requirements.txt <https://github.com/mbdevpl/version-query/blob/v1.6.3.dev0/requirements.txt>`_.
+Python libraries as specified in `requirements.txt <https://github.com/mbdevpl/version-query/blob/v1.7.0/requirements.txt>`_.
 
-Building and running tests additionally requires packages listed in `requirements_test.txt <https://github.com/mbdevpl/version-query/blob/v1.6.3.dev0/requirements_test.txt>`_.
+Building and running tests additionally requires packages listed in `requirements_test.txt <https://github.com/mbdevpl/version-query/blob/v1.7.0/requirements_test.txt>`_.
 
 Tested on Linux, macOS and Windows.

{version_query-1.6.3.dev0 → version_query-1.7.0}/version_query.egg-info/SOURCES.txt

@@ -8,7 +8,9 @@ requirements_test.txt
 setup.py
 ./test/__init__.py
 ./test/examples.py
+./test/test_cli.py
 ./test/test_git.py
+./test/test_local_git_version.py
 ./test/test_packaging.py
 ./test/test_query.py
 ./test/test_version.py
@@ -16,6 +18,7 @@ setup.py
 ./version_query/__main__.py
 ./version_query/_version.py
 ./version_query/git_query.py
+./version_query/local_git_version.py
 ./version_query/main.py
 ./version_query/parser.py
 ./version_query/patterns.py
@@ -25,7 +28,9 @@ setup.py
 ./version_query/version.py
 test/__init__.py
 test/examples.py
+test/test_cli.py
 test/test_git.py
+test/test_local_git_version.py
 test/test_packaging.py
 test/test_query.py
 test/test_version.py
@@ -33,6 +38,7 @@ version_query/__init__.py
 version_query/__main__.py
 version_query/_version.py
 version_query/git_query.py
+version_query/local_git_version.py
 version_query/main.py
 version_query/parser.py
 version_query/patterns.py