8000 Updates documentation and fixes example CLI main syntax. · SolarisYan/python-fire@48dd662 · GitHub
[go: up one dir, main page]
Skip to content

Commit 48dd662

Browse files
dbieberdbieber
committed
Updates documentation and fixes example CLI main syntax.
Copybara generated commit for Python Fire. PiperOrigin-RevId: 149033447 Change-Id: I0a9b2efbf6d8fb5436c3cca419d01bee376079be Reviewed-on: https://team-review.git.corp.google.com/63542 Reviewed-by: David Bieber <dbieber@google.com>
1 parent 421bbae commit 48dd662

File tree

8 files changed

+43
-41
lines changed

8 files changed

+43
-41
lines changed

‎doc/using-cli.md

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,25 @@
44

55
## Basic usage
66

7-
Every Fire command (even just running your Fire CLI with no arguments) always
8-
corresponds to a Python component.
7+
Every Fire command corresponds to a Python component.
98

10-
This can be any Python component, e.g. an object, a function, a class, or a
11-
module. To see what Python component a Fire command corresponds to, append
12-
`-- --help` to the command. For example, to see what Python component the
13-
command `widget whack` corresponds to, run `widget whack -- --help`. To see what
14-
Python component the command `widget whack 5` corresponds to, run
15-
`widget whack 5 -- --help`. To see what Python component the command `widget`
16-
corresponds to, run `widget -- --help`.
9+
The simplest Fire command consists of running your program with no additional
10+
arguments. This command corresponds to the Python component you called the
11+
`Fire` function on. If you did not supply an object in the call to `Fire`, then
12+
the context in which `Fire` was called will be used as the Python component.
1713

18-
When you first go to use a Fire CLI you're unfamiliar with, let's say it is
19-
called `widget`, start by seeing what Python component the command corresponds
20-
to without any arguments, by calling `widget -- --help`.
14+
You can append `-- --help` to any command to see what Python component it
15+
corresponds to, as well as the various ways in which you can extend the command.
16+
Flags are always separated from the Fire command by an isolated `--` in order
17+
to distinguish between flags and named arguments.
18+
19+
Given a Fire command that corresponds to a Python object, you can extend that
20+
command to access a member of that object, call it with arguments if it is a
21+
function, instantiate it if it is a class, or index into it if it is a list.
22+
23+
Read on to learn about how you can write a Fire command corresponding to
24+
whatever Python component you're looking for.
2125

22-
The following sections discuss how you can write a Fire command corresponding
23-
to whatever Python component you're looking for.
2426

2527
### Accessing members of an object
2628

@@ -37,14 +39,15 @@ named high_score, then you can add the argument 'high-score' to your command,
3739
and the resulting new command corresponds to the value of the high_score
3840
property.
3941

42+
4043
### Accessing members of a dict
4144

4245
If your command corresponds to a dict, you can extend your command by adding
4346
the name of one of the dict's keys as an argument.
4447

45-
For example, `widget function-that-returns-dict key` will correspond to the
46-
value of the item with key "key" in the dict returned by
47-
function_that_returns_dict.
48+
For example, `widget function-that-returns-dict key` will correspond to the
49+
value of the item with key `key` in the dict returned by
50+
`function_that_returns_dict`.
4851

4952

5053
### Accessing members of a list or tuple
@@ -77,18 +80,18 @@ You can force a function that takes a variable number of arguments to be
7780
evaluated by adding a separator (the default separator is the hyphen, "-"). This
7881
will prevent arguments to the right of the separator from being consumed for
7982
calling the function. This is useful if the function has arguments with default
80-
values, or if the function accepts *varargs, or if the function accepts
81-
**kwargs.
83+
values, or if the function accepts \*varargs, or if the function accepts
84+
\*\*kwargs.
8285

8386
See also the section on [Changing the Separator](#separator-flag).
8487

8588

8689
### Instantiating a class
8790

8891
If your command corresponds to a class, you can extend your command by adding
89-
the arguments of the class's __init__ function. Arguments can be specified
90-
positionally, or by name. To specify an argument by name, use flag syntax. See
91-
the section on [calling a function](#calling-a-function) for more details.
92+
the arguments of the class's \_\_init\_\_ function. Arguments must be specified
93+
by name, using the flags syntax. See the section on
94+
[calling a function](#calling-a-function) for more details.
9295

9396

9497
## Using Flags with Fire CLIs <a name="using-flags"></a>

‎examples/cipher/cipher.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ def _caesar_shift_char(n=0, char=' '):
5252
return chr((ord(char) - ord('a') + n) % 26 + ord('a'))
5353

5454

55-
def main()
55+
def main():
5656
fire.Fire(name='cipher')
5757

5858
if __name__ == '__main__':

‎examples/diff/diff.py

Lines changed: 1 addition & 1 deletion
< 9E7A td data-grid-cell-id="diff-d26c5e3a73314f65ea5b58ec64cb29a51c29efde60b7cc753e30a253e8a9ed15-97-97-0" data-selected="false" role="gridcell" style="background-color:var(--bgColor-default);text-align:center" tabindex="-1" valign="top" class="focusable-grid-cell diff-line-number position-relative diff-line-number-neutral left-side">97
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ def context_diff(self, lines=3):
9696
self._tofile, self.fromdate, self.todate, n=lines)
97

9898

99-
def main()
99+
def main():
100100
fire.Fire(DiffLibWrapper, name='diff')
101101

102102
if __name__ == '__main__':

‎examples/diff/difffull.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@
4444
import fire
4545

4646

47-
def main()
47+
def main():
4848
fire.Fire(difflib, name='difffull')
4949

5050
if __name__ == '__main__':

‎examples/widget/collector.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ def collect_widgets(self):
3131
return [widget.Widget() for _ in xrange(self.desired_widget_count)]
3232

3333

34-
def main()
34+
def main():
3535
fire.Fire(Collector(), name='collector')
3636

3737
if __name__ == '__main__':

‎examples/widget/widget.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ def bang(self, noise='bang'):
2828
return '{noise} bang!'.format(noise=noise)
2929

3030

31-
def main()
31+
def main():
3232
fire.Fire(Widget(), name='widget')
3333

3434
if __name__ == '__main__':

‎fire/interact.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -74,16 +74,16 @@ def _AvailableString(variables, verbose=False):
7474
).format(liststrs='\n'.join(liststrs))
7575

7676

77-
def _EmbedIPython(variables):
78-
"""Drops into an IPython REPL with variables available as local variables.
77+
def _EmbedIPython(variables, argv=None):
78+
"""Drops into an IPython REPL with variables available for use.
7979
8080
Args:
8181
variables: A dict of variables to make available. Keys are variable names.
8282
Values are variable values.
83+
argv: The argv to use for starting ipython. Defaults to an empty list.
8384
"""
84-
lcl = locals()
85-
lcl.update(**variables)
86-
IPython.embed()
85+
argv = argv or []
86+
IPython.start_ipython(argv=argv, user_ns=variables)
8787

8888

8989
def _EmbedCode(variables):

‎fire/interact_test.py

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,21 +24,20 @@
2424

2525
class InteractTest(unittest.TestCase):
2626

27-
@mock.patch('IPython.embed')
28-
def testInteract(self, mock_embed):
29-
self.assertFalse(mock_embed.called)
27+
@mock.patch('IPython.start_ipython')
28+
def testInteract(self, mock_ipython):
29+
self.assertFalse(mock_ipython.called)
3030
interact.Embed({})
31-
self.assertTrue(mock_embed.called)
31+
self.assertTrue(mock_ipython.called)
3232

33-
@mock.patch('IPython.embed')
34-
def testInteractVariables(self, mock_embed):
35-
self.assertFalse(mock_embed.called)
33+
@mock.patch('IPython.start_ipython')
34+
def testInteractVariables(self, mock_ipython):
35+
self.assertFalse(mock_ipython.called)
3636
interact.Embed({
3737
'count': 10,
3838
'mock': mock,
3939
})
40-
self.assertTrue(mock_embed.called)
41-
40+
self.assertTrue(mock_ipython.called)
4241

4342
if __name__ == '__main__':
4443
unittest.main()

0 commit comments

Comments
 (0)
0