hexdoc.core.compat

  1from __future__ import annotations
  2
  3from dataclasses import dataclass, field
  4from typing import Annotated, Any, ClassVar, Generic, Protocol, TypeVar
  5
  6from packaging.specifiers import SpecifierSet
  7from pydantic import GetCoreSchemaHandler, ValidationInfo
  8from pydantic_core import core_schema
  9from typing_extensions import override
 10
 11from hexdoc.model.base import HexdocModel
 12
 13_T = TypeVar("_T")
 14
 15_T_ModelType = TypeVar("_T_ModelType", bound=type[HexdocModel])
 16
 17_If = TypeVar("_If")
 18_Else = TypeVar("_Else")
 19
 20
 21class VersionSource(Protocol):
 22    @classmethod
 23    def get(cls) -> str | None:
 24        """Returns the current version."""
 25        ...
 26
 27    @classmethod
 28    def matches(cls, specifier: str | SpecifierSet) -> bool:
 29        """Returns True if the current version matches the version_spec."""
 30        ...
 31
 32
 33class MinecraftVersion(VersionSource):
 34    MINECRAFT_VERSION: ClassVar[str | None] = None
 35
 36    @override
 37    @classmethod
 38    def get(cls) -> str | None:
 39        return cls.MINECRAFT_VERSION
 40
 41    @override
 42    @classmethod
 43    def matches(cls, specifier: str | SpecifierSet) -> bool:
 44        if isinstance(specifier, str):
 45            specifier = SpecifierSet(specifier)
 46        if (version := cls.get()) is None:
 47            return True
 48        return version in specifier
 49
 50
 51@dataclass(frozen=True)
 52class Versioned:
 53    """Base class for types which can behave differently based on a version source,
 54    which defaults to MinecraftVersion."""
 55
 56    version_spec: str
 57    version_source: VersionSource = field(default=MinecraftVersion, kw_only=True)
 58
 59    @property
 60    def is_current(self):
 61        return self.version_source.matches(self.version_spec)
 62
 63
 64@dataclass(frozen=True)
 65class IsVersion(Versioned):
 66    """Instances of this class are truthy if version_spec matches version_source, which
 67    defaults to MinecraftVersion.
 68
 69    Can be used as a Pydantic validator annotation, which raises ValueError if
 70    version_spec doesn't match the current version. Use it like this:
 71
 72    `Annotated[str, IsVersion(">=1.20")] | Annotated[None, IsVersion("<1.20")]`
 73
 74    Can also be used as a class decorator for Pydantic models, which raises ValueError
 75    when validating the model if version_spec doesn't match the current version.
 76    Decorated classes must subclass HexdocModel (or HexdocBaseModel).
 77    """
 78
 79    def __bool__(self):
 80        return self.is_current
 81
 82    def __call__(self, cls: _T_ModelType) -> _T_ModelType:
 83        cls.__hexdoc_before_validator__ = self._model_validator
 84        return cls
 85
 86    def __get_pydantic_core_schema__(
 87        self,
 88        source_type: type[Any],
 89        handler: GetCoreSchemaHandler,
 90    ) -> core_schema.CoreSchema:
 91        return core_schema.no_info_before_validator_function(
 92            self._schema_validator,
 93            schema=handler(source_type),
 94        )
 95
 96    def _schema_validator(self, value: Any):
 97        if self.is_current:
 98            return value
 99        raise ValueError(
100            f"Expected version {self.version_spec}, got {self.version_source.get()}"
101        )
102
103    def _model_validator(self, cls: Any, value: Any, info: ValidationInfo):
104        return self._schema_validator(value)
105
106
107Before_1_19 = Annotated[_T, IsVersion("<1.19")]
108"""Alias for `Annotated[_T, IsVersion("<1.19")]`."""
109AtLeast_1_19 = Annotated[_T, IsVersion(">=1.19")]
110"""Alias for `Annotated[_T, IsVersion(">=1.19")]`."""
111After_1_19 = Annotated[_T, IsVersion(">1.19")]
112"""Alias for `Annotated[_T, IsVersion("<1.19")]`."""
113
114Before_1_20 = Annotated[_T, IsVersion("<1.20")]
115"""Alias for `Annotated[_T, IsVersion("<1.20")]`."""
116AtLeast_1_20 = Annotated[_T, IsVersion(">=1.20")]
117"""Alias for `Annotated[_T, IsVersion(">=1.20")]`."""
118After_1_20 = Annotated[_T, IsVersion(">1.20")]
119"""Alias for `Annotated[_T, IsVersion("<1.20")]`."""
120
121
122@dataclass(frozen=True)
123class ValueIfVersion(Versioned, Generic[_If, _Else]):
124    value_if: _If
125    value_else: _Else
126
127    def __call__(self) -> _If | _Else:
128        if self.is_current:
129            return self.value_if
130        return self.value_else