fix: restore ._version as a compat shim (#1062)

henryiii · web-flow · commit d5398b8bc19f · 2026-01-15T17:34:36.000-05:00
* fix: hatching uses and modifies _version

Signed-off-by: Henry Schreiner &lt;henryfs@princeton.edu&gt;

* fix: issue warnings if _version is used

Signed-off-by: Henry Schreiner &lt;henryfs@princeton.edu&gt;

* fix: don't add deprecation warning to _Version to avoid double warnings

Signed-off-by: Henry Schreiner &lt;henryfs@princeton.edu&gt;

* fix: add an underscore to deprecated

Signed-off-by: Henry Schreiner &lt;henryfs@princeton.edu&gt;

---------

Signed-off-by: Henry Schreiner &lt;henryfs@princeton.edu&gt;
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -4,7 +4,9 @@ Changelog
 *unreleased*
 ~~~~~~~~~~~~
 
-No unreleased changes.
+Fixes:
+
+* Restore ``Version._version`` as a compatibility shim with a ``DeprecationWarning`` (:pull:`1062`)
 
 26.0rc3 - 2026-01-15
 ~~~~~~~~~~~~~~~~~~~~
diff --git a/src/packaging/version.py b/src/packaging/version.py
@@ -12,13 +12,46 @@
 import re
 import sys
 import typing
-from typing import Any, Callable, Literal, SupportsInt, Tuple, TypedDict, Union
+from typing import (
+    Any,
+    Callable,
+    Literal,
+    NamedTuple,
+    SupportsInt,
+    Tuple,
+    TypedDict,
+    Union,
+)
 
 from ._structures import Infinity, InfinityType, NegativeInfinity, NegativeInfinityType
 
 if typing.TYPE_CHECKING:
     from typing_extensions import Self, Unpack
 
+if sys.version_info >= (3, 13):  # pragma: no cover
+    from warnings import deprecated as _deprecated
+elif typing.TYPE_CHECKING:
+    from typing_extensions import deprecated as _deprecated
+else:  # pragma: no cover
+    import functools
+    import warnings
+
+    def _deprecated(message: str) -> object:
+        def decorator(func: object) -> object:
+            @functools.wraps(func)
+            def wrapper(*args: object, **kwargs: object) -> object:
+                warnings.warn(
+                    message,
+                    category=DeprecationWarning,
+                    stacklevel=2,
+                )
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+
 _LETTER_NORMALIZATION = {
     "alpha": "a",
     "beta": "b",
@@ -264,6 +297,16 @@ def _validate_local(value: object, /) -> LocalType | None:
     raise InvalidVersion(msg)
 
 
+# Backward compatibility for internals before 26.0. Do not use.
+class _Version(NamedTuple):
+    epoch: int
+    release: tuple[int, ...]
+    dev: tuple[str, int] | None
+    pre: tuple[str, int] | None
+    post: tuple[str, int] | None
+    local: LocalType | None
+
+
 class Version(_BaseVersion):
     """This class abstracts handling of a project's versions.
 
@@ -374,6 +417,24 @@ def _key(self) -> CmpKey:
             )
         return self._key_cache
 
+    @property
+    @_deprecated("Version._version is private and will be removed soon")
+    def _version(self) -> _Version:
+        return _Version(
+            self._epoch, self._release, self._dev, self._pre, self._post, self._local
+        )
+
+    @_version.setter
+    @_deprecated("Version._version is private and will be removed soon")
+    def _version(self, value: _Version) -> None:
+        self._epoch = value.epoch
+        self._release = value.release
+        self._dev = value.dev
+        self._pre = value.pre
+        self._post = value.post
+        self._local = value.local
+        self._key_cache = None
+
     def __repr__(self) -> str:
         """A representation of the Version that shows all internal state.
 
diff --git a/tests/test_version.py b/tests/test_version.py
@@ -997,3 +997,37 @@ def test_replace_invalid_local_string(self) -> None:
             InvalidVersion, match="local must be a valid version string"
         ):
             replace(v, local="+abc")
+
+
+# Taken from hatchling 1.28
+def reset_version_parts(version: Version, **kwargs: typing.Any) -> None:  # noqa: ANN401
+    # https://github.com/pypa/packaging/blob/20.9/packaging/version.py#L301-L310
+    internal_version = version._version
+    parts: dict[str, typing.Any] = {}
+    ordered_part_names = ("epoch", "release", "pre", "post", "dev", "local")
+
+    reset = False
+    for part_name in ordered_part_names:
+        if reset:
+            parts[part_name] = kwargs.get(part_name)
+        elif part_name in kwargs:
+            parts[part_name] = kwargs[part_name]
+            reset = True
+        else:
+            parts[part_name] = getattr(internal_version, part_name)
+
+    version._version = type(internal_version)(**parts)
+
+
+# These will be deprecated in 26.1, and removed in the future
+def test_deprecated__version() -> None:
+    v = Version("1.2.3")
+    with pytest.warns(DeprecationWarning, match="is private"):
+        assert v._version.release == (1, 2, 3)
+
+
+def test_hatchling_usage__version() -> None:
+    v = Version("2.3.4")
+    with pytest.warns(DeprecationWarning, match="is private"):
+        reset_version_parts(v, post=("post", 1))
+    assert v == Version("2.3.4.post1")
