Source code for spack.deprecation

# 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)