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

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

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