# Copyright Spack Project Developers. See COPYRIGHT file for details.
#
# SPDX-License-Identifier: (Apache-2.0 OR MIT)
"""Shared deprecation policy used by both the concretizer and the installer.
A version (or, more generally, a spec constraint) is marked deprecated via the ``deprecated()``
directive, with a reason, a severity, and the advisory labels it refers to.
Which deprecations are tolerated is defined by ``packages:<name>:deprecation:allow``, a list of
selectors falling back to ``packages:all`` and finally to the legacy ``config:deprecated`` flag.
A directive without labels is skipped when at least one selector matches it, and a directive
with labels when each of its labels is matched by at least one selector, or fixed by a patch
applied to the spec (``patch(..., fixes=[...])``).
"""
import warnings
from typing import TYPE_CHECKING, Dict, FrozenSet, Iterable, List, NamedTuple, Optional, Set, Tuple
import spack.config
import spack.deptypes as dt
import spack.error
import spack.repo
import spack.traverse
from spack.enums import (
LEGACY_DEPRECATION_LABEL,
ConfigScopePriority,
Deprecation,
DeprecationReason,
DeprecationSeverity,
)
if TYPE_CHECKING:
import spack.spec
[docs]
class Violation(NamedTuple):
"""A single disallowed deprecation on a spec"""
constraint: "spack.spec.Spec"
#: The deprecation, with only the labels the policy does not allow
deprecation: Deprecation
[docs]
class Selector(NamedTuple):
"""One entry of ``packages:<name>:deprecation:allow``.
The attributes are AND-ed, and an attribute left empty matches any deprecation.
"""
#: Reasons this entry selects
reasons: FrozenSet[DeprecationReason] = frozenset()
#: Maximum severity this entry selects
severity: Optional[DeprecationSeverity] = None
#: Labels the user assessed. A label of a deprecation is selected if it is listed here.
labels: FrozenSet[str] = frozenset()
[docs]
@staticmethod
def from_config(data: dict) -> "Selector":
reasons = data.get("reason", [])
if isinstance(reasons, str):
reasons = [reasons]
severity = data.get("severity")
return Selector(
reasons=frozenset(DeprecationReason(x) for x in reasons),
severity=DeprecationSeverity(severity) if severity is not None else None,
labels=frozenset(data.get("labels", ())),
)
[docs]
def matches(self, entry: Deprecation, label: Optional[str] = None) -> bool:
"""Return True if this selector matches a deprecation, considering only one of its
labels, or none of them if ``label`` is None.
"""
if self.reasons and entry.reason not in self.reasons:
return False
if self.severity is not None and entry.severity > self.severity:
return False
if self.labels and label not in self.labels:
return False
return True
def _default_selectors(
packages_yaml: dict, *, legacy_default: bool, warn_on_legacy: bool = False
) -> List[Selector]:
"""Return the selectors from ``packages:all:deprecation:allow``.
Falls back to the legacy ``config:deprecated`` flag (which allows any severity) and finally
to the empty list, meaning every deprecation is disallowed.
Args:
packages_yaml: the ``packages`` configuration.
legacy_default: value of the legacy ``config:deprecated`` flag.
warn_on_legacy: emit a warning when the deprecated ``config:deprecated`` flag is
what relaxes the policy.
"""
value = packages_yaml.get("all", {}).get("deprecation", {}).get("allow")
if value is not None:
return [Selector.from_config(x) for x in value]
if legacy_default:
if warn_on_legacy:
warnings.warn(
"config:deprecated is deprecated. Use an entry with 'severity: critical' under "
"'packages:all:deprecation:allow' instead",
UserWarning,
stacklevel=2,
)
return [Selector(severity=DeprecationSeverity.CRITICAL)]
return []
[docs]
def allow_every_deprecation(configuration: spack.config.Configuration) -> None:
"""Push a configuration scope that allows every deprecation.
The scope appends a selector allowing any severity to ``packages:all:deprecation:allow``, and
to each per-package ``allow`` list in the configuration at the time of the call. Lists added
by scopes pushed later are not affected.
Args:
configuration: the configuration to push the scope onto.
"""
packages_yaml = configuration.get_config("packages")
names = ["all"] + [
name
for name, data in packages_yaml.items()
if name != "all" and data.get("deprecation", {}).get("allow") is not None
]
severity = DeprecationSeverity.CRITICAL.name.lower()
data = {
"packages": {name: {"deprecation": {"allow": [{"severity": severity}]}} for name in names}
}
configuration.push_scope(
spack.config.InternalConfigScope("command_line_deprecated", data),
priority=ConfigScopePriority.COMMAND_LINE,
)
[docs]
class Policy:
"""Deprecation policy resolved from the ``packages`` configuration."""
def __init__(
self,
packages_yaml: dict,
default_selectors: List[Selector],
scope: str = "runtime",
*,
repo: spack.repo.RepoPath,
) -> None:
"""
Args:
packages_yaml: the ``packages`` configuration.
default_selectors: selectors from ``packages:all``, used for the packages that
declare none of their own.
scope: check scope from ``packages:all:deprecation:scope`` ("runtime" or "all").
repo: the repositories the ``deprecated()`` directives of a spec are read from.
"""
self.packages_yaml = packages_yaml
self.repo = repo
self.default_selectors = default_selectors
self.scope = scope
self._selectors: Dict[str, List[Selector]] = {}
[docs]
@staticmethod
def from_config(
configuration: spack.config.Configuration,
*,
repo: spack.repo.RepoPath,
warn_on_legacy: bool = False,
) -> "Policy":
"""Build a policy from the ``packages`` config, read once.
Args:
configuration: the configuration to read the policy from.
repo: the repositories the ``deprecated()`` directives of a spec are read from.
warn_on_legacy: emit a warning when the deprecated ``config:deprecated`` flag is
what relaxes the policy. Set only where the warning should fire once.
"""
packages_yaml = configuration.get_config("packages")
scope = packages_yaml.get("all", {}).get("deprecation", {}).get("scope", "runtime")
default_selectors = _default_selectors(
packages_yaml,
legacy_default=configuration.get("config:deprecated", False),
warn_on_legacy=warn_on_legacy,
)
return Policy(packages_yaml, default_selectors, scope, repo=repo)
@property
def deptypes(self) -> int:
"""Dependency types to traverse for the configured deprecation scope."""
return dt.ALL if self.scope == "all" else dt.LINK | dt.RUN
[docs]
def selectors(self, pkg_name: str) -> List[Selector]:
"""Return the selectors for a package. A package that declares an ``allow`` list
replaces the one under ``all``, like every other ``packages`` setting.
"""
if pkg_name not in self._selectors:
override = self.packages_yaml.get(pkg_name, {}).get("deprecation", {}).get("allow")
self._selectors[pkg_name] = (
[Selector.from_config(x) for x in override]
if override is not None
else self.default_selectors
)
return self._selectors[pkg_name]
[docs]
def refused(self, pkg_name: str, entry: Deprecation) -> Optional[Deprecation]:
"""Return the part of a deprecation on a package that is not allowed, or None if it is
allowed, hence skipped.
A deprecation with labels is allowed when each label is matched by some selector, and
the part returned lists only the labels that are not.
"""
selectors = self.selectors(pkg_name)
if not entry.labels:
return None if any(x.matches(entry) for x in selectors) else entry
labels = tuple(
label for label in entry.labels if not any(x.matches(entry, label) for x in selectors)
)
return entry._replace(labels=labels) if labels else None
[docs]
def disallowed(self, spec: "spack.spec.Spec") -> List[Violation]:
"""Returns the list of deprecation-policy violations for a spec. External specs are
exempted since they are not under Spack's control.
A label fixed by a patch applied to the spec is not a violation.
"""
if spec.external:
return []
try:
pkg_cls = self.repo.get_pkg_class(spec.name)
except spack.repo.UnknownPackageError:
return []
violations = []
fixed: Optional[Set[str]] = None
for constraint, entries in pkg_cls.deprecations.items():
if not spec.satisfies(constraint):
continue
for entry in entries:
refused = self.refused(spec.name, entry)
if refused is not None and can_be_fixed(refused.labels):
if fixed is None:
fixed = fixed_labels(spec, repo=self.repo)
labels = tuple(x for x in refused.labels if x not in fixed)
refused = refused._replace(labels=labels) if labels else None
if refused is not None:
violations.append(Violation(constraint, refused))
return violations
[docs]
def can_be_fixed(labels: Tuple[str, ...]) -> bool:
"""Return True if a patch may fix one of the labels. The label Spack records for
``version(..., deprecated=True)`` is never fixed, since ``patch(fixes=...)`` refuses it.
"""
return any(x != LEGACY_DEPRECATION_LABEL for x in labels)
[docs]
def fixed_labels(spec: "spack.spec.Spec", *, repo: spack.repo.RepoPath) -> Set[str]:
"""Return the deprecation labels fixed by the patches applied to a concrete spec. The set is
empty when the patches cannot be looked up in ``repo``.
"""
try:
patches = spec._patches_from(repo)
except (spack.error.SpecError, spack.repo.RepoError):
return set()
return {label for patch in patches for label in patch.fixes}
[docs]
def deprecated_spec_str(pkg_name: str, constraint: "spack.spec.Spec") -> str:
"""Format the spec a ``deprecated()`` directive refers to."""
constraint_str = str(constraint)
if not constraint_str:
return pkg_name
return constraint_str if constraint.name else f"{pkg_name}{constraint_str}"
[docs]
def deprecation_attributes_str(entry: Deprecation) -> str:
"""Format the attributes of a refused deprecation, as they are written in a selector."""
result = f"reason: {entry.reason.value}, severity: {entry.severity.name.lower()}"
return f"{result}, labels: {', '.join(entry.labels)}" if entry.labels else result
[docs]
def reusable(
specs: Iterable["spack.spec.Spec"], *, policy: Optional[Policy] = None
) -> List["spack.spec.Spec"]:
"""Return the subset of ``specs`` that can be reused under the deprecation policy.
A candidate is rejected when it, or any node in its checked closure, has a disallowed
deprecation. The closure is the link/run one under the ``runtime`` scope, and the whole DAG
under ``all``, so ``all`` additionally rejects artifacts built with a deprecated tool.
Args:
specs: the reuse candidates.
policy: the policy to apply; defaults to the configured one.
"""
resolved = policy or Policy.from_config(spack.config.CONFIG, repo=spack.repo.PATH)
deptypes = resolved.deptypes
candidates = list(specs)
# One post-order pass over the union of the candidate DAGs, keyed by hash so a node shared
# by many candidates is evaluated once.
rejected: Set[str] = set()
for node in spack.traverse.traverse_nodes(
candidates, deptype=deptypes, order="post", key=spack.traverse.by_dag_hash
):
if resolved.disallowed(node) or any(
edge.spec.dag_hash() in rejected
for edge in node.edges_to_dependencies(depflag=deptypes)
):
rejected.add(node.dag_hash())
return [s for s in candidates if s.dag_hash() not in rejected]
[docs]
def check_deprecations(
seeds: Iterable["spack.spec.Spec"], *, policy: Optional[Policy] = None
) -> None:
"""Raise if the DAG reachable from any seed contains a disallowed deprecation.
Args:
seeds: the specs to check, together with the DAG reachable from them.
policy: the policy to apply, together with the closure it checks; defaults to the
configured one.
"""
resolved = policy or Policy.from_config(spack.config.CONFIG, repo=spack.repo.PATH)
violations: List[str] = []
for node in spack.traverse.traverse_nodes(list(seeds), deptype=resolved.deptypes):
found = resolved.disallowed(node)
if found:
violations.append(_format_violations(node, found))
if violations:
raise spack.error.InstallError(
"the following specs are deprecated and cannot be installed:\n\n"
+ "\n".join(violations)
+ "\n\n Add an entry to 'packages:<name>:deprecation:allow' in your "
"configuration to install them anyway."
)
def _format_violations(spec: "spack.spec.Spec", violations: List[Violation]) -> str:
lines = [f" {spec.cshort_spec}"]
for constraint, entry in violations:
spec_str = deprecated_spec_str(spec.name, constraint)
attributes = deprecation_attributes_str(entry)
lines.append(
f" {spec_str} is deprecated ({attributes}); not allowed by "
f"'packages:{spec.name}:deprecation:allow'"
)
if entry.msg:
lines.append(f" {entry.msg}")
return "\n".join(lines)