8000 Initial commit for Python Fire. · PythonNuts/python-fire@9f9630a · GitHub
[go: up one dir, main page]
Skip to content

Commit 9f9630a

Browse files
dbieberdbieber
committed
Initial commit for Python Fire.
0 parents  commit 9f9630a

38 files changed

+4566
-0
lines changed

‎CONTRIBUTING.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# How to contribute
2+
3+
We'd love to accept your patches and contributions to this project. There are
4+
just a few small guidelines you need to follow.
5+
6+
## Contributor License Agreement
7+
8+
Contributions to this project must be accompanied by a Contributor License
9+
Agreement. You (or your employer) retain the copyright to your contribution,
10+
this simply gives us permission to use and redistribute your contributions as
11+
part of the project. Head over to <https://cla.developers.google.com/> to see
12+
your current agreements on file or to sign a new one.
13+
14+
You generally only need to submit a CLA once, so if you've already submitted one
15+
(even if it was for a different project), you probably don't need to do it
16+
again.
17+
18+
## Code reviews
19+
20+
All submissions, including submissions by project members, require review. We
21+
use GitHub pull requests for this purpose. Consult [GitHub Help] for more
22+
information on using pull requests.
23+
24+
[GitHub Help]: https://help.github.com/articles/about-pull-requests/

‎LICENSE

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Copyright 2017 Google Inc. All rights reserved.
2+
3+
Licensed under the Apache License, Version 2.0 (the "License");
4+
you may not use this file except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
http://www.apache.org/licenses/LICENSE-2.0
8+
9+
Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.

‎README.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Python Fire
2+
_Python Fire is a library for creating command line interfaces (CLIs) from
3+
absolutely any Python object._
4+
5+
- Python Fire is a simple way to create a CLI in Python. [[1]](doc/benefits.md#simple-cli)
6+
- Python Fire is a helpful tool for developing and debugging Python code. [[2]](doc/benefits.md#debugging)
7+
- Python Fire helps with exploring existing code or turning other people's code
8+
into a CLI. [[3]](doc/benefits.md#exploring)
9+
- Python Fire makes transitioning between Bash and Python easier. [[4]](doc/benefits.md#bash)
10+
- Python Fire makes using a Python REPL easier by setting up the REPL with the
11+
modules and variables you'll need already imported and created. [[5]](doc/benefits.md#repl)
12+
13+
## Installation
14+
15+
`pip install fire`
16+
17+
## Basic Usage
18+
19+
You can call `Fire` on any Python object:<br>
20+
functions, classes, modules, objects, dictionaries, lists, tuples, etc.
21+
They all work!
22+
23+
Here's a simple example.
24+
25+
```python
26+
import fire
27+
28+
class Calculator(object):
29+
"""A simple calculator class."""
30+
31+
def double(self, number):
32+
return 2 * number
33+
34+
if __name__ == '__main__':
35+
fire.Fire(Calculator)
36+
```
37+
38+
Then, from the command line, you can run:
39+
40+
```bash
41+
python calculator.py double 10 # 20
42+
python calculator.py double --number=15 # 30
43+
```
44+
45+
To learn how Fire behaves on functions, objects, dicts, lists, etc, and to learn
46+
about Fire's other features, see the [Using a Fire CLI page](doc/using-cli.md).
47+
48+
49+
## Why is it called Fire?
50+
51+
When you call `Fire`, it fires off (executes) your command.
52+
53+
54+
## Reference
55+
56+
| Setup | Command | Notes
57+
| :------ | :------------------ | :---------
58+
| install | `pip install fire` |
59+
60+
| Creating a CLI | Command | Notes
61+
| :--------------| :--------------------- | :---------
62+
| import | `import fire` |
63+
| Call | `fire.Fire()` | Turns the current module into a Fire CLI.
64+
| Call | `fire.Fire(component)` | Turns `component` into a Fire CLI.
65+
66+
| Using a CLI | Command | Notes
67+
| :------------- | :------------------------- | :---------
68+
| [Help](doc/using-cli.md#help-flag) | `command -- --help` |
69+
| [REPL](doc/using-cli.md#interactive-flag) | `command -- --interactive` | Enters interactive mode.
70+
| [Separator](doc/using-cli.md#separator-flag) | `command -- --separator=X` | This sets the separator to `X`. The default separator is `-`.
71+
| [Completion](doc/using-cli.md#completion-flag) | `command -- --completion` | Generate a completion script for the CLI.
72+
| [Trace](doc/using-cli.md#trace-flag) | `command -- --trace` | Gets a Fire trace for the command.
73+
| [Verbose](doc/using-cli.md#verbose-flag) | `command -- --verbose` |
74+
_Note that flags are separated from the Fire command by an isolated `--` arg._
75+
76+
77+
## Disclaimer
78+
79+
This is not an official Google product.

‎doc/benefits.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Benefits of Python Fire
2+
3+
## Python Fire is a simple way to create a CLI in Python. <a name="simple-cli"></a>
4+
5+
It's dead simple. Simply write the functionality you want exposed at the command
6+
line as a function / module / class, and then call Fire. With this addition of a
7+
single-line call to Fire, your CLI is ready to go.
8+
9+
10+
## Python Fire is a helpful tool for developing and debugging Python code. <a name="debugging"></a>
11+
12+
When you're writing a Python library, you probably want to try it out as you go.
13+
You could write a main method to check the functionality you're interested in,
14+
but then you have to change the main method with every new experiment you're
15+
interested in testing, and constantly updating the main method is a hassle.
16+
You could also open an IPython REPL and import your library there and test it,
17+
but then you have to deal with reloading your imports every time you change
18+
something.
19+
20+
If you simply call Fire in your library, then you can run all of it's
21+
functionality from the command line without having to keep making changes to
22+
a main method. And if you use the `--interactive` flag to enter an IPython REPL
23+
then you don't need to load the imports or create your variables; they'll
24+
already be ready for use as soon as you start the REPL.
25+
26+
27+
## Python Fire helps with exploring existing code or turning other people's code into a CLI. <a name="exploring"></a>
28+
29+
You can take an existing module, maybe even one that you don't have access to
30+
the source code for, and call `Fire` on it. This lets you easily see what
31+
functionality this code exposes, without you having to read through all the
32+
code.
33+
34+
This technique can be a very simple way to create very powerful CLIs. Call
35+
`Fire` on the difflib library and you get a powerful diffing tool. Call `Fire`
36+
on the Python Imaging Library (PIL) module and you get a powerful image
37+
manipulation command line tool, very similar in nature to ImageMagick.
38+
39+
The auto-generated help strings that Fire provides when you run a Fire CLI
40+
allow you to see all the functionality these modules provide in a concise
41+
manner.
42+
43+
44+
## Python Fire makes transitioning between Bash and Python easier. <a name="bash"></a>
45+
46+
Using Fire lets you call Python directly from Bash. So you can mix your Python
47+
functions with the unix tools you know and love, like `grep`, `xargs`, `wc`,
48+
etc.
49+
50+
Additionally since writing CLIs in Python requires only a single call to Fire,
51+
it is now easy to write even one-off scripts that would previously have been in
52+
Bash, in Python.
53+
54+
55+
## 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. <a name="repl"></a>
56+
57+
When you use the `--interactive` flag to enter an IPython REPL, it starts with
58+
variables and modules already defined for you. You don't need to waste time
59+
importing the modules you care about or defining the variables you're going to
60+
use, since Fire has already done so for you.

0 commit comments

Comments
 (0)
0