Add CliIgnoreArg to support integration with an existing parser

[kzrnm]

Fix #742

import sys
from argparse import ArgumentParser
from typing import Literal

from pydantic_settings import BaseSettings, CliApp, CliSettingsSource, CliIgnoreArg

parser = ArgumentParser()
parser.add_argument('--food', choices=['pear', 'kiwi', 'lime'], help='fruite')


class Settings(BaseSettings):
    name: str = 'Bob'
    food: CliIgnoreArg[Literal['pear', 'kiwi', 'lime']]


cli_settings = CliSettingsSource(Settings, root_parser=parser)
cli_settings.root_parser.print_help()
# usage: app.py [-h] [--food {pear,kiwi,lime}] [--name str]

# options:
#   -h, --help            show this help message and exit
#   --food {pear,kiwi,lime}
#                         fruite

sys.argv = ['example.py', '--food', 'kiwi', '--name', 'waldo']
s = CliApp.run(Settings, cli_settings_source=cli_settings)
print(s.model_dump())
# {'name': 'waldo', 'food': 'kiwi'}


# Load CLI settings from pre-parsed arguments. i.e., the parsing occurs elsewhere and we
# just need to load the pre-parsed args into the settings source.
parsed_args = parser.parse_args(['--food', 'lime', '--name', 'ralph'])
s = CliApp.run(Settings, cli_args=parsed_args, cli_settings_source=cli_settings)
print(s.model_dump())
# {'name': 'waldo', 'food': 'lime'}

Selected Reviewer: @dmontagu

[hramezani]

Thanks @kzrnm for the PR.

@kschwab Please review the PR when you have time.

[kschwab]

Thanks for the PR @kzrnm. Can you change the name from CliIgnoreArg to something like CliExternalArg? CliIgnoreArg is somewhat confusing since the arg is not ignored, it's just mapped from an external parser.

Additionally, since this is externally mapped, we will have to ensure that the parsed arg is str or list[str]. Internally, CliSettingsSource is just an overlay on top of EnvSettingsSource, so all CLI arguments are expected to be parsed as type str.

You will need to modify _resolve_parsed_args such that for each field name, you get the mapped cli_arg, and then modify val to str or list[str]. Then everything else should work as expected.

Lastly, please amend the docs for Integrating with Existing Parsers with the new annotation.