Improve Python Fire's tab completion

[dbieber]

Please see this early stage design document for improving Python Fire's tab completion.

Comments on the design document are welcome!
Contributors also welcome! :)

[jtratner]

@dbieber - can you open up read access to everyone?

[dbieber]

Try now

[Ellmen]

I like this idea. I left a few thoughts in the doc. Not sure if this has been suggested before but it might make sense to have a "dev" version of the CLI with features like this and be able to ship a prod version with precomputed completions. I can take a stab at implementing this.

[dbieber]

I'm definitely on board with being able to ship a version of a Fire CLI with precomputed completions 👍. I'm not sure I totally understand the distinction you're drawing between "dev" and "prod" though. In "prod" mode, generating new completions would be disabled? Is that the only distinction or are there others?

[Ellmen]

Well another could be disabling the --completions flag in "prod". There could also be more verbose errors in "dev" although that would be outside the scope of the completions PR. Do you think it's too much overhead?

[dbieber]

I want to make sure things keep working well in the simple case of:

if __name__ == '__main__':
  fire.Fire()

In particular it would be great if in this case you can get tab completions after having run your CLI only once (or, better, before you even run it at all! This is possible if the completion script runs your CLI with some flag when you hit tab, like your-command -- --get-completions. We'd have to make sure this doesn't execute code the user wasn't intending to execute though.).
Fire gets used during development a bunch, so it's important that completions can be invalidated once the system realizes they're no longer relevant.

Once a Fire CLI is shipped with completions, I don't think there's any problem with continuing to update the completions. If all the completions were included, these updates should be a no-op. I suppose I do see value in freezing the completions if there are completions the developer doesn't want to include.

One way to freeze completions (akin to your "dev" mode) would be having a config like fire.Fire(freeze_completions=True). Another approach would be to include something in the completions mapping that indicates that it's frozen (haven't thought this last bit through). I'm not sure how necessary completion freezing is, or if it's worth the complexity that it adds. Adding it to the list at #98 though as a possible config to support.

[dbieber]

[As you can see from that list in #98 I've been really reluctant to add configs so far, but at some point we'll probably want to add a number of these. I want to make sure we do so in a way 1) that doesn't make people feel like they're lost in the documentation, 2) that keeps fire working well even for people that don't configure anything, 3) that never necessitates breaking backwards compatibility and that allows future configs to be added to the system seamlessly w/ a good naming convention.]

[Ellmen]

That makes sense and I like your point about not getting lost in the docs.
I feel a little uneasy about generating completions on the fly in prod especially since they could be different the second time using the CLI. I'll think some more about the cleanest way to freeze them.
It could be as simple as not creating the completions files if there is no PYTHON_FIRE_COMPLETION set. A user is unlikely to be sourcing the completions if they aren't choosing where to put them.

[dbieber]

Brainstorming here:

One possibility is having two places to look for completions:

• The first is the "prod" completions, included e.g. when you pip install a published CLI
• The second is PYTHON_FIRE_COMPLETION

If the first location has completions, only those are used. If not, then PYTHON_FIRE_COMPLETION is used.
PYTHON_FIRE_COMPLETION is updated "on the fly" by fire (but only if PYTHON_FIRE_COMPLETION is set).