Deprecate trio.__version__

.readthedocs.yml

@@ -13,6 +13,7 @@ build:
 python:
   install:
     - requirements: docs-requirements.txt
+    - path: .
 
 sphinx:
   fail_on_warning: true

docs/source/conf.py

@@ -315,9 +315,9 @@ def add_mapping(
 # built documents.
 #
 # The short X.Y version.
-import trio
+import importlib.metadata
 
-version = trio.__version__
+version = importlib.metadata.version("trio")
 # The full version, including alpha/beta/rc tags.
 release = version
 

newsfragments/3190.deprecated.rst

@@ -0,0 +1 @@
+Deprecate ``trio.__version__`` in favor of `importlib.metadata.version`.

src/trio/__init__.py

@@ -115,7 +115,14 @@
 
 _deprecate.enable_attribute_deprecations(__name__)
 
-__deprecated_attributes__: dict[str, _deprecate.DeprecatedAttribute] = {}
+__deprecated_attributes__: dict[str, _deprecate.DeprecatedAttribute] = {
+    "__version__": _deprecate.DeprecatedAttribute(
+        __version__, "0.29.0", issue=None, instead='importlib.metadata.version("trio")'
+    )
+}
+
+if not TYPE_CHECKING:
+    del __version__
 
 # Having the public path in .__module__ attributes is important for:
 # - exception names in printed tracebacks

src/trio/_tests/test_trio.py

@@ -6,3 +6,12 @@ def test_trio_import() -> None:
             del sys.modules[module]
 
     import trio  # noqa: F401
+
+
+def test_trio_version_deprecated() -> None:
+    import pytest
+
+    import trio
+
+    with pytest.warns(DeprecationWarning, match="^trio.__version__ is deprecated"):
+        _ = trio.__version__

src/trio/_tests/type_tests/trio_version.py

@@ -0,0 +1,4 @@
+import trio
+from typing_extensions import assert_type
+
+assert_type(trio.__version__, str)