Get a list of all valid commands when writing --help

[bfelbo]

Thanks for creating this amazing library. I'm somewhat confused as to how the --help command is implemented. When running python example.py --help Fire only prints the flags, not the actual commands that can be run (see example below):

NAME
    fury.py

SYNOPSIS
    fury.py <flags>

FLAGS
    --verbosity=VERBOSITY

How do I make --help show all the possible commands and why is that not the default? :)

[dbieber]

Hi @bfelbo,

Are you suggesting that the help show:

fury.py --verbosity=VERBOSITY

or is there a command that's actually missing from the help, that you'd like it to show?

It should be showing all the possible commands, but not listed out as all possible complete commands explicitly simply due to formatting considerations. In particular, all commands share a prefix, and sometimes that prefix is quite long, so we choose not to write out that prefix repeatedly. Always open to suggestions for improvement though.

[bfelbo]

Thanks for the response. I'll make it more clear :) See the below example from the docs.

import fire

class Calculator(object):

  def add(self, x, y):
    return x + y

  def multiply(self, x, y):
    return x * y

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

Right now running python example.py --help returns the following:

NAME
    example.py

SYNOPSIS
    example.py

I think it'd be great if running help would actually tell you what CLI commands are available, i.e. add and multiply in this case. Otherwise, how can you figure out what you can do with the CLI? Maybe I'm missing something obvious here :)

[bfelbo]

It should be showing all the possible commands

This doesn't seem to be the case? (see my previous comment and example)

[saltyfireball]

@bfelbo As far as I know, it doesn't generate the options for you. You're saying it would be nice if help also showed something like this?

add - examply.py add x y
multiply - examply.py multiply x y

I don't think that would be too hard to add-in.

[bfelbo]

Exactly. That would be amazing!

For the class-based interface, I would probably ignore the self argument. It would then become something like the following:

NAME
    example.py

COMMANDS
    add x y
    multiply x y

SYNOPSIS
    example.py

[bfelbo]

If the arguments have a default, it'd be great to include them too, e.g.:

NAME
    example.py

COMMANDS
    add x y
    multiply x y
    root x z=2

SYNOPSIS
    example.py

I'm not really sure what the SYNOPSIS part is useful for, even in the case of NAME != SYNOPSIS. If you're worried the output gets too long, it would perhaps make sense to remove it?

[saltyfireball]

@bfelbo so I was just playing around. If you return self from your functions you can get a little bit closer to what you're looking for:

import fire
class Calculator(object):
    """A simple calculator class."""
    def __init__(self, meow=True):
        self.meow=meow
        self.db = None

    def double(self, number):
        self.db = 2 * number
        return self

    def add(self, number):
        self.db = 2 * number
        return self

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

Now when I run this I get a help screen with COMMANDS:

python runner.py double 10

NAME
    runner.py double 10 - A simple calculator class.

SYNOPSIS
    runner.py double 10 COMMAND | VALUE

DESCRIPTION
    A simple calculator class.

COMMANDS
    COMMAND is one of the following:

     add

     double

[saltyfireball]

@bfelbo Ignoring that my example isn't really functional, it does show that COMMANDS are parsed at some point. and we could make use of that to extend the general response from --help

This would be a nice upgrade - and I think fits the theme of bootstrapping classes into a more friendly cli.

[dbieber]

Agreed this is an issue. Let me explain why the current behavior is as it is, and how we can probably fix it.

Current State

"--help" vs "-- --help"

--help, --interactive, --verbose, etc are special Fire arguments. Normally they are separated from the standard arguments to a Fire CLI by a separating --. This is to avoid confusion between arguments intended for the CLI developers functions and arguments intended for Fire itself.

However, in order to let users get help the way they expect, we make an exception for --help. (Eventually we may want to broaden this exception to all of Fire's args, but for now it's just for --help.) This means that if a user specifies "--help" or "-h" and the CLI isn't expecting an argument named "help" or "h", we'll show the user help for the current component.

Help for Objects vs Help for Classes

The help screen is meant to show all the commands for the current component. If the current component is a class, often the only thing you can do is initialize it. Only after it's initialized does it make sense to access and call its methods. If the current component is an object (which happens for example after a class has been initialized) then the methods on that object are shown in the help as commands.

You can use a separator (-) to indicate that you're done passing arguments to a component. Using a separator will cause a class to be initialized without waiting for additional arguments.

Getting Help Today

class --help # Shows help for the class. This is often unhelpful, and is the main issue in this issue.
class -- --help # Same as previous
class - --help # Instantiates an object of class class, then shows help for that object. This is more useful help, but unintuitive to users.
class - -- --help # Same as previous.

Next Steps [Edit: never mind, see next comment instead]

The solution will be to make class --help equivalent to class - -- --help, rather than to class -- --help as it is today.

References in the Code

Here is where Fire checks to see if the user is requesting help without a separating --.

https://github.com/google/python-fire/blob/1ac5105a0437518785033f47dd78746678e5133a/fire/core.py#L438-439

The logic for separators is at

python-fire/fire/core.py

Lines 442 to 450 in 1ac5105

	saved_args = []
	used_separator = False
	if separator in remaining_args:
	# For the current component, only use arguments up to the separator.
	separator_index = remaining_args.index(separator)
	saved_args = remaining_args[separator_index + 1:]
	remaining_args = remaining_args[:separator_index]
	used_separator = True
	assert separator not in remaining_args

and

python-fire/fire/core.py

Line 570 in 1ac5105

if used_separator:

Basically what we'll have to change is:

Instead of immediately breaking at 439 when --help is observed, we'll first do one more pass through the big while loop as if there was a separator, and then we'll break to show help.

[dbieber]

Actually, perhaps it's even better to just show the methods of a class in that class's help screen, even if the class hasn't been instantiated yet. We'll just need to be careful in the presentation to make clear which flags are required (because the methods can't be called until after the class is initialized).

[saltyfireball]

Actually, perhaps it's even better to just show the methods of a class in that class's help screen, even if the class hasn't been instantiated yet. We'll just need to be careful in the presentation to make clear which flags are required (because the methods can't be called until after the class is initialized).

@dbieber I think this would work perfectly. Like you previously outlined

class --help 

Should just go into details on that class, like an improved version of what class - --help does.

[dbieber]

The help text is generated at:

python-fire/fire/helptext.py

Line 47 in 1ac5105

def HelpText(component, trace=None, verbose=False):

The list of possible actions (including commands) is generated by

python-fire/fire/helptext.py

Line 61 in 1ac5105

actions_grouped_by_kind = _GetActionsGroupedByKind(component, verbose=verbose)

The commands are aggregated at:

python-fire/fire/helptext.py

Lines 330 to 331 in 1ac5105

	if value_types.IsCommand(member):
	commands.Add(name=member_name, member=member)

And isCommand is defined at:

python-fire/fire/value_types.py

Lines 35 to 36 in 1ac5105

	def IsCommand(component):
	return inspect.isroutine(component) or inspect.isclass(component)

---

The actual string formatting to build the help text starts at

python-fire/fire/helptext.py

Line 65 in 1ac5105

# Sections:

[dbieber]

Here's a minimal example that would need to be fixed to resolve this:

In [1]: class A: 
   ...:     def x(self): 
   ...:         return 0 
   ...:                                                                                                                                                           

In [5]: import fire                                                                                                                                               

In [6]: fire.completion.VisibleMembers(A)                                                                                                                         
Out[6]: []  # This will need to include x.

In [7]: fire.completion.VisibleMembers(A())                                                                                                                       
Out[7]: [('x', <bound method A.x of <__main__.A object at 0x10af2c790>>)]

VisibleMembers is defined here:

python-fire/fire/completion.py

Line 347 in 1ac5105

def VisibleMembers(component, class_attrs=None, verbose=False):

[dbieber]

The code ignoring methods in classes is here:

python-fire/fire/completion.py

Lines 331 to 334 in 1ac5105

	if class_attr and class_attr.kind in ('method', 'property'):
	# methods and properties should be accessed on instantiated objects,
	# not uninstantiated classes.
	return False

Simply changing that from False to True will result in methods being included in the help. Additional changes will likely also be needed to make sure flags are marked as required when appropriate so we don't falsely give the impression that these methods are callable before the class has been instantiated.