Set __version__ in the runtime package (#222)

* Set ``__version__`` in the runtime package
* Return the version key in ``setup()``
* Add static type annotations to ``setup()``
* Fix the Python version for ``tomli``
* read ``__version__`` from ``__init__.py``

Co-authored-by: Hugo van Kemenade <[email protected]>

Author: AA-Turner

CONTRIBUTING.rst

@@ -2,7 +2,7 @@ How to release
 --------------
 
 - Update ``CHANGELOG.rst``
-- Bump version (YYYY.MM) in ``pyproject.toml``
+- Bump version (YYYY.MM) in ``python_docs_theme/__init__.py``
 - Commit
 - Push to check tests pass on
   `GitHub Actions <https://github.com/python/python-docs-theme/actions>`__

babel_runner.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+import ast
 import subprocess
 from pathlib import Path
 
@@ -17,6 +18,8 @@
         ) from ie
 
 PROJECT_DIR = Path(__file__).resolve().parent
+PYPROJECT_TOML = PROJECT_DIR / "pyproject.toml"
+INIT_PY = PROJECT_DIR / "python_docs_theme" / "__init__.py"
 
 # Global variables used by pybabel below (paths relative to PROJECT_DIR)
 DOMAIN = "messages"
@@ -29,9 +32,23 @@
 
 def get_project_info() -> dict:
     """Retrieve project's info to populate the message catalog template"""
-    with open(Path(PROJECT_DIR / "pyproject.toml"), "rb") as f:
-        data = tomllib.load(f)
-    return data["project"]
+    pyproject_text = PYPROJECT_TOML.read_text(encoding="utf-8")
+    project_data = tomllib.loads(pyproject_text)["project"]
+
+    # read __version__ from __init__.py
+    for child in ast.parse(INIT_PY.read_bytes()).body:
+        if not isinstance(child, ast.Assign):
+            continue
+        target = child.targets[0]
+        if not isinstance(target, ast.Name) or target.id != "__version__":
+            continue
+        version_node = child.value
+        if not isinstance(version_node, ast.Constant):
+            continue
+        project_data["version"] = version_node.value
+        break
+
+    return project_data
 
 
 def extract_messages() -> None:

pyproject.toml

@@ -6,7 +6,6 @@ requires = [
 
 [project]
 name = "python-docs-theme"
-version = "2024.12"
 description = "The Sphinx theme for the CPython docs and related projects"
 readme = "README.md"
 license.file = "LICENSE"
@@ -28,6 +27,8 @@ classifiers = [
   "Topic :: Documentation",
   "Topic :: Software Development :: Documentation",
 ]
+dynamic = [ "version" ]
+
 dependencies = [
   "sphinx>=3.4",
 ]

python_docs_theme/__init__.py

@@ -1,15 +1,22 @@
 from __future__ import annotations
 
 import hashlib
-import os
 from functools import cache
 from pathlib import Path
-from typing import Any
 
 import sphinx.application
 from sphinx.builders.html import StandaloneHTMLBuilder
 
-THEME_PATH = Path(__file__).parent.resolve()
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Any
+
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+__version__ = "2024.12"
+
+THEME_PATH = Path(__file__).resolve().parent
 
 
 @cache
@@ -52,15 +59,15 @@ def _html_page_context(
         )
 
 
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.require_sphinx("3.4")
 
-    current_dir = os.path.abspath(os.path.dirname(__file__))
-    app.add_html_theme("python_docs_theme", current_dir)
+    app.add_html_theme("python_docs_theme", str(THEME_PATH))
 
     app.connect("html-page-context", _html_page_context)
 
     return {
+        "version": __version__,
         "parallel_read_safe": True,
         "parallel_write_safe": True,
     }

requirements.txt

@@ -2,4 +2,4 @@
 setuptools
 Babel
 Jinja2
-tomli; python_version < "3.10"
+tomli; python_version < "3.11"