Update architecture docs

Update the examples to more a modern way of doing things and bring some
names in line with other parts of the docs.

Author: mdellweg

docs/dev/learn/architecture.md

@@ -52,10 +52,12 @@ def mount(main: click.Group, **kwargs: Any) -> None:
 ## Contexts
 
 In `click`, every subcommand is accompanied by a `click.Context`, and objects can be attached to them.
-In this CLI we attach a [`PulpCLIContext`][pulp_cli.generic.PulpCLIContext] to the main command, which inherits from `pulp-glue`'s [`PulpContext`][pulp_glue.common.context.PulpContext].
+In this CLI we attach a [`PulpCLIContext`][pulp_cli.generic.PulpCLIContext] to the main command,
+which inherits from `pulp-glue`'s [`PulpContext`][pulp_glue.common.context.PulpContext].
 This context handles the communication to the pulp server through its `api` property.
 
-Further we encourage the handling of communication with certain endpoints by subclassing the [`PulpEntityContext`][pulp_glue.common.context.PulpEntityContext] or some of the resource-specific children, such as [PulpRepositoryContext][pulp_glue.common.context.PulpRepositoryContext].
+Further we encourage the handling of communication with certain endpoints by subclassing the [`PulpEntityContext`][pulp_glue.common.context.PulpEntityContext]
+or some of the resource-specific children, such as [`PulpRepositoryContext`][pulp_glue.common.context.PulpRepositoryContext].
 Some examples of this can be found under `pulp_glue/{plugin-name}/context.py`.
 
 By attaching them to the contexts of certain command groups, they are accessible to commands via the `pass_entity_context` decorator.
@@ -65,41 +67,58 @@ Those entity contexts should provide a common interface to the layer of `click`
 @pulp_group()
 @pass_pulp_context
 @click.pass_context
-def my_command(ctx, pulp_ctx):
-    ctx.obj = MyEntityContext(pulp_ctx)
+def my_resource(ctx, pulp_ctx: PulpContext) -> None:
+    ctx.obj = PulpMyResourceContext(pulp_ctx)
 
 
-@my_command.command()
+@my_resource.command()
 @pass_entity_context
-def my_sub_command(entity_ctx):
-    entity_ctx.entity = {"name": "myentity")
-    entity_ctx.destroy()
+def frobnicate(entity_ctx: PulpMyResourceContext) -> None:
+    entity_ctx.entity = {"name": "myentity"}
+    entity_ctx.frobnicate()
 ```
 
 ## Generics
 
 For certain often repeated patterns like listing all entities of a particular kind,
 we provide generic commands that use the underlying context objects.
 The following example shows the use of the [`show_command`][pulp_cli.generic.show_command] generic.
+It uses a generated lookup option that will populate the closest matching `entity_ctx` in the command hierarchy.
 
 ```python
-from pulp_cli.generic import name_option, show_command,
+from pulp_cli.generic import resource_lookup_option, show_command,
 
-lookup_params = [name_option]
-my_command.add_command(show_command(decorators=lookup_params))
+
+my_resource_lookup_option = resource_lookup_option(
+    "--my-resource",
+    context_class=PulpMyResourceContext,
+)
+lookup_params = [my_resource_lookup_option]
+my_resource.add_command(show_command(decorators=lookup_params))
+
+# The example from above could use the lookup option too.
+
+@my_resource.command()
+@my_resource_lookup_option
+@pass_entity_context
+def frobnicate(entity_ctx: PulpMyResourceContext) -> None:
+    # At this point, the lookup option has already selected an entity.
+    entity_ctx.frobnicate()
 ```
 
 To add options to these subcommands, pass a list of [`PulpOption`][pulp_cli.generic.PulpOption] objects to the `decorators` argument.
 Preferably these are created using the [`pulp_option`][pulp_cli.generic.pulp_option] factory.
+More specific factories for resource handling are [`resource_option`][pulp_cli.generic.resource_option] and [`resource_lookup_option`][pulp_cli.generic.resource_lookup_option].
 
+Another example is the `list-command` that allows filtering (based on the server's capabilities) by adding named options:
 ```python
 from pulp_cli.generic import list_command,
 
 filter_params = [
     pulp_option("--name"),
     pulp_option("--name-contains", "name__contains"),
 ]
-my_command.add_command(list_command(decorators=filter_params))
+my_resource.add_command(list_command(decorators=filter_params))
 ```
 
 ## Version dependent code paths
@@ -116,22 +135,23 @@ It will raise an error, once the first access to the server is attempted.
 
 ```python
 # In pulp_glue_my_plugin
-class MyEntityContext(PulpEntityContext):
-    def show(self, href):
-        if self.pulp_ctx.has_plugin(PluginRequirement("my_content", specifier=">=1.2.3", inverted=True)):
+class PulpMyResourceContext(PulpEntityContext):
+    NEEDS_PLUGINS = [PluginRequirement("my_plugin", specifier=">=1.0.0")]
+
+    def show(self) -> t.Dict[str, t.Any]:
+        if self.pulp_ctx.has_plugin(PluginRequirement("my_plugin", specifier=">=1.2.3", inverted=True)):
             # Versioned workaroud
             # see bug-tracker/12345678
-            return lookup_my_content_legacy(href)
-        return super().show(href)
+            return lookup_my_content_legacy(self.pulp_href)
+        return super().show()
 
 
 # In pulp_cli_my_plugin
 @main.command()
 @pass_pulp_context
-@click.pass_context
-def my_command(ctx, pulp_ctx):
-    pulp_ctx.needs_plugin(PluginRequirement("my_content", specifier=">=1.0.0"))
-    ctx.obj = MyEntityContext(pulp_ctx)
+def my_command(pulp_ctx:PulpContext) -> None:
+    pulp_ctx.needs_plugin(PluginRequirement("my_plugin", specifier=">=1.1.0"))
+    # From here on we can assume `my_plugin>=1.1.0`.
 ```
 
 To declare version restrictions on *options*, the [`preprocess_entity`][pulp_glue.common.context.PulpEntityContext.preprocess_entity] method can be used to check if a given option is present in the request body and conditionally apply the requirements to the context.

pulp_cli/generic.py

@@ -756,7 +756,10 @@ def pulp_option(*args: t.Any, **kwargs: t.Any) -> t.Callable[[FC], FC]:
 
 
 def resource_lookup_option(*args: t.Any, **kwargs: t.Any) -> t.Callable[[FC], FC]:
-    lookup_key: str = kwargs.pop("lookup_key", "name")
+    """
+    A factory to create a lookup option that will pass the lookup to the closest matching Context.
+    """
+    lookup_key: t.Optional[str] = kwargs.pop("lookup_key", "name")
     context_class: t.Type[PulpEntityContext] = kwargs.pop("context_class")
 
     def _option_callback(
@@ -788,9 +791,15 @@ def _option_callback(
                         value=value, option_name=param.name
                     )
                 )
-        else:
+        elif lookup_key is not None:
             # The named identity of a resource was passed
             entity_ctx.entity = {lookup_key: value}
+        else:
+            raise click.ClickException(
+                _("'{value}' is not recognised by {option_name}.").format(
+                    value=value, option_name=param.name
+                )
+            )
 
         return entity_ctx
 
@@ -801,14 +810,25 @@ def _option_callback(
     kwargs["expose_value"] = False
 
     if "help" not in kwargs:
-        kwargs["help"] = _(
-            "A resource to look for identified by <{lookup_key}> or by <href>."
-        ).format(lookup_key=lookup_key)
+        kwargs["help"] = (
+            _("A resource to look for identified by <href>.")
+            if lookup_key is None
+            else _("A resource to look for identified by <{lookup_key}> or by <href>.").format(
+                lookup_key=lookup_key
+            )
+        )
 
     return click.option(*args, **kwargs)
 
 
 def resource_option(*args: t.Any, **kwargs: t.Any) -> t.Callable[[FC], FC]:
+    """
+    Factory for an option that passes a preloaded PulpEntityContext to the command.
+
+    The resulting option will accept the entity being described in multiple ways, including its
+    href.
+    """
+
     default_plugin: t.Optional[str] = kwargs.pop("default_plugin", None)
     default_type: t.Optional[str] = kwargs.pop("default_type", None)
     lookup_key: str = kwargs.pop("lookup_key", "name")
@@ -924,11 +944,12 @@ def _multi_option_callback(
 
     if "help" not in kwargs:
         kwargs["help"] = _(
-            "Referenced resource, in the form {plugin_form}{type_form}<name> or by href. "
+            "Referenced resource, in the form {plugin_form}{type_form}<{lookup_key}> or by href. "
             "{plugin_default}{type_default}{multiple_note}"
         ).format(
             plugin_form=_("[<plugin>:]") if default_plugin else _("<plugin>:"),
             type_form=_("[<resource_type>:]") if default_type else _("<resource_type>:"),
+            lookup_key=lookup_key,
             plugin_default=(
                 _("'<plugin>' defaults to {plugin}. ").format(plugin=default_plugin)
                 if default_plugin
@@ -946,6 +967,9 @@ def _multi_option_callback(
 
 
 def type_option(*args: t.Any, **kwargs: t.Any) -> t.Callable[[FC], FC]:
+    """
+    A factory for `--type` options to allow selecting the class of the `PulpEntityContext` to use.
+    """
     choices: t.Dict[str, t.Type[PulpEntityContext]] = kwargs.pop("choices")
     assert choices and isinstance(choices, dict)
     type_names = list(choices.keys())

pulpcore/cli/core/upload.py

@@ -9,6 +9,7 @@
     list_command,
     pass_pulp_context,
     pulp_group,
+    resource_lookup_option,
     show_command,
 )
 
@@ -23,7 +24,12 @@ def upload(ctx: click.Context, pulp_ctx: PulpCLIContext, /) -> None:
     ctx.obj = PulpUploadContext(pulp_ctx)
 
 
-lookup_options = [href_option]
+upload_lookup_option = resource_lookup_option(
+    "--upload",
+    lookup_key=None,
+    context_class=PulpUploadContext,
+)
+lookup_options = [href_option, upload_lookup_option]
 
 upload.add_command(list_command())
 upload.add_command(show_command(decorators=lookup_options))