python-fire
python-fire copied to clipboard
google
Multiline docstring in help with parameters and their descriptions
I'm using the latest version of Fire as of now and was wondering if it's possible to display a multiline docstring in help instead of concatenating it to one line. Also is there a way of displaying the available params and their descriptions in the help screen?
Example program:
# main.py
import fire
class MyCLI:
def create(name, surname):
"""
Method to create a user \n
And some second line to describe some specific cases.
And some third line that could be concatenated with the second one
:param name name of the user
:param surname surname of the user
:raises ValueError if user with this name and surname already exist
:returns: unique id of the created user
"""
...
def remove(id):
"""
Removes user given the id
:id unique id to identify the user
:raises ValueError if there is no user with the specified id
"""
...
if __name__ == '__main__':
cli = MyCLI()
fire.Fire(cli)
Expected help:
main.py -h
NAME
main.py -
SYNOPSIS
main.py COMMAND
COMMANDS
COMMAND is one of the following:
create
Method to create a user
And some second line to describe some specific cases. And some third line that could be concatenated with the second one
remove
Removes user given the id
Example command help (more specific)
main.py create -h
NAME
main.py create - Method to create a user
SYNOPSIS
main.py create NAME SURNAME
DESCRIPTION
Method to create a user
And some second line to describe some specific cases. And some third line that could be concatenated with the second one
--name: name of the user
--surname: surname of the user
raises ValueError if user with this name and surname already exist
returns: unique id of the created user
POSITIONAL ARGUMENTS
NAME
SURNAME
NOTES
You can also use flags syntax for POSITIONAL ARGUMENTS
Agreed on multi-line docstrings.
This is particularly important if people use whitespace for formatting in their docstrings, such as including usage examples.
The param descriptions should be showing up in the help in a separate section from the description. If that's not showing up, that's a bug. The return and raises information is being parsed but isn't being displayed yet, but should be in a later version.
Yes I think right now the params formatted like
:param name name of the user
:param surname surname of the user
aren't getting displayed in the help screen.
Multi-line docstrings issue is resolved.
As for the params, it works if you 1) add the missing self args to your methods (or mark them as @staticmethod) and 2) include a closing colon around your param directives.
E.g. if you update your code to this:
class MyCLI:
def create(self, name, surname):
"""
Method to create a user \n
And some second line to describe some specific cases.
And some third line that could be concatenated with the second one
:param name: name of the user
:param surname: surname of the user
:raises ValueError if user with this name and surname already exist
:returns: unique id of the created user
"""
pass
def remove(self, id):
"""
Removes user given the id
:param id: unique id to identify the user
:raises ValueError if there is no user with the specified id
"""
pass
fire.Fire(MyCLI())
Then these work:
MyCLI.py create -h
MyCLI.py remove -h
Of course we want our docstring parser to be as lenient as reasonably possible, so if we're able to support parsing args from your docstrings without compromising our ability to parse other docstrings, then we will. So, I'll leave the issue open for more flexibly/leniently parsing docstrings.
Hello, I need the configuration information of all cloud servers under my account and all the areas where cloud servers can be built. Please provide examples of the corresponding API and python code.
Hi okada8, I think your request is misplaced. This is an issue thread for Python Fire.
Is there any way to display the arguments from the docstring, even if they're not an explicitly named parameter in the function signature? In the example before, we accept bar as part of kwargs (and document that), but it won't show up in Fire.
def func(self, foo, **kwargs):
"""
:param str foo: (required) This argument shows up
:param str bar: (optional) This argument doesn't show up
"""
This is a very developer-centric view. Contrary to function arguments (or @annotated functions), docstrings can't be internationalized at runtime... CLI are also for the end users.
