Populating commands from config object?

[pawamoy]

How would you go about populating a command's attributes from a config object 🤔?

Here's what I'm playing with currently:

# --------------------------------------------
# Declare the config stuff
# --------------------------------------------
class Unset:
    """A sentinel value for unset configuration options."""

    def __repr__(self) -> str:
        return "<unset>"


@dataclass(kw_only=True)
class Config:
    """Configuration for the insiders project."""

    unset: ClassVar[Unset] = Unset()

    sponsors_minimum_amount: int | Unset = unset

    # ...more config fields


@cappa.command(name="insiders")
@dataclass(kw_only=True)
class CommandMain:
    """Command to manage your Insiders projects."""

    subcommand: An[
        CommandBacklog,
        cappa.Subcommand(group=_GROUP_SUBCOMMANDS),
        Doc("The selected subcommand."),
    ]

    # --------------------------------------------
    # Main command propagates a config arg
    # --------------------------------------------
    config: An[
        Config | None,
        cappa.Arg(
            short="-c",
            long=True,
            parse=Config.from_file,
            default=Config.from_default_location(),
            group=_GROUP_GLOBAL,
            propagate=True,
        ),
        Doc("Path to the configuration file."),
    ] = None


@cappa.command(name="backlog")
@dataclass(kw_only=True)
class CommandBacklog:
    """Command to list the backlog of issues."""

    github_namespaces: An[
        list[str],
        cappa.Arg(num_args=-1),
        Doc("Namespaces to fetch issues from."),
    ]

    github_org_users: An[
        dict[str, list[str]],
        cappa.Arg(short=False, long=True),
        Doc("""A mapping of users belonging to sponsoring organizations."""),
    ]

    github_token: An[
        str,
        cappa.Arg(short=False, long=True, default=cappa.Env("GITHUB_TOKEN")),
        Doc("""A GitHub token. Recommended scopes: `repo`."""),
    ]

    polar_token: An[
        str,
        cappa.Arg(short=False, long=True, default=cappa.Env("POLAR_TOKEN")),
        Doc("""A Polar token. Recommended scopes: `read:backlog`."""),
    ]

    # ------------------------------------------------------------
    # Subcommands depend on main to fetch config values
    # ------------------------------------------------------------
    def __call__(self, main: CommandMain) -> int:
        if main.config:
            if not self.github_namespaces and main.config.backlog_namespaces is not Config.unset:
                self.github_namespaces = main.config.backlog_namespaces
            if not self.github_org_users and main.config.github_organization_members is not Config.unset:
                self.github_org_users = main.config.github_organization_members
            if not self.sort and main.config.backlog_sort is not Config.unset:
                self.sort = main.config.backlog_sort
            if not self.github_token and main.config.github_token_command is not Config.unset:
                self.github_token = main.config.github_token_command
            if not self.polar_token and main.config.polar_token_command is not Config.unset:
                self.polar_token = main.config.polar_token_command

        # ...actual code

I don't think this approach is the best, because required attributes like github_token will emit an error before they can be populated from the config, if they aren't provided from the CLI or through an env var.

Is there a more Cappa-idiomatic way to declare such an interface? The command dataclasses should keep representing the final state of the data, while each attribute is annotated to tell how it is populated.

I'm thinking about Pydantic settings, wondering if there's a way to integrate it with Cappa somehow?

[pawamoy]

I'm imagining something like cappa.Env.

Here we pass a tuple to cappa.From (dumb name for the example), which is the type of the command to be injected, and an attribute path, to get and return:

    github_token: An[
        str,
        cappa.Arg(
            short=False,
            long=True,
            default=[
                cappa.Env("GITHUB_TOKEN"),
                cappa.From(Command, "config.github_token"),
            ],
        ),
        Doc("A GitHub token. Recommended scopes: `repo`."),
    ]

Here we pass it a callable directly, which expects a Command instance again:

from functools import partial

unset = ...  # sentinel

def from_config(main: Command, attribute_name: str):
    if main.config and (attr := getattr(main.config, attribute_name, unset)) is not unset:
        return attr
    raise ValueError("whatever, just to instruct Cappa that there was no value?")


# ...in our dataclass:

    github_token: An[
        str,
        cappa.Arg(
            short=False,
            long=True,
            default=[
                cappa.Env("GITHUB_TOKEN"),
                cappa.From(partial(from_config, attribute_name="github_token")),
            ],
        ),
        Doc("A GitHub token. Recommended scopes: `repo`."),
    ]

🤔 🤔 🤔

[pawamoy]

Or the callable could raise a Cappa exception instead of returning a sentinel:

def from_config(attr_name: str) -> Any:
    config = CommandMain._load_config()
    value = getattr(config, attr_name)
    if value is config.unset:
        raise cappa.EmptyValue()
    return value

[DanCardin]

Yea I haven't yet lazified default factories, that should bring that down to 0 when not used. It was originally falling back on None because the only two sources of dynamic input were Env (where None` means it wasn't there) and Prompt/Confirm where None means there was no input.

And then further because in the context of a CLI command, you either have a value or not, and None would generally (always?) come from a lack of use of the cli arg.

So you're saying you have an explicitly set None config value with a further fallback that you dont want to default to?

[pawamoy]

So you're saying you have an explicitly set None config value with a further fallback that you dont want to default to?

I don't, actually, but I thought it wouldn't be uncommon to have None as a valid default value. Other formats than TOML have null values, so it could be useful/required to distinguish between null and unset. Even not considering data formats, maybe we want to consider a set but empty environment variable to be None, not "".

import os

def from_env(name: str) -> str | None:
    if value := os.getenv(name):
        return value
    return None  # ENVVAR= returns None, not ""

...

# This should stop at `None` and skip calling `something_else`.
cappa.Arg(default=cappa.ValueFrom(from_env, "VARNAME") | cappa.ValueFrom(something_else))

[DanCardin]

#180