2019-12-03 16:11:41 -08:00
|
|
|
# Python Fire [](https://github.com/google/python-fire)
|
2020-03-09 11:16:29 -07:00
|
|
|
|
2017-07-13 17:06:32 -07:00
|
|
|
_Python Fire is a library for automatically generating command line interfaces
|
|
|
|
|
(CLIs) from absolutely any Python object._
|
2017-02-15 13:22:36 -08:00
|
|
|
|
2020-03-13 11:49:37 -07:00
|
|
|
- Python Fire is a simple way to create a CLI in Python.
|
|
|
|
|
[[1]](docs/benefits.md#simple-cli)
|
|
|
|
|
- Python Fire is a helpful tool for developing and debugging Python code.
|
|
|
|
|
[[2]](docs/benefits.md#debugging)
|
|
|
|
|
- Python Fire helps with exploring existing code or turning other people's
|
|
|
|
|
code into a CLI. [[3]](docs/benefits.md#exploring)
|
|
|
|
|
- Python Fire makes transitioning between Bash and Python easier.
|
|
|
|
|
[[4]](docs/benefits.md#bash)
|
|
|
|
|
- Python Fire makes using a Python REPL easier by setting up the REPL with the
|
|
|
|
|
modules and variables you'll need already imported and created.
|
|
|
|
|
[[5]](docs/benefits.md#repl)
|
2017-02-15 13:22:36 -08:00
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
2017-07-13 17:06:32 -07:00
|
|
|
To install Python Fire with pip, run: `pip install fire`
|
2017-02-15 13:22:36 -08:00
|
|
|
|
2017-07-13 17:06:32 -07:00
|
|
|
To install Python Fire with conda, run: `conda install fire -c conda-forge`
|
2017-07-17 16:38:19 -04:00
|
|
|
|
2017-07-13 17:06:32 -07:00
|
|
|
To install Python Fire from source, first clone the repository and then run:
|
|
|
|
|
`python setup.py install`
|
2017-07-17 16:38:19 -04:00
|
|
|
|
2017-02-15 13:22:36 -08:00
|
|
|
## Basic Usage
|
|
|
|
|
|
|
|
|
|
You can call `Fire` on any Python object:<br>
|
|
|
|
|
functions, classes, modules, objects, dictionaries, lists, tuples, etc.
|
|
|
|
|
They all work!
|
|
|
|
|
|
2019-07-24 14:26:20 -07:00
|
|
|
Here's an example of calling Fire on a function.
|
|
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
import fire
|
|
|
|
|
|
|
|
|
|
def hello(name="World"):
|
|
|
|
|
return "Hello %s!" % name
|
|
|
|
|
|
|
|
|
|
if __name__ == '__main__':
|
|
|
|
|
fire.Fire(hello)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then, from the command line, you can run:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
python hello.py # Hello World!
|
|
|
|
|
python hello.py --name=David # Hello David!
|
|
|
|
|
python hello.py --help # Shows usage information.
|
|
|
|
|
```
|
|
|
|
|
|
2017-07-13 17:06:32 -07:00
|
|
|
Here's an example of calling Fire on a class.
|
2017-02-15 13:22:36 -08:00
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
import fire
|
|
|
|
|
|
|
|
|
|
class Calculator(object):
|
|
|
|
|
"""A simple calculator class."""
|
|
|
|
|
|
|
|
|
|
def double(self, number):
|
|
|
|
|
return 2 * number
|
|
|
|
|
|
|
|
|
|
if __name__ == '__main__':
|
|
|
|
|
fire.Fire(Calculator)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then, from the command line, you can run:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
python calculator.py double 10 # 20
|
|
|
|
|
python calculator.py double --number=15 # 30
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
To learn how Fire behaves on functions, objects, dicts, lists, etc, and to learn
|
2017-07-13 17:06:32 -07:00
|
|
|
about Fire's other features, see the [Using a Fire CLI page](docs/using-cli.md).
|
2017-02-15 13:22:36 -08:00
|
|
|
|
2017-07-13 17:06:32 -07:00
|
|
|
For additional examples, see [The Python Fire Guide](docs/guide.md).
|
2017-03-11 21:25:29 +00:00
|
|
|
|
2017-02-15 13:22:36 -08:00
|
|
|
## Why is it called Fire?
|
|
|
|
|
|
|
|
|
|
When you call `Fire`, it fires off (executes) your command.
|
|
|
|
|
|
2017-03-11 21:25:29 +00:00
|
|
|
## Where can I learn more?
|
|
|
|
|
|
2017-07-13 17:06:32 -07:00
|
|
|
Please see [The Python Fire Guide](docs/guide.md).
|
2017-03-11 21:25:29 +00:00
|
|
|
|
2017-02-15 13:22:36 -08:00
|
|
|
## Reference
|
|
|
|
|
|
|
|
|
|
| Setup | Command | Notes
|
|
|
|
|
| :------ | :------------------ | :---------
|
|
|
|
|
| install | `pip install fire` |
|
|
|
|
|
|
|
|
|
|
| Creating a CLI | Command | Notes
|
|
|
|
|
| :--------------| :--------------------- | :---------
|
|
|
|
|
| import | `import fire` |
|
|
|
|
|
| Call | `fire.Fire()` | Turns the current module into a Fire CLI.
|
|
|
|
|
| Call | `fire.Fire(component)` | Turns `component` into a Fire CLI.
|
|
|
|
|
|
2020-03-09 11:16:29 -07:00
|
|
|
| Using a CLI | Command | Notes
|
|
|
|
|
| :---------------------------------------------- | :-------------------------------------- | :----
|
|
|
|
|
| [Help](docs/using-cli.md#help-flag) | `command --help` or `command -- --help` |
|
|
|
|
|
| [REPL](docs/using-cli.md#interactive-flag) | `command -- --interactive` | Enters interactive mode.
|
|
|
|
|
| [Separator](docs/using-cli.md#separator-flag) | `command -- --separator=X` | Sets the separator to `X`. The default separator is `-`.
|
|
|
|
|
| [Completion](docs/using-cli.md#completion-flag) | `command -- --completion [shell]` | Generates a completion script for the CLI.
|
|
|
|
|
| [Trace](docs/using-cli.md#trace-flag) | `command -- --trace` | Gets a Fire trace for the command.
|
|
|
|
|
| [Verbose](docs/using-cli.md#verbose-flag) | `command -- --verbose` |
|
2017-03-31 19:03:55 +00:00
|
|
|
|
2019-07-24 14:26:20 -07:00
|
|
|
_Note that these flags are separated from the Fire command by an isolated `--`._
|
2017-02-15 13:22:36 -08:00
|
|
|
|
2018-12-01 03:00:46 +05:30
|
|
|
## License
|
2017-02-15 13:22:36 -08:00
|
|
|
|
2018-12-14 15:07:43 -08:00
|
|
|
Licensed under the
|
|
|
|
|
[Apache 2.0](https://github.com/google/python-fire/blob/master/LICENSE) License.
|
|
|
|
|
|
2017-02-15 13:22:36 -08:00
|
|
|
## Disclaimer
|
|
|
|
|
|
|
|
|
|
This is not an official Google product.
|
