[breaking] Rework `flag` function, restrict `nargs` on bool fields

[lebrice]

• Overhaul of the flag function:

  • Add negative_prefix and negative_option arguments to the flag function.
  • [breaking] Remove the weird default=True behaviour of setting the opposite of the default value

    
    def flag(
    default: bool | _MISSING_TYPE = MISSING,
    *,
    default_factory: Callable[[], bool] | _MISSING_TYPE = MISSING,
    negative_prefix: str | None = DEFAULT_NEGATIVE_PREFIX,
    negative_option: str | None = None,
    nargs: Literal["?"] | None = None,
    type: Callable[[str], bool] = str2bool,
    action: type[BooleanOptionalAction] = BooleanOptionalAction,
    **kwargs,
    ) -> bool:
    """A boolean field with a positive and negative command-line argument.

  If either default or default_factory are set, then both the field and the generated command-line arguments are optional. Otherwise, both are required.

  Negative flags are generated using negative_prefix and negative_option:

  • When negative_option is passed, it is used to create the negative flag.
  • Otherwise, negative_prefix is prepended to the field name to create the negative flag.

  NOTE: The negative flags don't accept a value. (i.e. --noverbose works, but --noverbose=True does not.) The positive flags can be used either with or without a value. """

Breaking changes:

• Make it invalid to use nargs not in {"?", None} for single boolean fields
• Rework and refactor the BooleanOptionalAction class.

Signed-off-by: Fabrice Normandin fabrice.normandin@gmail.com