Pulp-cli usability discussion

Development
#1

I recently noticed something, that annoys me very greatly about Pulp CLI usage:

Namely, different sub-commands, tend to use different option names, for the same things.

For example, let’s suppose I want to see the repository with name “test”:

pulp deb repository show --name="test"

Now I decide, I actually want to see the latest repository version for that same repository. Instead of having to add just the subcommand before the show, I also need to change the option name:

pulp deb repository version show --repository="test"

This is because the repository command is “about repositories” and therefor has the option --name to refer to repositories, but the version command has the option --repository because --name to refer to repository names would not make sense here.

Would it be possible to add option names, that are descriptive independently of whether the relevant sub command is “about that entity” or not? For example, both pulp deb repository show and pulp deb repository version show might both accept the option --repository-name as an alias for --name and --repository respectively. (If it is possible to add aliases for options we don’t need to break the existing CLI interface for this).

Then I could run:

pulp deb repository show --repository-name="test"
pulp deb repository version show --repository-name="test"

Which allows me to make minimal adjustments to my first command for great convenience!

4 Likes
#2

This sounds like great idea in my opinion. I’ll add it to open floor agenda as good candidate for a story (RFE).

#3

This is a good suggestion. Please file an RFE for the pulp-cli project.

#4

“RFE” is just a fancy word for GitHub issue in this context?

#5

Yes it is :slight_smile:

#6
3 Likes
#7

The only reservation i have with this is that it is quite a lot to type, but yes for “command history recycling” readline style i can see the benefit.
So i assume these would be available additionally to the existing ones?

#8

I imagined the --<entity>-<field> type options as in addition to the short ones (where the <entity>) is implied by the command they are a part of. This preserves both backwards compatibility as well as the availability of the shorter option names.

PS.: Regarding option name length: One could consider --repo-name instead of --repository-name I guess, but that would mess with the consistency of the schema, probably does not work for most entities, so is probably not worth it.

#9

One of the problems I am seeing with this proposal is that some of the options currently support parsing both the HREF and the Name of a resource simultaneously. Which is quite user-friendly. Would it make sense to decouple these options? Instead of one “remote” option, we will have “remote-name” and “remote-href” (https://github.com/pulp/pulp-cli/blob/29fb074e5eae768fd8701f1824f23d233ca79604/pulpcore/cli/ansible/repository.py#L54-L66).

#10

Maybe I’m missing something obvious.
With the resource_option are we not in the position, where we can just specify pulp file remote show --remote <name-or-href>?
I think we could use the expose_value to determine whether resource_option should return a new context or change the lookup of an existing one in the stack.

#11

We can create a repository either with the name or href reference to a remote with the --remote option:

(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp file remote create --name aa --url https://fixtures.pulpproject.org/file/PULP_MANIFEST
{
  "pulp_href": "/pulp/api/v3/remotes/file/file/6b51eef0-3008-4d01-a2f1-2397b6b82e46/",
  "pulp_created": "2022-10-06T08:26:43.864568Z",
  "name": "aa",
  "url": "https://fixtures.pulpproject.org/file/PULP_MANIFEST",
  "ca_cert": null,
  "client_cert": null,
  "tls_validation": true,
  "proxy_url": null,
  "pulp_labels": {},
  "pulp_last_updated": "2022-10-06T08:26:43.864590Z",
  "download_concurrency": null,
  "max_retries": null,
  "policy": "immediate",
  "total_timeout": null,
  "connect_timeout": null,
  "sock_connect_timeout": null,
  "sock_read_timeout": null,
  "headers": null,
  "rate_limit": null
}

(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp file repository create --name aa --remote aa
{
  "pulp_href": "/pulp/api/v3/repositories/file/file/a115b974-5b8d-400e-a5a1-51f72ea4486e/",
  "pulp_created": "2022-10-06T08:27:23.308264Z",
  "versions_href": "/pulp/api/v3/repositories/file/file/a115b974-5b8d-400e-a5a1-51f72ea4486e/versions/",
  "pulp_labels": {},
  "latest_version_href": "/pulp/api/v3/repositories/file/file/a115b974-5b8d-400e-a5a1-51f72ea4486e/versions/0/",
  "name": "aa",
  "description": null,
  "retain_repo_versions": null,
  "remote": "/pulp/api/v3/remotes/file/file/6b51eef0-3008-4d01-a2f1-2397b6b82e46/",
  "autopublish": false,
  "manifest": "PULP_MANIFEST"
}

(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp file repository create --name bb --remote /pulp/api/v3/remotes/file/file/6b51eef0-3008-4d01-a2f1-2397b6b82e46/
{
  "pulp_href": "/pulp/api/v3/repositories/file/file/a9a90ec6-785f-4adb-a13a-3caca9652d5d/",
  "pulp_created": "2022-10-06T08:27:30.212005Z",
  "versions_href": "/pulp/api/v3/repositories/file/file/a9a90ec6-785f-4adb-a13a-3caca9652d5d/versions/",
  "pulp_labels": {},
  "latest_version_href": "/pulp/api/v3/repositories/file/file/a9a90ec6-785f-4adb-a13a-3caca9652d5d/versions/0/",
  "name": "bb",
  "description": null,
  "retain_repo_versions": null,
  "remote": "/pulp/api/v3/remotes/file/file/6b51eef0-3008-4d01-a2f1-2397b6b82e46/",
  "autopublish": false,
  "manifest": "PULP_MANIFEST"
}

My question is what to do in this particular case. Should I create two options for such a case or should I totally remove the possibility to work with href?

#12

That case (referring to related entities) is absolutely fine. The original claim was that certain subcommands of pulp file repository refer to that same repository sometimes by --name, sometimes by --repository-name. And I think, (at least for the latter) this is due to technical limitations.
My suggestion is to always use --repository which can accept either name or href.

#13

Hmm. Does it mean that you would still like to have the following commands available to prevent ambiguity?

pulp file repository show --repository [NAME|HREF]  # instead of having --name or --href
pulp file repository version show --repository [NAME|HREF]  # instead of having --repository-name or --repository-href
pulp file repository create --name aa --remote [NAME|HREF]  # instead of having --remote-name or --remote-href
2 Likes
#14

Yes, i think that would be the best option.

The question is, should we remove (deprecate and remove later) the then redundant other options?

#15

I was not aware of the existence of commands with an option named --remote that allows the remote to be referenced by either the relevant NAME or the HREF, so I did not consider that possibility in my original proposal. The existence of such options makes me think that the best overall design would be if ALL options that need some reference to an entity as their argument were named after the entity and would accept [NAME|HREF].

If we could get there, options currently named --name or --href could eventually be deprecated in favor of the more clearly named versions that flexibly take both kinds of argument.

So going back to my original example, the commands should become:

pulp deb repository show --repository [NAME|HREF]
pulp deb repository version show --repository [NAME|HREF]

Instead of what we have now (which I believe is something like):

pulp deb repository show [--name NAME|--href HREF]
pulp deb repository version show --repository NAME

The --repository [NAME|HREF] style option is nice and short, is named independently of the subcommand it attaches to, and covers both the NAME and HREF use case. If we consistently made all options like this, then I no longer see any need for --repository-name or --name or --href!

2 Likes
#16

I am glad that we have reached a consensus. I am now going to work on refactoring all related options to accept [NAME|HREF] consistently across the commands.

The original approach of having options such as --repository-name will not be considered anymore.

#17

What about using arguments? Something like this:

pulp deb repository show [NAME|HREF]
pulp deb repository version show [NAME|HREF] [VERSION]

This is the pattern we follow in our CLI (we use typer which adds to click by being type aware) and it’s much less typing.

1 Like
#18

@davidd, I like the idea. I am not sure about the compatibility impact. @x9c4, I would go with the following commands (best of both worlds) if you do not have any concerns:

pulp deb repository show [NAME|HREF]
pulp deb repository version show [NAME|HREF] [VERSION]
pulp deb repository create --name NAME --remote [NAME|HREF]
#19

Compatibility is def a concern - there are a fair number of pulp-cli users “in the wild”, and having to rewrite scripts for cosmetic changes makes people grumpy.

pulp-cli has avoided position-dependent parameters, and I don’t think I want to introduce them as a special case. Also, consider a command like “pulp deb repository version show 1 2” - if there’s a problem, did you typo the name, or the version, or just the order?

For reduced typing, I’d rather see us implement a feature we’ve discussed where pulp-cli “remembers” the last (or even a history-of) entities you’ve looked at/worked with, and following commands can essentially say “do X to the last repo I looked at”. We don’t have an RFC opened for this, I think because we haven’t thought it out well enough to have a stab at something resembling requirements for it…

2 Likes
#20

My memory about a feature idea like this was that you could enter the interactive shell of the cli, and “enter” the context of entities like directories. Once in the context of a repository you could simply call show, sync or versions list.