0
# Python Fire
1

2
A comprehensive Python library for automatically generating command line interfaces (CLIs) from any Python object. Fire enables developers to quickly create CLIs from existing Python code by calling Fire() on functions, classes, modules, dictionaries, lists, tuples, or any other Python objects without additional configuration.
3

4
## Package Information
5

6
- **Package Name**: fire
7
- **Language**: Python
8
- **Installation**: `pip install fire`
9
- **Repository**: https://github.com/google/python-fire
10
- **License**: Apache-2.0
11

12
## Core Imports
13

14
```python
15
import fire
16
```
17

18
For advanced functionality, import specific modules:
19

20
```python
21
from fire import decorators    # Custom argument parsing
22
from fire import completion    # Shell completion scripts
23
from fire import interact      # Interactive REPL mode
24
from fire import helptext      # Help text generation
25
from fire import trace         # Execution tracing
26
```
27

28
## Basic Usage
29

30
```python
31
import fire
32

33
def hello(name="World"):
34
    return f"Hello {name}!"
35

36
def add(x, y):
37
    return x + y
38

39
class Calculator:
40
    def multiply(self, x, y):
41
        return x * y
42

43
if __name__ == '__main__':
44
    # Convert function to CLI
45
    fire.Fire(hello)
46
    
47
    # Convert class to CLI
48
    # fire.Fire(Calculator)
49
    
50
    # Convert multiple functions to CLI
51
    # fire.Fire({
52
    #     'hello': hello,
53
    #     'add': add,
54
    #     'calc': Calculator
55
    # })
56
```
57

58
## Architecture
59

60
Python Fire uses a component traversal system that recursively processes command-line arguments:
61

62
- **Component**: The current Python object being processed (function, class, module, etc.)
63
- **Trace**: Execution history tracking each step of component navigation
64
- **Parser**: Argument parsing and value conversion system
65
- **Formatter**: Output formatting and help text generation
66

67
Fire transforms any Python object into a CLI by consuming command arguments to either access members, call functions, or instantiate classes, continuing until all arguments are processed.
68

69
## Capabilities
70

71
### Core CLI Generation
72

73
The main Fire function that transforms any Python object into a command-line interface. Supports functions, classes, modules, objects, dictionaries, lists, and tuples with automatic argument parsing and help generation.
74

75
```python { .api }
76
def Fire(component=None, command=None, name=None, serialize=None):
77
    """
78
    Main entry point for creating CLIs from Python objects.
79
    
80
    Parameters:
81
    - component: The Python object to convert to CLI
82
    - command: Optional command string/list to execute 
83
    - name: Optional name for the CLI command
84
    - serialize: Optional serialization function for output
85
    
86
    Returns:
87
    Result of executing the Fire command
88
    """
89
```
90

91
[Core CLI Generation](./core-cli.md)
92

93
### Argument Parsing Customization
94

95
Decorators and utilities for customizing how Fire parses command-line arguments, allowing fine-grained control over argument conversion and validation.
96

97
```python { .api }
98
def SetParseFn(fn, *arguments):
99
    """Decorator to set custom parsing function for arguments."""
100

101
def SetParseFns(*positional, **named):
102
    """Decorator to set multiple custom parsing functions."""
103
```
104

105
[Argument Parsing](./argument-parsing.md)
106

107
### Shell Completion
108

109
Functionality for generating shell completion scripts (Bash and Fish) that provide tab completion for Fire-generated CLIs.
110

111
```python { .api }
112
def Script(name, component, default_options=None, shell='bash'):
113
    """Generate shell completion script for a Fire CLI."""
114
```
115

116
[Shell Completion](./shell-completion.md)
117

118
### Interactive Mode
119

120
Interactive REPL functionality that allows users to drop into a Python shell with access to the CLI components and execution context.
121

122
```python { .api }
123
def Embed(variables, verbose=False):
124
    """Drop into Python REPL with variables available."""
125
```
126

127
[Interactive Mode](./interactive-mode.md)
128

129
### Help and Documentation
130

131
Utilities for generating help text and usage information for Fire CLIs, with support for docstring parsing and formatting.
132

133
```python { .api }
134
def HelpText(component, trace=None, verbose=False):
135
    """Generate help text for a component."""
136

137
def UsageText(component, trace=None, verbose=False):
138
    """Generate usage text for a component."""
139
```
140

141
[Help and Documentation](./help-documentation.md)
142

143
## Types
144

145
```python { .api }
146
class FireError(Exception):
147
    """Base exception for Fire-related errors."""
148

149
class FireExit(SystemExit):
150
    """System exit exception used by Fire."""
151

152
class FireTrace:
153
    """
154
    Represents execution trace of Fire commands.
155
    
156
    Tracks the sequence of steps taken during Fire execution, including
157
    component traversal, function calls, and property access.
158
    
159
    Attributes:
160
    - name: Optional name of the CLI command
161
    - separator: Separator used in command parsing (default: '-')
162
    - elements: List of FireTraceElement objects
163
    - verbose: Whether to include verbose information
164
    - show_help: Whether help was requested
165
    - show_trace: Whether trace output was requested
166
    """
167

168
class FireTraceElement:
169
    """
170
    Individual element in Fire execution trace.
171
    
172
    Represents a single step in the Fire execution process, such as
173
    instantiating a class, calling a function, or accessing a property.
174
    
175
    Attributes:
176
    - component: The component being processed
177
    - action: Type of action performed
178
    - target: Target of the action (if applicable)
179
    - args: Arguments used in the action
180
    - filename: Source file where action occurred
181
    - lineno: Line number where action occurred
182
    """
183
```