Merge pull request #150 from DanCardin/dc/destructure-arg

feat: Introduce `Arg.destructure()` and `Arg.has_value`.

docs/source/arg.md

@@ -258,6 +258,8 @@ The `group` argument can be any of:
  Argument 'arg1' is not allowed with argument 'arg2'
  ```
 
+(exclusive-group-syntax)=
+
 ### Dedicated Mutual Exclusion Syntax
 
 A potentially common use of mutually exclusive arguments would be two distinct
@@ -344,3 +346,64 @@ Natively (at present), cappa doesn't have any specific `dict` type inference bec
 ambiguous what CLI input shape that ought to map to. However, by combining that with
 a dedicated `parse=json.loads` annotation, `example.py '{"foo": "bar"}'` now yields
 `Example({'foo': 'bar'})`.
+
+### `Arg.has_value`
+
+`Arg(has_value=True/False)` can be used to explicitly control whether the argument in question
+corresponds to a destination-type attribute as a value.
+
+For example the `Arg` that produces the `--help` option has a dedicated action which produces
+help text, and as such has a `has_value=False`.
+
+While there may not be much point in manually setting this attribute to `True` (because it will default
+to `True` in most cases), you **could** conceivably manually combine `has_value=False` and a
+custom [action](#Action), to avoid cappa trying to map your `Arg` back to a specific attribute.
+
+### `Arg.destructured`/`Arg.destructure()`
+
+**Generally** a single class/type corresponds to a command, and that type's attributes correspond to
+the arguments/options for that command.
+
+The [exclusive group syntax](#exclusive-group-syntax) is one counter example, where a single
+class attribute maps to more than one CLI argument.
+
+"Destructured" arguments are essentially the inverse, in that they allow multiple attributes
+(and thus CLI arguments) to be mapped back to a single command's class attribute.
+
+```python
+from __future__ import annotations
+from typing import Annotated
+
+@dataclass
+class Args:
+ sub_object: Annotated[SubObject, Arg.destructured()]
+
+
+@dataclass
+class SubObject:
+ arg1: Annotated[str, Arg(long=True)]
+ arg2: Annotated[int, Arg(long=True)]
+```
+
+This essentially fans out the `--arg1=foo --arg2=2` CLI arguments up into the parent `Args` command,
+while ultimately mapping the resultant values back into the expected output structure of:
+`Args(sub_object=SubObject(arg1='foo', arg2=2))`.
+
+This concept has a couple of practical uses:
+
+- Code/argument reuse: In the above example `SubObject` can now be shared between multiple subcommands
+ to provide the same set of arguments in different places **without** requiring subclassing.
+
+- Logical grouping/organization: This allows grouping of logically related fields in the **python**
+ code without affecting how those arguments are represented in the CLI shape.
+
+```{note}
+Currently `Arg.destructure()` only works with **singular concrete** type annotations. That is,
+in the above example `Annotated[SubObject, Arg.destructured()]`;
+whereas it will raise a `ValueError` if given `SubObject | None` or other more exotic annotations.
+
+Principally, `Annotated[SubObject | None, Arg.destructured()]` **could** make sense to imply that all
+child options are therefore optional, or that if any child attributes are missing, then that implies
+`sub_object=None` at the top level. However both of these are mechanically much more complex than the
+feature, as it exists today.
+```

src/cappa/arg.py

@@ -6,6 +6,9 @@
 import enum
 import typing
 from collections.abc import Callable
+from typing import Union
+
+from typing_extensions import TypeAlias
 
 from cappa.class_inspect import Field, extract_dataclass_metadata
 from cappa.completion.completers import complete_choices
@@ -71,6 +74,9 @@ def is_bool_action(self):
  return self in {self.store_true, self.store_false}
 
 
+ArgActionType: TypeAlias = Union[ArgAction, Callable]
+
+
 @dataclasses.dataclass(order=True)
 class Group:
  order: int = 0
@@ -128,6 +134,11 @@ class Arg(typing.Generic[T]):
  deprecated: If supplied, the argument will be marked as deprecated. If given `True`,
  a default message will be generated, otherwise a supplied string will be
  used as the deprecation message.
+ destructured: When set, destructures the annotated type into current-level arguments.
+ See `Arg.destructure`.
+ has_value: Whether the argument has a value that should be saved back to the destination
+ type. For most `Arg`, this will default to `True`, however `--help` is an example
+ of an `Arg` for which it is false.
  """
 
  value_name: str | EmptyType = Empty
@@ -141,14 +152,17 @@ class Arg(typing.Generic[T]):
  group: str | tuple[int, str] | Group | EmptyType = Empty
 
  hidden: bool = False
- action: ArgAction | Callable | None = None
+ action: ArgActionType | None = None
  num_args: int | None = None
  choices: list[str] | None = None
  completion: Callable[..., list[Completion]] | None = None
  required: bool | None = None
  field_name: str | EmptyType = Empty
  deprecated: bool | str = False
 
+ destructured: Destructured | None = None
+ has_value: bool | None = None
+
  annotations: list[type] = dataclasses.field(default_factory=list)
 
  @classmethod
@@ -190,15 +204,20 @@ def collect(
  default_long=default_long,
  exclusive=exclusive,
  )
- result.append(normalized_arg)
+
+ if arg.destructured:
+ destructured_args = destructure(normalized_arg, type_view)
+ result.extend(destructured_args)
+ else:
+ result.append(normalized_arg)
 
  return list(explode_negated_bool_args(result))
 
  def normalize(
  self,
  type_view: TypeView | None = None,
  fallback_help: str | None = None,
- action: ArgAction | Callable | None = None,
+ action: ArgActionType | None = None,
  default: typing.Any = Empty,
  field_name: str | None = None,
  default_short: bool = False,
@@ -226,6 +245,7 @@ def normalize(
  group = infer_group(self, short, long, exclusive)
 
  value_name = infer_value_name(self, field_name, num_args)
+ has_value = infer_has_value(self, action)
 
  return dataclasses.replace(
  self,
@@ -242,8 +262,13 @@ def normalize(
  help=help,
  completion=completion,
  group=group,
+ has_value=has_value,
  )
 
+ @classmethod
+ def destructure(cls, settings: Destructured | None = None):
+ return cls(destructured=settings or Destructured())
+
  def names(self, *, n=0) -> list[str]:
  short_names = typing.cast(list, self.short or [])
  long_names = typing.cast(list, self.long or [])
@@ -415,7 +440,7 @@ def infer_choices(arg: Arg, type_view: TypeView) -> list[str] | None:
 
 def infer_action(
  arg: Arg, type_view: TypeView, long, default: typing.Any
-) -> ArgAction | Callable:
+) -> ArgActionType:
  if arg.count:
  return ArgAction.count
 
@@ -458,7 +483,7 @@ def infer_action(
 def infer_num_args(
  arg: Arg,
  type_view: TypeView,
- action: ArgAction | Callable,
+ action: ArgActionType,
  long,
 ) -> int:
  if arg.num_args is not None:
@@ -607,3 +632,16 @@ def explode_negated_bool_args(args: typing.Sequence[Arg]) -> typing.Iterable[Arg
 
  if not yielded:
  yield arg
+
+
+def infer_has_value(arg: Arg, action: ArgActionType):
+ if arg.has_value is not None:
+ return arg.has_value
+
+ if isinstance(action, ArgAction) and action in ArgAction.value_actions():
+ return False
+
+ return True
+
+
+from cappa.destructure import Destructured, destructure # noqa: E402

src/cappa/command.py

@@ -6,7 +6,7 @@
 from collections.abc import Callable
 
 from cappa import class_inspect
-from cappa.arg import Arg, ArgAction, Group
+from cappa.arg import Arg, Group
 from cappa.docstring import ClassHelpText
 from cappa.env import Env
 from cappa.help import HelpFormatable, HelpFormatter, format_short_help
@@ -199,7 +199,7 @@ def map_result(self, command: Command[T], prog: str, parsed_args) -> T:
  if is_subcommand:
  continue
 
- assert arg.default is not Empty
+ assert arg.default is not Empty, arg
  value = arg.default
 
  else:
@@ -231,9 +231,8 @@ def map_result(self, command: Command[T], prog: str, parsed_args) -> T:
 
  def value_arguments(self):
  for arg in self.arguments:
- if isinstance(arg, Arg):
- if arg.action in ArgAction.value_actions():
- continue
+ if isinstance(arg, Arg) and not arg.has_value:
+ continue
 
  yield arg
 

src/cappa/destructure.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from type_lens import TypeView
+
+from cappa.arg import Arg, ArgActionType
+from cappa.invoke import fulfill_deps
+from cappa.output import Output
+from cappa.parser import ParseContext, Value, determine_action_handler
+from cappa.typing import assert_type
+
+
+@dataclass
+class Destructured: ...
+
+
+def destructure(arg: Arg, type_view: TypeView):
+ if not isinstance(type_view.annotation, type):
+ raise ValueError(
+ "Destructured arguments currently only support singular concrete types."
+ )
+
+ command: Command = Command.get(type_view.annotation)
+ virtual_args = Command.collect(command).arguments
+
+ arg.parse = lambda v: command.cmd_cls(**v)
+
+ result = [arg]
+ for virtual_arg in virtual_args:
+ if isinstance(virtual_arg, Subcommand):
+ raise ValueError(
+ "Subcommands are unsupported in the context of a destructured argument"
+ )
+
+ assert virtual_arg.action
+ virtual_arg.action = restructure(arg, virtual_arg.action)
+ virtual_arg.has_value = False
+
+ result.append(virtual_arg)
+
+ return result
+
+
+def restructure(root_arg: Arg, action: ArgActionType):
+ action_handler = determine_action_handler(action)
+
+ def restructure_action(context: ParseContext, arg: Arg, value: Value):
+ root_field_name = assert_type(root_arg.field_name, str)
+ result = context.result.setdefault(root_field_name, {})
+
+ fulfilled_deps: dict = {
+ Command: context.command,
+ Output: context.output,
+ ParseContext: context,
+ Arg: arg,
+ Value: value,
+ }
+ kwargs = fulfill_deps(action_handler, fulfilled_deps)
+ action_result = action_handler(**kwargs)
+
+ assert arg.parse
+ result[arg.field_name] = arg.parse(action_result)
+ return result
+
+ return restructure_action
+
+
+from cappa.command import Command # noqa: E402
+from cappa.subcommand import Subcommand # noqa: E402

src/cappa/help.py

@@ -41,6 +41,7 @@ def create_version_arg(version: str | Arg | None = None) -> Arg | None:
  long=["--version"],
  help="Show the version and exit.",
  group=(4, "Help"),
+ action=ArgAction.version,
  )
 
  if version.value_name is Empty:
@@ -66,6 +67,7 @@ def create_help_arg(help: bool | Arg | None = True) -> Arg | None:
  long=["--help"],
  help="Show this message and exit.",
  group=(4, "Help"),
+ action=ArgAction.help,
  )
 
  return help.normalize(action=ArgAction.help, field_name="help", default=None)
@@ -81,6 +83,7 @@ def create_completion_arg(completion: bool | Arg = True) -> Arg | None:
  choices=["generate", "complete"],
  group=(4, "Help"),
  help="Use `--completion generate` to print shell-specific completion source.",
+ action=ArgAction.completion,
  )
 
  return completion.normalize(

src/cappa/parser.py

@@ -4,7 +4,7 @@
 import typing
 from collections import deque
 
-from cappa.arg import Arg, ArgAction, Group
+from cappa.arg import Arg, ArgAction, ArgActionType, Group
 from cappa.command import Command, Subcommand
 from cappa.completion.types import Completion, FileCompletion
 from cappa.help import format_subcommand_names
@@ -180,6 +180,7 @@ def collect_arguments(command: Command) -> list[Arg | Subcommand]:
  isinstance(arg, Arg)
  and not arg.short
  and not arg.long
+ and not arg.destructured
  or isinstance(arg, Subcommand)
  ):
  result.append(arg)
@@ -576,13 +577,7 @@ def consume_arg(
  if option and field_name in context.missing_options:
  context.missing_options.remove(field_name)
 
- action = arg.action
- assert action
-
- if isinstance(action, ArgAction):
- action_handler = process_options[action]
- else:
- action_handler = action
+ action_handler = determine_action_handler(arg.action)
 
  fulfilled_deps: dict = {
  Command: context.command,
@@ -651,6 +646,15 @@ def store_append(context: ParseContext, arg: Arg, value: Value[typing.Any]):
  return result
 
 
+def determine_action_handler(action: ArgActionType | None):
+ assert action
+
+ if isinstance(action, ArgAction):
+ return process_options[action]
+
+ return action
+
+
 process_options: dict[ArgAction, typing.Callable] = {
  ArgAction.help: HelpAction.from_context,
  ArgAction.version: VersionAction.from_arg,