pantsbuild / pants / 24055979590

# Copyright 2025 Pants project contributors (see CONTRIBUTORS.md).

# Licensed under the Apache License, Version 2.0 (see LICENSE).

# Supported option value types.

#

# Note that this is a subset of the value types supported by og Pants, which allows

# nested and heterogenously-valued dicts. However that doesn't seem to be worth the effort

# so let's see how far we can get without supporting those. Note also that these types are all

# immutable, whereas the og types did not have to be. Again, not a complication we should

# be enthusiastic to support.

        # ScalarType

        # tuple[ScalarType, ...]

        torig == tuple and len(targs) == 2 and targs[0] in _SCALAR_TYPES and targs[1] == Ellipsis

    ) or (

        # FrozenDict[str, str]

        torig == FrozenDict and targs == (str, str)

    )

        # E.g., `str` instead of `<class 'str'>`

    # A GenericAlias renders as you'd expect (e.g., `tuple[str, ...]`).

            (type(k), type(v)) == (str, str) for k, v in val.items()

        )

    # Should never happen, assuming we've already passed _is_valid_type().

    # The legacy getter returns a tuple of (value, rank, optional derivation),

    # we only care about value and rank.

    getter: Callable, option_parser, option_id, default

) -> tuple[tuple[ScalarValue, ...], bool]:

    # The legacy getter returns a tuple of (list value, rank, optional derivation),

    # we only care about value and rank, and we convert the value to tuple. The rust code can

    # consume a tuple where a list is expected, so no need to convert the default.

    # The legacy getter returns a tuple of (value, rank, optional derivation),

    # we only care about value and rank, and we convert the value to FrozenDict.

    # We also convert the default to regular dict, so the Rust code can consume it.

    # The type checker currently doesn't grok the overloaded FrozenDict.__init__, so

    # we ignore the arg-type error.

# A map from type to getter for that type.

# Each getter is called with the arguments (options_reader, option_id, default) and

# returns a pair (value, is_explicit). is_explicit is True if the value was specified

# explicitly (by config, env var or flag), and False if the default was used.

# Note that this differentiates between the case of "no explicit value" vs "explicit value

# was provided, but it happened to be the same as the default value".

    bool: partial(_getter, PyNgOptionsReader.get_bool),

    str: partial(_getter, PyNgOptionsReader.get_string),

    int: partial(_getter, PyNgOptionsReader.get_int),

    float: partial(_getter, PyNgOptionsReader.get_float),

    tuple[bool, ...]: partial(_tuple_getter, PyNgOptionsReader.get_bool_list),

    tuple[str, ...]: partial(_tuple_getter, PyNgOptionsReader.get_string_list),

    tuple[int, ...]: partial(_tuple_getter, PyNgOptionsReader.get_int_list),

    tuple[float, ...]: partial(_tuple_getter, PyNgOptionsReader.get_float_list),

    FrozenDict[str, str]: _dict_getter,

}

    """Information we capture at @option evaluation time."""

    name: str

    type: type | GenericAlias

    default: OptionValue | None

    help: str

# A @decorator for options.

        # Mark the func as an option.

    """A holder of options in a scope.

    Much lighter weight than its og counterpart.

    Use like this:

    class Foo(SubsystemNg):

        options_scope = "foo"

        @option(help="bar help")

        def bar(self) -> str: ...

        @option(default=42, help="baz help")

        def baz(self) -> int: ...

        ...

    The supported option types are: bool, str, int, float, tuple[bool, ...], tuple[str, ...],

    tuple[int, ...], tuple[float, ...] and FrozenDict[str, str].

    The `...` in the method bodies above are literal: the subsystem mechanism will provide the body.

    You may need `# mypy: disable-error-code=empty-body` for your code to pass mypy type checks, or

    you can use the mypy plugin at pants.ng.subsystem_mypy_plugin to suppress those errors.

    `default` and `help` can be values or callables that take the subsystem type as an arg, and

    return the relevant values.

    Subsystem instances are instantiated with a PyNgOptionsReader, and calling .bar or .baz (with

    no parentheses) on an instance of Foo will return the value of that option from the underlying

    parser.

    Option names must not _begin_and_end_ with an underscore. Such names are reserved for the

    underlying initialization mechanics.

    """

    # Subclasses must set.

    # The ctor will set.

        """Indirect constructor method.

        Useful for avoiding spurious mypy errors when instantiating instances in tests.

        """

                options_reader, option_id=option_id, default=descriptor.default

            )

                    "No value provided for required option "

                    f"[{self.options_scope}].{descriptor.name}."

                )

        """Return the option descriptors for this subsystem.

        Must only be called after initialize() has been called.

        """

        # We don't use dir() or inspect.getmembers() because those sort by name,

        # and we want to preserve declaration order.

                        f"The @option decorator expects to be placed on a no-arg instance method, but {basecls.__name__}.{name} does not have this signature."

                    )

                        f"Invalid type `{option_type}` for option {basecls.__name__}.{name}"

                    )

                            "The option {basecls.__name__}.{name} is required, so it must not provide a default value."

                        )

                else:

                            f"The default for option {basecls.__name__}.{name} must be of type {_type_to_readable_str(option_type)} (or None)."

                        )

                    OptionDescriptor(

                        name,

                        type=option_type,

                        required=required,

                        default=default,

                        help=help,

                    )

                )

        """Returns information that allows the engine to construct an instance of the subsystem.

        The return value is a pair (function, params) where the function takes the

        type of the subsystem as its first argument (`cls`) and the given params

        as its subsequent argument(s). The params dict is a map of param name -> param type.

        See below for examples of use (currently the only uses, in fact).

        """

        """Returns a `TaskRule` that will construct the target Subsystem."""

        # NB: We populate several dunder methods on the partial function because partial

        # functions do not have these defined by default, and the engine uses these values to

        # visualize functions in error messages and the rule graph.

            output_type=cls,

            parameters=FrozenDict(construct_func_params),

            awaitables=(),

            masked_types=(),

            func=partial_construct_subsystem,

            canonical_name=name,

        )

    options_reader: PyNgOptionsReader

    # The universal options are the options for the repo root dir.

    """A subsystem whose values are universal for all uses.

    Uses include:

    - Global options, as these affect the running of Pants itself.

    - Command/subcommand options, as these are typically provided on the command line and

      are intended by the user to apply to all sources.

    """

    subsystem_typ: type[_UniversalSubsystemT],

    universal_options_reader: UniversalOptionsReader,

) -> _UniversalSubsystemT:

    """A subsystem whose values may vary depending on the sources it applies to.

    The main use is to allow config files in subdirectories to override option values

    set in parent directories (including the root directory), and for those overrides

    to apply just to the sources in or below those subdirectories.

    The input sources for a command will be partitioned into subsets, each attached to

    its own subsystem instance.

    """

    subsystem_typ: type[_ContextualSubsystemT],

    source_partition: SourcePartition,

) -> _ContextualSubsystemT: