From 06d7ed4b840659c1bcb0cd3483d7fd4ece65f002 Mon Sep 17 00:00:00 2001
From: Jan Benda <jan.benda@uni-tuebingen.de>
Date: Tue, 30 Apr 2024 18:53:40 +0200
Subject: [PATCH] extra version module

---
 README.md               | 28 ++++++++++++++++++++--------
 pyproject.toml          |  2 +-
 src/numerix/__init__.py | 11 +----------
 src/numerix/numbers.py  |  2 +-
 src/numerix/version.py  | 10 ++++++++++
 5 files changed, 33 insertions(+), 20 deletions(-)
 create mode 100644 src/numerix/version.py

diff --git a/README.md b/README.md
index 464af7e..a186c23 100644
--- a/README.md
+++ b/README.md
@@ -215,8 +215,8 @@ as well when you call them with a `--version' argument.
 
 For the latter two cases, you can define a `__version__` variable in
 one of the modules, or even in a dedicated module, that you then
-import whereever you need it. Even better is to define it in the
-`__init__.py` file:
+import whereever you need it. For example, you may create a simple
+module called `version.py` file with the following content:
 
 ```
 __version__ = '1.4.2'
@@ -226,6 +226,12 @@ __year__ = '2024'
 """ Year of the current numerix version as string. """
 ```
 
+In `__init__.py` you import the version:
+
+```
+from .version import __version__
+```
+
 Then a script can easily check the package's version like this:
 
 ```
@@ -234,20 +240,26 @@ from numerix import __version__
 print(__version__)
 ```
 
-Other modules of the package need to import it from the `__init__.py`
-file by a relative import to be able to use it:
+Other modules of the package may also import the version by a relative
+import to be able to use it:
 
 ```
-from .__init__ import __version__
+from .version import __version__
 
 
 def about():
     print(f'{__name__} {__version__}')
 ```
 
+Why not defining `__version__` directly in `__init__.py`? Each module
+using the version string would import it from `__init__.py`. If you
+also want to import some functions from such a module in `__init__.py`
+to make them more easily importable from the package, you end up in
+cyclic imports. Python does not like them for a good reason...
+
 But how do you get the very same version into the `pyproject.toml`
 file? It would be a very bad idea to write it there directly and
-update it whenever you change it in the `__init__.py` file. The
+update it whenever you change it in the `version.py` file. The
 version number should be set only in one place.
 
 This is possible, of course. You need to specify the `version` field
@@ -255,7 +267,7 @@ as `dynamic` in the `[project]` section. This tells the package tool
 that the version will be set dynamically by some code. There are
 several options to do so. The simplest one is to add a
 `[tool.setuptools.dynamic]` section where the version is read as an
-attribute from the `numerix` package, that is its `__init__.py`file:
+attribute from the `version` module of the `numerix` package:
 
 ```txt
 ...
@@ -266,7 +278,7 @@ dynamic = ["version"]
 ...
 
 [tool.setuptools.dynamic]
-version = {attr = "numerix.__version__"}
+version = {attr = "numerix.version.__version__"}
 ```
 
 ## Distribute your package
diff --git a/pyproject.toml b/pyproject.toml
index bb7ef34..6a5e295 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -43,7 +43,7 @@ Documentation = "https://whale.am28.uni-tuebingen.de/git/benda/packagehowto/src/
 #numerix   = "numerix.numerix:main"
 
 [tool.setuptools.dynamic]
-version = {attr = "numerix.__version__"}
+version = {attr = "numerix.version.__version__"}
 
 #[tool.pytest.ini_options]
 #pythonpath = "src"
diff --git a/src/numerix/__init__.py b/src/numerix/__init__.py
index 170f5db..5568371 100644
--- a/src/numerix/__init__.py
+++ b/src/numerix/__init__.py
@@ -5,16 +5,7 @@ Fancy numerics made easy.
 """
 
 
-__version__ = '1.4.2'
-""" Current version of the numerix package as string 'x.y.z'. """
-
-__year__ = '2024'
-""" Year of the current numerix version as string. """
-
-# Add them to documentation:
-__pdoc__ = {}
-__pdoc__['__version__'] = True
-__pdoc__['__year__'] = True
+from .version import __version__
 
 
 # Functions defined directly in __init__.py can be imported directly
diff --git a/src/numerix/numbers.py b/src/numerix/numbers.py
index 243a4e0..fa2360e 100644
--- a/src/numerix/numbers.py
+++ b/src/numerix/numbers.py
@@ -1,4 +1,4 @@
-from .__init__ import __version__
+from .version import __version__
 from .addition import add_two
 
 
diff --git a/src/numerix/version.py b/src/numerix/version.py
new file mode 100644
index 0000000..ce37f67
--- /dev/null
+++ b/src/numerix/version.py
@@ -0,0 +1,10 @@
+__version__ = '1.4.2'
+""" Current version of the numerix package as string 'x.y.z'. """
+
+__year__ = '2024'
+""" Year of the current numerix version as string. """
+
+# Add them to documentation:
+__pdoc__ = {}
+__pdoc__['__version__'] = True
+__pdoc__['__year__'] = True