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

59.62

/src/python/pants/option/ranked_value.py

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

from __future__ import annotations

from collections.abc import Iterator
from dataclasses import dataclass
from enum import Enum
from functools import total_ordering
from typing import Any, Optional, Union


# NB: Must mirror the Rank enum in src/rust/options/src/lib.rs.
@total_ordering
class Rank(Enum):
    # The ranked value sources. Higher ranks override lower ones.
    NONE = (0, "NONE")  # The value None.
    HARDCODED = (1, "HARDCODED")  # The default provided at option registration.
    CONFIG_DEFAULT = (2, "CONFIG_DEFAULT")  # The value from the DEFAULT section of the config file.
    CONFIG = (3, "CONFIG")  # The value from the relevant section of the config file.
    ENVIRONMENT = (4, "ENVIRONMENT")  # The value from the appropriately-named environment variable.
    FLAG = (5, "FLAG")  # The value from the appropriately-named command-line flag.

    _rank: int

    def __new__(cls, rank: int, display: str) -> Rank:
        member: Rank = object.__new__(cls)
        member._value_ = display
        member._rank = rank
        return member

    def __lt__(self, other: Any) -> bool:
        if type(other) != Rank:  # noqa: E721
            return NotImplemented
        return self._rank < other._rank

    def description(self) -> str | None:
        """The source descriptions used to display option value derivation to users."""
        # These specific strings are for compatibility with the legacy parser's tests.
        # We may revisit them once that is gone.
        if self == Rank.CONFIG:
            return "from config"
        if self == Rank.ENVIRONMENT:
            return "from an env var"
        if self == Rank.FLAG:
            return "from command-line flag"
        return None


Value = Union[str, int, float, None, dict, Enum, list]
ValueAndDetails = tuple[Optional[Value], Optional[str]]


@dataclass(frozen=True)
class RankedValue:
    """An option value, together with a rank inferred from its source.

     Allows us to control which source wins: e.g., a command-line flag overrides an environment
     variable which overrides a config, etc. For example:

     Consider this config:

     [compile.java]
     foo: 11

     And this environment variable:

     PANTS_COMPILE_FOO: 22

    If the command-line is

     ./pants compile target

     we expect the value of foo in the compile.java scope to be 22, because it was explicitly
     set by the user in the enclosing compile scope. I.e., the outer scope's environment value
     overrides the inner scope's config value.

     However if the command-line is

     ./pants compile.java --foo=33 target

     we now expect the value of foo in the compile.java to be 33. I.e., the inner scope's flag
     overrides the outer scope's environment value.

     To tell these cases apart we need to know the "ranking" of the value.
    """

    @classmethod
    def prioritized_iter(
        cls,
        flag_val: ValueAndDetails,
        env_val: ValueAndDetails,
        config_val: ValueAndDetails,
        config_default_val: ValueAndDetails,
        hardcoded_val: ValueAndDetails,
        default: ValueAndDetails,
    ) -> Iterator[RankedValue]:
        """Yield the non-None values from highest-ranked to lowest, as RankedValue instances."""
        if flag_val[0] is not None:
            yield RankedValue(Rank.FLAG, *flag_val)
        if env_val[0] is not None:
            yield RankedValue(Rank.ENVIRONMENT, *env_val)
        if config_val[0] is not None:
            yield RankedValue(Rank.CONFIG, *config_val)
        if config_default_val[0] is not None:
            yield RankedValue(Rank.CONFIG_DEFAULT, *config_default_val)
        if hardcoded_val[0] is not None:
            yield RankedValue(Rank.HARDCODED, *hardcoded_val)
        yield RankedValue(Rank.NONE, *default)

    rank: Rank
    value: Value
    details: str | None = None  # Optional details about the derivation of the value.

1	# Copyright 2014 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 collections.abc import Iterator	1✔
7	from dataclasses import dataclass	1✔
8	from enum import Enum	1✔
9	from functools import total_ordering	1✔
10	from typing import Any, Optional, Union	1✔
11
12
13	# NB: Must mirror the Rank enum in src/rust/options/src/lib.rs.
14	@total_ordering	1✔
15	class Rank(Enum):	1✔
16	# The ranked value sources. Higher ranks override lower ones.
17	NONE = (0, "NONE") # The value None.	1✔
18	HARDCODED = (1, "HARDCODED") # The default provided at option registration.	1✔
19	CONFIG_DEFAULT = (2, "CONFIG_DEFAULT") # The value from the DEFAULT section of the config file.	1✔
20	CONFIG = (3, "CONFIG") # The value from the relevant section of the config file.	1✔
21	ENVIRONMENT = (4, "ENVIRONMENT") # The value from the appropriately-named environment variable.	1✔
22	FLAG = (5, "FLAG") # The value from the appropriately-named command-line flag.	1✔
23
24	_rank: int	1✔
25
26	def __new__(cls, rank: int, display: str) -> Rank:	1✔
27	member: Rank = object.__new__(cls)	1✔
28	member._value_ = display	1✔
29	member._rank = rank	1✔
30	return member	1✔
31
32	def __lt__(self, other: Any) -> bool:	1✔
UNCOV 33	if type(other) != Rank: # noqa: E721	×
34	return NotImplemented	×
UNCOV 35	return self._rank < other._rank	×
36
37	def description(self) -> str \| None:	1✔
38	"""The source descriptions used to display option value derivation to users."""
39	# These specific strings are for compatibility with the legacy parser's tests.
40	# We may revisit them once that is gone.
41	if self == Rank.CONFIG:	×
42	return "from config"	×
43	if self == Rank.ENVIRONMENT:	×
44	return "from an env var"	×
45	if self == Rank.FLAG:	×
46	return "from command-line flag"	×
47	return None	×
48
49
50	Value = Union[str, int, float, None, dict, Enum, list]	1✔
51	ValueAndDetails = tuple[Optional[Value], Optional[str]]	1✔
52
53
54	@dataclass(frozen=True)	1✔
55	class RankedValue:	1✔
56	"""An option value, together with a rank inferred from its source.
57
58	Allows us to control which source wins: e.g., a command-line flag overrides an environment
59	variable which overrides a config, etc. For example:
60
61	Consider this config:
62
63	[compile.java]
64	foo: 11
65
66	And this environment variable:
67
68	PANTS_COMPILE_FOO: 22
69
70	If the command-line is
71
72	./pants compile target
73
74	we expect the value of foo in the compile.java scope to be 22, because it was explicitly
75	set by the user in the enclosing compile scope. I.e., the outer scope's environment value
76	overrides the inner scope's config value.
77
78	However if the command-line is
79
80	./pants compile.java --foo=33 target
81
82	we now expect the value of foo in the compile.java to be 33. I.e., the inner scope's flag
83	overrides the outer scope's environment value.
84
85	To tell these cases apart we need to know the "ranking" of the value.
86	"""
87
88	@classmethod	1✔
89	def prioritized_iter(	1✔
90	cls,
91	flag_val: ValueAndDetails,
92	env_val: ValueAndDetails,
93	config_val: ValueAndDetails,
94	config_default_val: ValueAndDetails,
95	hardcoded_val: ValueAndDetails,
96	default: ValueAndDetails,
97	) -> Iterator[RankedValue]:
98	"""Yield the non-None values from highest-ranked to lowest, as RankedValue instances."""
99	if flag_val[0] is not None:	×
100	yield RankedValue(Rank.FLAG, *flag_val)	×
101	if env_val[0] is not None:	×
102	yield RankedValue(Rank.ENVIRONMENT, *env_val)	×
103	if config_val[0] is not None:	×
104	yield RankedValue(Rank.CONFIG, *config_val)	×
105	if config_default_val[0] is not None:	×
106	yield RankedValue(Rank.CONFIG_DEFAULT, *config_default_val)	×
107	if hardcoded_val[0] is not None:	×
108	yield RankedValue(Rank.HARDCODED, *hardcoded_val)	×
109	yield RankedValue(Rank.NONE, *default)	×
110
111	rank: Rank	1✔
112	value: Value	1✔
113	details: str \| None = None # Optional details about the derivation of the value.	1✔

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