Initial commit for Python Fire.

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# How to contribute
+
+We'd love to accept your patches and contributions to this project. There are
+just a few small guidelines you need to follow.
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution,
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult [GitHub Help] for more
+information on using pull requests.
+
+[GitHub Help]: https://help.github.com/articles/about-pull-requests/

LICENSE

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

README.md

@@ -0,0 +1,79 @@
+# Python Fire
+_Python Fire is a library for creating command line interfaces (CLIs) from
+absolutely any Python object._
+
+- Python Fire is a simple way to create a CLI in Python. [[1]](doc/benefits.md#simple-cli)
+- Python Fire is a helpful tool for developing and debugging Python code. [[2]](doc/benefits.md#debugging)
+- Python Fire helps with exploring existing code or turning other people's code
+into a CLI. [[3]](doc/benefits.md#exploring)
+- Python Fire makes transitioning between Bash and Python easier. [[4]](doc/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]](doc/benefits.md#repl)
+
+## Installation
+
+`pip install fire`
+
+## Basic Usage
+
+You can call `Fire` on any Python object:<br>
+functions, classes, modules, objects, dictionaries, lists, tuples, etc.
+They all work!
+
+Here's a simple example.
+
+```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
+about Fire's other features, see the [Using a Fire CLI page](doc/using-cli.md).
+
+
+## Why is it called Fire?
+
+When you call `Fire`, it fires off (executes) your command.
+
+
+## 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.
+
+| Using a CLI    | Command                    | Notes
+| :------------- | :------------------------- | :---------
+| [Help](doc/using-cli.md#help-flag) | `command -- --help` |
+| [REPL](doc/using-cli.md#interactive-flag) | `command -- --interactive` | Enters interactive mode.
+| [Separator](doc/using-cli.md#separator-flag) | `command -- --separator=X` | This sets the separator to `X`. The default separator is `-`.
+| [Completion](doc/using-cli.md#completion-flag) | `command -- --completion` | Generate a completion script for the CLI.
+| [Trace](doc/using-cli.md#trace-flag) | `command -- --trace` | Gets a Fire trace for the command.
+| [Verbose](doc/using-cli.md#verbose-flag) | `command -- --verbose` |
+_Note that flags are separated from the Fire command by an isolated `--` arg._
+
+
+## Disclaimer
+
+This is not an official Google product.

doc/benefits.md

@@ -0,0 +1,60 @@
+# Benefits of Python Fire
+
+## Python Fire is a simple way to create a CLI in Python. <a name="simple-cli"></a>
+
+It's dead simple. Simply write the functionality you want exposed at the command
+line as a function / module / class, and then call Fire. With this addition of a
+single-line call to Fire, your CLI is ready to go.
+
+
+## Python Fire is a helpful tool for developing and debugging Python code. <a name="debugging"></a>
+
+When you're writing a Python library, you probably want to try it out as you go.
+You could write a main method to check the functionality you're interested in,
+but then you have to change the main method with every new experiment you're
+interested in testing, and constantly updating the main method is a hassle.
+You could also open an IPython REPL and import your library there and test it,
+but then you have to deal with reloading your imports every time you change
+something.
+
+If you simply call Fire in your library, then you can run all of it's
+functionality from the command line without having to keep making changes to
+a main method. And if you use the `--interactive` flag to enter an IPython REPL
+then you don't need to load the imports or create your variables; they'll
+already be ready for use as soon as you start the REPL.
+
+
+## Python Fire helps with exploring existing code or turning other people's code into a CLI. <a name="exploring"></a>
+
+You can take an existing module, maybe even one that you don't have access to
+the source code for, and call `Fire` on it. This lets you easily see what
+functionality this code exposes, without you having to read through all the
+code.
+
+This technique can be a very simple way to create very powerful CLIs. Call
+`Fire` on the difflib library and you get a powerful diffing tool. Call `Fire`
+on the Python Imaging Library (PIL) module and you get a powerful image
+manipulation command line tool, very similar in nature to ImageMagick.
+
+The auto-generated help strings that Fire provides when you run a Fire CLI
+allow you to see all the functionality these modules provide in a concise
+manner.
+
+
+## Python Fire makes transitioning between Bash and Python easier. <a name="bash"></a>
+
+Using Fire lets you call Python directly from Bash. So you can mix your Python
+functions with the unix tools you know and love, like `grep`, `xargs`, `wc`,
+etc.
+
+Additionally since writing CLIs in Python requires only a single call to Fire,
+it is now easy to write even one-off scripts that would previously have been in
+Bash, in Python.
+
+
+## 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>
+
+When you use the `--interactive` flag to enter an IPython REPL, it starts with
+variables and modules already defined for you. You don't need to waste time
+importing the modules you care about or defining the variables you're going to
+use, since Fire has already done so for you.