8000 Documentation updates for '--help' and 'python -m fire' · randomprin/python-fire@aa72776 · GitHub
[go: up one dir, main page]
Skip to content

Commit aa72776

Browse files
dbiebercopybara-github
dbieber
authored and
copybara-github
committed
Documentation updates for '--help' and 'python -m fire'
PiperOrigin-RevId: 300798279 Change-Id: I21bfe6fe5596546b092c2968c9234febf357d4ba
1 parent cd008fb commit aa72776

File tree

4 files changed

+95
-25
lines changed

4 files changed

+95
-25
lines changed

‎README.md

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,17 @@
33
_Python Fire is a library for automatically generating command line interfaces
44
(CLIs) from absolutely any Python object._
55

6-
- Python Fire is a simple way to create a CLI in Python. [[1]](docs/benefits.md#simple-cli)
7-
- Python Fire is a helpful tool for developing and debugging Python code. [[2]](docs/benefits.md#debugging)
8-
- Python Fire helps with exploring existing code or turning other people's code
9-
into a CLI. [[3]](docs/benefits.md#exploring)
10-
- Python Fire makes transitioning between Bash and Python easier. [[4]](docs/benefits.md#bash)
11-
- Python Fire makes using a Python REPL easier by setting up the REPL with the
12-
modules and variables you'll need already imported and created. [[5]](docs/benefits.md#repl)
6+
- Python Fire is a simple way to create a CLI in Python.
7+
[[1]](docs/benefits.md#simple-cli)
8+
- Python Fire is a helpful tool for developing and debugging Python code.
9+
[[2]](docs/benefits.md#debugging)
10+
- Python Fire helps with exploring existing code or turning other people's
11+
code into a CLI. [[3]](docs/benefits.md#exploring)
12+
- Python Fire makes transitioning between Bash and Python easier.
13+
[[4]](docs/benefits.md#bash)
14+
- Python Fire makes using a Python REPL easier by setting up the REPL with the
15+
modules and variables you'll need already imported and created.
16+
[[5]](docs/benefits.md#repl)
1317

1418
## Installation
1519

‎docs/api.md

Lines changed: 54 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
## Python Fire Quick Reference
2+
13
| Setup | Command | Notes
24
| :------ | :------------------ | :---------
35
| install | `pip install fire` |
@@ -8,13 +10,56 @@
810
| Call | `fire.Fire()` | Turns the current module into a Fire CLI.
911
| Call | `fire.Fire(component)` | Turns `component` into a Fire CLI.
1012

11-
| Using a CLI | Command | Notes
12-
| :------------- | :------------------------- | :---------
13-
| [Help](using-cli.md#help-flag) | `command -- --help` |
14-
| [REPL](using-cli.md#interactive-flag) | `command -- --interactive` | Enters interactive mode.
15-
| [Separator](using-cli.md#separator-flag) | `command -- --separator=X` | This sets the separator to `X`. The default separator is `-`.
16-
| [Completion](using-cli.md#completion-flag) | `command -- --completion [shell]` | Generate a completion script for the CLI.
17-
| [Trace](using-cli.md#trace-flag) | `command -- --trace` | Gets a Fire trace for the command.
18-
| [Verbose](using-cli.md#verbose-flag) | `command -- --verbose` |
13+
| Using a CLI | Command | Notes |
14+
| :----------------------------------------- | :------------- | :------------- |
15+
| [Help](using-cli.md#help-flag) | `command | Show the help |
16+
: : --help` : screen. :
17+
| [REPL](using-cli.md#interactive-flag) | `command -- | Enters |
18+
: : --interactive` : interactive :
19+
: : : mode. :
20+
| [Separator](using-cli.md#separator-flag) | `command -- | This sets the |
21+
: : --separator=X` : separator to :
22+
: : : `X`. The :
23+
: : : default :
24+
: : : separator is :
25+
: : : `-`. :
26+
| [Completion](using-cli.md#completion-flag) | `command -- | Generate a |
27+
: : --completion : completion :
28+
: : [shell]` : script for the :
29+
: : : CLI. :
30+
| [Trace](using-cli.md#trace-flag) | `command -- | Gets a Fire |
31+
: : --trace` : trace for the :
32+
: : : command. :
33+
| [Verbose](using-cli.md#verbose-flag) | `command -- | |
34+
: : --verbose` : :
35+
36+
_Note that flags are separated from the Fire command by an isolated `--` arg.
37+
Help is an exception; the isolated `--` is optional for getting help._
38+
39+
## Arguments for Calling fire.Fire()
40+
41+
| Argument | Usage | Notes |
42+
| :-------- | :------------------------ | :----------------------------------- |
43+
| component | `fire.Fire(component)` | If omitted, defaults to a dict of |
44+
: : : all locals and globals. :
45+
| command | `fire.Fire(command='hello | Either a string or a list of |
46+
: : --name=5')` : arguments. If a string is provided, :
47+
: : : it is split to determine the :
48+
: : : arguments. If a list or tuple is :
49+
: : : provided, they are the arguments. If :
50+
: : : `command` is omitted, then :
51+
: : : `sys.argv[1\:]` (the arguments from :
52+
: : : the command line) are used by :
53+
: : : default. :
54+
| name | `fire.Fire(name='tool')` | The name of the CLI, ideally the |
55+
: : : name users will enter to run the :
56+
: : : CLI. This name will be used in the :
57+
: : : CLI's help screens. If the argument :
58+
: : : is omitted, it will be inferred :
59+
: : : automatically. :
60+
61+
## Using a Fire CLI without modifying any code
62+
63+
`python -m fire <module> <arguments>`
1964

20-
_Note that flags are separated from the Fire command by an isolated `--` arg._
65+
For example, `python -m fire calendar -h`.

‎docs/guide.md

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,22 @@ def main():
9999
fire.Fire(hello)
100100
```
101101

102+
##### Version 4: Fire Without Code Changes
103+
104+
If you have a file `example.py` that doesn't even import fire:
105+
106+
```python
107+
def hello(name):
108+
return 'Hello {name}!'.format(name=name)
109+
```
110+
111+
Then you can use it with Fire like this:
112+
113+
```bash
114+
$ python -m fire example hello --name=World
115+
Hello World!
116+
```
117+
102118
### Exposing Multiple Commands
103119

104120
In the previous example, we exposed a single function to the command line. Now
@@ -685,8 +701,9 @@ You can add the help flag to any command to see help and usage information. Fire
685701
incorporates your docstrings into the help and usage information that it
686702
generates. Fire will try to provide help even if you omit the isolated `--`
687703
separating the flags from the Fire command, but may not always be able to, since
688-
`help` is a valid argument name. Use this feature like this:
689-
`python example.py -- --help`.
704+
`help` is a valid argument name. Use this feature like this: `python
705+
example.py -- --help` or `python example.py --help` (or even `python example.py
706+
-h`).
690707

691708
The complete set of flags available is shown below, in the reference section.
692709

‎docs/index.md

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,17 @@
33
_Python Fire is a library for automatically generating command line interfaces
44
(CLIs) from absolutely any Python object._
55

6-
- Python Fire is a simple way to create a CLI in Python. [[1]](benefits.md#simple-cli)
7-
- Python Fire is a helpful tool for developing and debugging Python code. [[2]](benefits.md#debugging)
8-
- Python Fire helps with exploring existing code or turning other people's code
9-
into a CLI. [[3]](benefits.md#exploring)
10-
- Python Fire makes transitioning between Bash and Python easier. [[4]](benefits.md#bash)
11-
- Python Fire makes using a Python REPL easier by setting up the REPL with the
12-
modules and variables you'll need already imported and created. [[5]](benefits.md#repl)
6+
- Python Fire is a simple way to create a CLI in Python.
7+
[[1]](benefits.md#simple-cli)
8+
- Python Fire is a helpful tool for developing and debugging Python code.
9+
[[2]](benefits.md#debugging)
10+
- Python Fire helps with exploring existing code or turning other people's
11+
code into a CLI. [[3]](benefits.md#exploring)
12+
- Python Fire makes transitioning between Bash and Python easier.
13+
[[4]](benefits.md#bash)
14+
- Python Fire makes using a Python REPL easier by setting up the REPL with the
15+
modules and variables you'll need already imported and created.
16+
[[5]](benefits.md#repl)
1317

1418
## Installation
1519

0 commit comments

Comments
 (0)
0