19015773527

Committed 02 Nov 2025 05:33PM UTC coverage: 17.872% (-62.4%) from 80.3%

Build # 19015773527

Build Type

Pull #22816

github

Committed by

web-flow

Commit Message

Merge a12d75757 into 6c024e162

Pull Request Pull Request #22816: Update Pants internal Python to 3.14

Run Details

4 of 5 new or added lines in 3 files covered. (80.0%)

28452 existing lines in 683 files now uncovered.

9831 of 55007 relevant lines covered (17.87%)

0.18 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

65.38

/src/python/pants/engine/engine_aware.py

# Copyright 2020 Pants project contributors (see CONTRIBUTORS.md).
# Licensed under the Apache License, Version 2.0 (see LICENSE).

from __future__ import annotations

from abc import ABC
from typing import TYPE_CHECKING, Any

from pants.engine.internals import native_engine
from pants.util.logging import LogLevel

if TYPE_CHECKING:
    from pants.engine.fs import FileDigest, Snapshot


class EngineAwareParameter(ABC):
    """A marker class for rule parameters that allows sending additional metadata to the engine.

    When Pants executes a rule, the engine will call this marker class's methods on the rule's
    inputs to see if they implement any of the methods. If the method returns `None`, the engine
    will do nothing; otherwise, it will use the additional metadata provided.
    """

    def debug_hint(self) -> str | None:
        """If implemented, this string will be shown in `@rule` debug contexts if that rule takes
        the annotated type as a parameter."""
        return None

    def metadata(self) -> dict[str, Any] | None:
        """If implemented, adds arbitrary key-value pairs to the `metadata` entry of the `@rule`.

        If multiple Params to a `@rule` have metadata, the metadata will be merged in a
        deterministic but unspecified order.
        """

        return None


class EngineAwareReturnType(ABC):
    """A marker class for types that are returned by rules to allow sending additional metadata to
    the engine.

    When Pants finishes executing a rule, the engine will call this marker class's methods to see if
    it implements any of the methods. If the method returns `None`, the engine will do nothing;
    otherwise, it will use the additional metadata provided.
    """

    def level(self) -> LogLevel | None:
        """If implemented, this method will modify the level of the workunit associated with any
        `@rule`s that return the annotated type.

        For instance, this can be used to change a workunit that would normally be at `Debug` level
        to `Warn` if an anomalous condition occurs within the `@rule`.
        """
        return None

    def message(self) -> str | None:
        """If implemented, this adds a result message to the workunit for any `@rule`'s that return
        the annotated type.

        The final message will take the form "Completed: <Rule description> - <this method's return
        value>". This method may use newlines.
        """
        return None

    def cacheable(self) -> bool:
        """Allows a return type to be conditionally marked uncacheable.

        An uncacheable value is recomputed in each Session: this can be useful if the level or
        message should be rendered as side effects in each Session.
        """
        return True

    def artifacts(self) -> dict[str, FileDigest | Snapshot] | None:
        """If implemented, this sets the `artifacts` entry for the workunit of any `@rule`'s that
        return the annotated type.

        `artifacts` is a mapping of arbitrary string keys to `Snapshot`s or `FileDigest`s.
        """
        return None

    def metadata(self) -> dict[str, Any] | None:
        """If implemented, adds arbitrary key-value pairs to the `metadata` entry of the `@rule`.

        If a @rule has `metadata` supplied by `EngineAwareParameter`s, the data will be merged, with
        only colliding keys overwritten.
        """

        return None


class SideEffecting(ABC):
    """Marks a class as providing side-effecting APIs, which are handled specially in @rules.

    Implementers of SideEffecting classes should ensure that `def side_effected` is called before
    the class causes side effects.

    Note that logging is _not_ considered to be a side effect, but other types of output to stdio
    are.
    """

    # Used to disable enforcement of effects in tests.
    _enforce_effects: bool

    def side_effected(self) -> None:
        # NB: This method is implemented by manipulating a thread/task-local property which will
        # only be in scope if the SideEffecting property has correctly been identified on a @rule
        # Parameter.
        #
        # TODO: As part of #10542, it's possible that all side-effecting methods will need to
        # become async instead, which would avoid the need for a thread/task-local.
        if self._enforce_effects:
            native_engine.task_side_effected()

1	# Copyright 2020 Pants project contributors (see CONTRIBUTORS.md).
2	# Licensed under the Apache License, Version 2.0 (see LICENSE).
3
4	from __future__ import annotations	1✔
5
6	from abc import ABC	1✔
7	from typing import TYPE_CHECKING, Any	1✔
8
9	from pants.engine.internals import native_engine	1✔
10	from pants.util.logging import LogLevel	1✔
11
12	if TYPE_CHECKING:
13	from pants.engine.fs import FileDigest, Snapshot
14
15
16	class EngineAwareParameter(ABC):	1✔
17	"""A marker class for rule parameters that allows sending additional metadata to the engine.
18
19	When Pants executes a rule, the engine will call this marker class's methods on the rule's
20	inputs to see if they implement any of the methods. If the method returns `None`, the engine
21	will do nothing; otherwise, it will use the additional metadata provided.
22	"""
23
24	def debug_hint(self) -> str \| None:	1✔
25	"""If implemented, this string will be shown in `@rule` debug contexts if that rule takes
26	the annotated type as a parameter."""
27	return None	×
28
29	def metadata(self) -> dict[str, Any] \| None:	1✔
30	"""If implemented, adds arbitrary key-value pairs to the `metadata` entry of the `@rule`.
31
32	If multiple Params to a `@rule` have metadata, the metadata will be merged in a
33	deterministic but unspecified order.
34	"""
35
36	return None	×
37
38
39	class EngineAwareReturnType(ABC):	1✔
40	"""A marker class for types that are returned by rules to allow sending additional metadata to
41	the engine.
42
43	When Pants finishes executing a rule, the engine will call this marker class's methods to see if
44	it implements any of the methods. If the method returns `None`, the engine will do nothing;
45	otherwise, it will use the additional metadata provided.
46	"""
47
48	def level(self) -> LogLevel \| None:	1✔
49	"""If implemented, this method will modify the level of the workunit associated with any
50	`@rule`s that return the annotated type.
51
52	For instance, this can be used to change a workunit that would normally be at `Debug` level
53	to `Warn` if an anomalous condition occurs within the `@rule`.
54	"""
55	return None	×
56
57	def message(self) -> str \| None:	1✔
58	"""If implemented, this adds a result message to the workunit for any `@rule`'s that return
59	the annotated type.
60
61	The final message will take the form "Completed: <Rule description> - <this method's return
62	value>". This method may use newlines.
63	"""
64	return None	×
65
66	def cacheable(self) -> bool:	1✔
67	"""Allows a return type to be conditionally marked uncacheable.
68
69	An uncacheable value is recomputed in each Session: this can be useful if the level or
70	message should be rendered as side effects in each Session.
71	"""
72	return True	×
73
74	def artifacts(self) -> dict[str, FileDigest \| Snapshot] \| None:	1✔
75	"""If implemented, this sets the `artifacts` entry for the workunit of any `@rule`'s that
76	return the annotated type.
77
78	`artifacts` is a mapping of arbitrary string keys to `Snapshot`s or `FileDigest`s.
79	"""
80	return None	×
81
82	def metadata(self) -> dict[str, Any] \| None:	1✔
83	"""If implemented, adds arbitrary key-value pairs to the `metadata` entry of the `@rule`.
84
85	If a @rule has `metadata` supplied by `EngineAwareParameter`s, the data will be merged, with
86	only colliding keys overwritten.
87	"""
88
89	return None	×
90
91
92	class SideEffecting(ABC):	1✔
93	"""Marks a class as providing side-effecting APIs, which are handled specially in @rules.
94
95	Implementers of SideEffecting classes should ensure that `def side_effected` is called before
96	the class causes side effects.
97
98	Note that logging is _not_ considered to be a side effect, but other types of output to stdio
99	are.
100	"""
101
102	# Used to disable enforcement of effects in tests.
103	_enforce_effects: bool	1✔
104
105	def side_effected(self) -> None:	1✔
106	# NB: This method is implemented by manipulating a thread/task-local property which will
107	# only be in scope if the SideEffecting property has correctly been identified on a @rule
108	# Parameter.
109	#
110	# TODO: As part of #10542, it's possible that all side-effecting methods will need to
111	# become async instead, which would avoid the need for a thread/task-local.
UNCOV 112	if self._enforce_effects:	×
113	native_engine.task_side_effected()	×

pantsbuild / pants / 19015773527

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous