markers.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388
  1. # This file is dual licensed under the terms of the Apache License, Version
  2. # 2.0, and the BSD License. See the LICENSE file in the root of this repository
  3. # for complete details.
  4. from __future__ import annotations
  5. import operator
  6. import os
  7. import platform
  8. import sys
  9. from typing import AbstractSet, Callable, Literal, Mapping, TypedDict, Union, cast
  10. from ._parser import MarkerAtom, MarkerList, Op, Value, Variable
  11. from ._parser import parse_marker as _parse_marker
  12. from ._tokenizer import ParserSyntaxError
  13. from .specifiers import InvalidSpecifier, Specifier
  14. from .utils import canonicalize_name
  15. __all__ = [
  16. "Environment",
  17. "EvaluateContext",
  18. "InvalidMarker",
  19. "Marker",
  20. "UndefinedComparison",
  21. "UndefinedEnvironmentName",
  22. "default_environment",
  23. ]
  24. Operator = Callable[[str, Union[str, AbstractSet[str]]], bool]
  25. EvaluateContext = Literal["metadata", "lock_file", "requirement"]
  26. MARKERS_ALLOWING_SET = {"extras", "dependency_groups"}
  27. MARKERS_REQUIRING_VERSION = {
  28. "implementation_version",
  29. "platform_release",
  30. "python_full_version",
  31. "python_version",
  32. }
  33. class InvalidMarker(ValueError):
  34. """
  35. An invalid marker was found, users should refer to PEP 508.
  36. """
  37. class UndefinedComparison(ValueError):
  38. """
  39. An invalid operation was attempted on a value that doesn't support it.
  40. """
  41. class UndefinedEnvironmentName(ValueError):
  42. """
  43. A name was attempted to be used that does not exist inside of the
  44. environment.
  45. """
  46. class Environment(TypedDict):
  47. implementation_name: str
  48. """The implementation's identifier, e.g. ``'cpython'``."""
  49. implementation_version: str
  50. """
  51. The implementation's version, e.g. ``'3.13.0a2'`` for CPython 3.13.0a2, or
  52. ``'7.3.13'`` for PyPy3.10 v7.3.13.
  53. """
  54. os_name: str
  55. """
  56. The value of :py:data:`os.name`. The name of the operating system dependent module
  57. imported, e.g. ``'posix'``.
  58. """
  59. platform_machine: str
  60. """
  61. Returns the machine type, e.g. ``'i386'``.
  62. An empty string if the value cannot be determined.
  63. """
  64. platform_release: str
  65. """
  66. The system's release, e.g. ``'2.2.0'`` or ``'NT'``.
  67. An empty string if the value cannot be determined.
  68. """
  69. platform_system: str
  70. """
  71. The system/OS name, e.g. ``'Linux'``, ``'Windows'`` or ``'Java'``.
  72. An empty string if the value cannot be determined.
  73. """
  74. platform_version: str
  75. """
  76. The system's release version, e.g. ``'#3 on degas'``.
  77. An empty string if the value cannot be determined.
  78. """
  79. python_full_version: str
  80. """
  81. The Python version as string ``'major.minor.patchlevel'``.
  82. Note that unlike the Python :py:data:`sys.version`, this value will always include
  83. the patchlevel (it defaults to 0).
  84. """
  85. platform_python_implementation: str
  86. """
  87. A string identifying the Python implementation, e.g. ``'CPython'``.
  88. """
  89. python_version: str
  90. """The Python version as string ``'major.minor'``."""
  91. sys_platform: str
  92. """
  93. This string contains a platform identifier that can be used to append
  94. platform-specific components to :py:data:`sys.path`, for instance.
  95. For Unix systems, except on Linux and AIX, this is the lowercased OS name as
  96. returned by ``uname -s`` with the first part of the version as returned by
  97. ``uname -r`` appended, e.g. ``'sunos5'`` or ``'freebsd8'``, at the time when Python
  98. was built.
  99. """
  100. def _normalize_extras(
  101. result: MarkerList | MarkerAtom | str,
  102. ) -> MarkerList | MarkerAtom | str:
  103. if not isinstance(result, tuple):
  104. return result
  105. lhs, op, rhs = result
  106. if isinstance(lhs, Variable) and lhs.value == "extra":
  107. normalized_extra = canonicalize_name(rhs.value)
  108. rhs = Value(normalized_extra)
  109. elif isinstance(rhs, Variable) and rhs.value == "extra":
  110. normalized_extra = canonicalize_name(lhs.value)
  111. lhs = Value(normalized_extra)
  112. return lhs, op, rhs
  113. def _normalize_extra_values(results: MarkerList) -> MarkerList:
  114. """
  115. Normalize extra values.
  116. """
  117. return [_normalize_extras(r) for r in results]
  118. def _format_marker(
  119. marker: list[str] | MarkerAtom | str, first: bool | None = True
  120. ) -> str:
  121. assert isinstance(marker, (list, tuple, str))
  122. # Sometimes we have a structure like [[...]] which is a single item list
  123. # where the single item is itself it's own list. In that case we want skip
  124. # the rest of this function so that we don't get extraneous () on the
  125. # outside.
  126. if (
  127. isinstance(marker, list)
  128. and len(marker) == 1
  129. and isinstance(marker[0], (list, tuple))
  130. ):
  131. return _format_marker(marker[0])
  132. if isinstance(marker, list):
  133. inner = (_format_marker(m, first=False) for m in marker)
  134. if first:
  135. return " ".join(inner)
  136. else:
  137. return "(" + " ".join(inner) + ")"
  138. elif isinstance(marker, tuple):
  139. return " ".join([m.serialize() for m in marker])
  140. else:
  141. return marker
  142. _operators: dict[str, Operator] = {
  143. "in": lambda lhs, rhs: lhs in rhs,
  144. "not in": lambda lhs, rhs: lhs not in rhs,
  145. "<": lambda _lhs, _rhs: False,
  146. "<=": operator.eq,
  147. "==": operator.eq,
  148. "!=": operator.ne,
  149. ">=": operator.eq,
  150. ">": lambda _lhs, _rhs: False,
  151. }
  152. def _eval_op(lhs: str, op: Op, rhs: str | AbstractSet[str], *, key: str) -> bool:
  153. op_str = op.serialize()
  154. if key in MARKERS_REQUIRING_VERSION:
  155. try:
  156. spec = Specifier(f"{op_str}{rhs}")
  157. except InvalidSpecifier:
  158. pass
  159. else:
  160. return spec.contains(lhs, prereleases=True)
  161. oper: Operator | None = _operators.get(op_str)
  162. if oper is None:
  163. raise UndefinedComparison(f"Undefined {op!r} on {lhs!r} and {rhs!r}.")
  164. return oper(lhs, rhs)
  165. def _normalize(
  166. lhs: str, rhs: str | AbstractSet[str], key: str
  167. ) -> tuple[str, str | AbstractSet[str]]:
  168. # PEP 685 - Comparison of extra names for optional distribution dependencies
  169. # https://peps.python.org/pep-0685/
  170. # > When comparing extra names, tools MUST normalize the names being
  171. # > compared using the semantics outlined in PEP 503 for names
  172. if key == "extra":
  173. assert isinstance(rhs, str), "extra value must be a string"
  174. # Both sides are normalized at this point already
  175. return (lhs, rhs)
  176. if key in MARKERS_ALLOWING_SET:
  177. if isinstance(rhs, str): # pragma: no cover
  178. return (canonicalize_name(lhs), canonicalize_name(rhs))
  179. else:
  180. return (canonicalize_name(lhs), {canonicalize_name(v) for v in rhs})
  181. # other environment markers don't have such standards
  182. return lhs, rhs
  183. def _evaluate_markers(
  184. markers: MarkerList, environment: dict[str, str | AbstractSet[str]]
  185. ) -> bool:
  186. groups: list[list[bool]] = [[]]
  187. for marker in markers:
  188. if isinstance(marker, list):
  189. groups[-1].append(_evaluate_markers(marker, environment))
  190. elif isinstance(marker, tuple):
  191. lhs, op, rhs = marker
  192. if isinstance(lhs, Variable):
  193. environment_key = lhs.value
  194. lhs_value = environment[environment_key]
  195. rhs_value = rhs.value
  196. else:
  197. lhs_value = lhs.value
  198. environment_key = rhs.value
  199. rhs_value = environment[environment_key]
  200. assert isinstance(lhs_value, str), "lhs must be a string"
  201. lhs_value, rhs_value = _normalize(lhs_value, rhs_value, key=environment_key)
  202. groups[-1].append(_eval_op(lhs_value, op, rhs_value, key=environment_key))
  203. elif marker == "or":
  204. groups.append([])
  205. elif marker == "and":
  206. pass
  207. else: # pragma: nocover
  208. raise TypeError(f"Unexpected marker {marker!r}")
  209. return any(all(item) for item in groups)
  210. def format_full_version(info: sys._version_info) -> str:
  211. version = f"{info.major}.{info.minor}.{info.micro}"
  212. kind = info.releaselevel
  213. if kind != "final":
  214. version += kind[0] + str(info.serial)
  215. return version
  216. def default_environment() -> Environment:
  217. iver = format_full_version(sys.implementation.version)
  218. implementation_name = sys.implementation.name
  219. return {
  220. "implementation_name": implementation_name,
  221. "implementation_version": iver,
  222. "os_name": os.name,
  223. "platform_machine": platform.machine(),
  224. "platform_release": platform.release(),
  225. "platform_system": platform.system(),
  226. "platform_version": platform.version(),
  227. "python_full_version": platform.python_version(),
  228. "platform_python_implementation": platform.python_implementation(),
  229. "python_version": ".".join(platform.python_version_tuple()[:2]),
  230. "sys_platform": sys.platform,
  231. }
  232. class Marker:
  233. def __init__(self, marker: str) -> None:
  234. # Note: We create a Marker object without calling this constructor in
  235. # packaging.requirements.Requirement. If any additional logic is
  236. # added here, make sure to mirror/adapt Requirement.
  237. # If this fails and throws an error, the repr still expects _markers to
  238. # be defined.
  239. self._markers: MarkerList = []
  240. try:
  241. self._markers = _normalize_extra_values(_parse_marker(marker))
  242. # The attribute `_markers` can be described in terms of a recursive type:
  243. # MarkerList = List[Union[Tuple[Node, ...], str, MarkerList]]
  244. #
  245. # For example, the following expression:
  246. # python_version > "3.6" or (python_version == "3.6" and os_name == "unix")
  247. #
  248. # is parsed into:
  249. # [
  250. # (<Variable('python_version')>, <Op('>')>, <Value('3.6')>),
  251. # 'and',
  252. # [
  253. # (<Variable('python_version')>, <Op('==')>, <Value('3.6')>),
  254. # 'or',
  255. # (<Variable('os_name')>, <Op('==')>, <Value('unix')>)
  256. # ]
  257. # ]
  258. except ParserSyntaxError as e:
  259. raise InvalidMarker(str(e)) from e
  260. def __str__(self) -> str:
  261. return _format_marker(self._markers)
  262. def __repr__(self) -> str:
  263. return f"<{self.__class__.__name__}('{self}')>"
  264. def __hash__(self) -> int:
  265. return hash(str(self))
  266. def __eq__(self, other: object) -> bool:
  267. if not isinstance(other, Marker):
  268. return NotImplemented
  269. return str(self) == str(other)
  270. def evaluate(
  271. self,
  272. environment: Mapping[str, str | AbstractSet[str]] | None = None,
  273. context: EvaluateContext = "metadata",
  274. ) -> bool:
  275. """Evaluate a marker.
  276. Return the boolean from evaluating the given marker against the
  277. environment. environment is an optional argument to override all or
  278. part of the determined environment. The *context* parameter specifies what
  279. context the markers are being evaluated for, which influences what markers
  280. are considered valid. Acceptable values are "metadata" (for core metadata;
  281. default), "lock_file", and "requirement" (i.e. all other situations).
  282. The environment is determined from the current Python process.
  283. """
  284. current_environment = cast(
  285. "dict[str, str | AbstractSet[str]]", default_environment()
  286. )
  287. if context == "lock_file":
  288. current_environment.update(
  289. extras=frozenset(), dependency_groups=frozenset()
  290. )
  291. elif context == "metadata":
  292. current_environment["extra"] = ""
  293. if environment is not None:
  294. current_environment.update(environment)
  295. if "extra" in current_environment:
  296. # The API used to allow setting extra to None. We need to handle
  297. # this case for backwards compatibility. Also skip running
  298. # normalize name if extra is empty.
  299. extra = cast("str | None", current_environment["extra"])
  300. current_environment["extra"] = canonicalize_name(extra) if extra else ""
  301. return _evaluate_markers(
  302. self._markers, _repair_python_full_version(current_environment)
  303. )
  304. def _repair_python_full_version(
  305. env: dict[str, str | AbstractSet[str]],
  306. ) -> dict[str, str | AbstractSet[str]]:
  307. """
  308. Work around platform.python_version() returning something that is not PEP 440
  309. compliant for non-tagged Python builds.
  310. """
  311. python_full_version = cast("str", env["python_full_version"])
  312. if python_full_version.endswith("+"):
  313. env["python_full_version"] = f"{python_full_version}local"
  314. return env