extra version module

Reviewed-on: benda/packagehowto#1

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
+import whereever you need it. For example, you may create a simple
-`__init__.py` file:
+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`
+Other modules of the package may also import the version by a relative
-file by a relative import to be able to use it:
+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

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"

src/numerix/__init__.py

@@ -5,16 +5,7 @@ Fancy numerics made easy.
 """
 
 
-__version__ = '1.4.2'
+from .version import __version__
-""" 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
 
 
 # Functions defined directly in __init__.py can be imported directly

src/numerix/numbers.py

@@ -1,4 +1,4 @@
-from .__init__ import __version__
+from .version import __version__
 from .addition import add_two
 
 

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