python-fire Documentation

Technical Documentation: google/python-fire

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Python Fire [](https://github.com/google/python-fire)

Python Fire is a library for automatically generating command line interfaces
(CLIs) from absolutely any Python object.

• Python Fire is a simple way to create a CLI in Python.
  [1]
• Python Fire is a helpful tool for developing and debugging Python code.
  [2]
• Python Fire helps with exploring existing code or turning other people's
  code into a CLI. [3]
• Python Fire makes transitioning between Bash and Python easier.
  [4]
• 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]

Installation Copy Chapter

To install Python Fire with pip, run: pip install fire

To install Python Fire with conda, run: conda install fire -c conda-forge

To install Python Fire from source, first clone the repository and then run:
python setup.py install

Basic Usage Copy Chapter

You can call Fire on any Python object:
functions, classes, modules, objects, dictionaries, lists, tuples, etc.
They all work!

Here's an example of calling Fire on a function.

import fire

def hello(name="World"):
  return "Hello %s!" % name

if __name__ == '__main__':
  fire.Fire(hello)

Then, from the command line, you can run:

python hello.py  # Hello World!
python hello.py --name=David  # Hello David!
python hello.py --help  # Shows usage information.

Here's an example of calling Fire on a class.

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:

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.

For additional examples, see The Python Fire Guide.

Why is it called Fire? Copy Chapter

When you call Fire, it fires off (executes) your command.

Where can I learn more? Copy Chapter

Please see The Python Fire Guide.

Reference Copy Chapter

Note that these flags are separated from the Fire command by an isolated --.

License Copy Chapter

Licensed under the
Apache 2.0 License.

Disclaimer Copy Chapter

This is not an official Google product.

Overview (`fire/console/README.md`) Copy Section

This is the console package from googlecloudsdk, as used by Python Fire.
Python Fire does not accept pull requests modifying the console package; rather,
changes to console should go through the upstream project googlecloudsdk.

Index (`docs/index.md`) Copy Section

Python Fire [](https://github.com/google/python-fire)

Python Fire is a library for automatically generating command line interfaces
(CLIs) from absolutely any Python object.

• Python Fire is a simple way to create a CLI in Python.
  [1]
• Python Fire is a helpful tool for developing and debugging Python code.
  [2]
• Python Fire helps with exploring existing code or turning other people's
  code into a CLI. [3]
• Python Fire makes transitioning between Bash and Python easier.
  [4]
• 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]

Installation Copy Chapter

To install Python Fire with pip, run: pip install fire

To install Python Fire with conda, run: conda install fire -c conda-forge

To install Python Fire from source, first clone the repository and then run:
python setup.py install

Basic Usage Copy Chapter

You can call Fire on any Python object:
functions, classes, modules, objects, dictionaries, lists, tuples, etc.
They all work!

Here's an example of calling Fire on a function.

import fire

def hello(name="World"):
  return "Hello %s!" % name

if __name__ == '__main__':
  fire.Fire(hello)

Then, from the command line, you can run:

python hello.py  # Hello World!
python hello.py --name=David  # Hello David!
python hello.py --help  # Shows usage information.

Here's an example of calling Fire on a class.

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:

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.

For additional examples, see The Python Fire Guide.

Why is it called Fire? Copy Chapter

When you call Fire, it fires off (executes) your command.

Where can I learn more? Copy Chapter

Please see The Python Fire Guide.

Reference Copy Chapter

Note that flags are separated from the Fire command by an isolated -- arg.
Help is an exception; the isolated -- is optional for getting help.

License Copy Chapter

Licensed under the
Apache 2.0 License.

Disclaimer Copy Chapter

This is not an official Google product.

Api (`docs/api.md`) Copy Section

Python Fire Quick Reference Copy Chapter

Note that flags are separated from the Fire command by an isolated -- arg.
Help is an exception; the isolated -- is optional for getting help.

Arguments for Calling fire.Fire() Copy Chapter

Using a Fire CLI without modifying any code Copy Chapter

You can use Python Fire on a module without modifying the code of the module.
The syntax for this is:

python -m fire <module> <arguments>

or

python -m fire <filepath> <arguments>

For example, python -m fire calendar -h will treat the built in calendar
module as a CLI and provide its help.

Benefits (`docs/benefits.md`) Copy Section

Benefits of Python Fire

Create CLIs in Python Copy Chapter

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.

Develop and debug Python code Copy Chapter

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.

Explore existing code; turn other people's code into a CLI Copy Chapter

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.

Transition between Bash and Python Copy Chapter

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.

Explore code in a Python REPL Copy Chapter

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.

Guide (`docs/guide.md`) Copy Section

The Python Fire Guide Copy Chapter

Introduction Copy Section

Welcome to the Python Fire guide! Python Fire is a Python library that will turn
any Python component into a command line interface with just a single call to
Fire.

Let's get started!

Installation Copy Section

To install Python Fire from pypi, run:

pip install fire

Alternatively, to install Python Fire from source, clone the source and run:

python setup.py install

Hello World Copy Section

Version 1: `fire.Fire()`

The easiest way to use Fire is to take any Python program, and then simply call
fire.Fire() at the end of the program. This will expose the full contents of
the program to the command line.

import fire

def hello(name):
  return f'Hello {name}!'

if __name__ == '__main__':
  fire.Fire()

Here's how we can run our program from the command line:

$ python example.py hello World
Hello World!

Version 2: `fire.Fire()`

Let's modify our program slightly to only expose the hello function to the
command line.

import fire

def hello(name):
  return f'Hello {name}!'

if __name__ == '__main__':
  fire.Fire(hello)

Here's how we can run this from the command line:

$ python example.py World
Hello World!

Notice we no longer have to specify to run the hello function, because we
called fire.Fire(hello).

Version 3: Using a main

We can alternatively write this program like this:

import fire

def hello(name):
  return f'Hello {name}!'

def main():
  fire.Fire(hello)

if __name__ == '__main__':
  main()

Or if we're using
entry points,
then simply this:

import fire

def hello(name):
  return f'Hello {name}!'

def main():
  fire.Fire(hello)

Version 4: Fire Without Code Changes

If you have a file example.py that doesn't even import fire:

def hello(name):
  return f'Hello {name}!'

Then you can use it with Fire like this:

$ python -m fire example hello --name=World
Hello World!

You can also specify the filepath of example.py rather than its module path,
like so:

$ python -m fire example.py hello --name=World
Hello World!

Exposing Multiple Commands Copy Section

In the previous example, we exposed a single function to the command line. Now
we'll look at ways of exposing multiple functions to the command line.

Version 1: `fire.Fire()`

The simplest way to expose multiple commands is to write multiple functions, and
then call Fire.

import fire

def add(x, y):
  return x + y

def multiply(x, y):
  return x * y

if __name__ == '__main__':
  fire.Fire()

We can use this like so:

$ python example.py add 10 20
30
$ python example.py multiply 10 20
200

You'll notice that Fire correctly parsed 10 and 20 as numbers, rather than
as strings. Read more about argument parsing here.

Version 2: `fire.Fire()`

In version 1 we exposed all the program's functionality to the command line. By
using a dict, we can selectively expose functions to the command line.

import fire

def add(x, y):
  return x + y

def multiply(x, y):
  return x * y

if __name__ == '__main__':
  fire.Fire({
      'add': add,
      'multiply': multiply,
  })

We can use this in the same way as before:

$ python example.py add 10 20
30
$ python example.py multiply 10 20
200

Version 3: `fire.Fire(