pax_global_header 0000666 0000000 0000000 00000000064 13520106167 0014513 g ustar 00root root 0000000 0000000 52 comment=c1a7e2f21fb95e37d80d3e32c7ecbefa12140edf
python-fire-0.2.1/ 0000775 0000000 0000000 00000000000 13520106167 0013757 5 ustar 00root root 0000000 0000000 python-fire-0.2.1/.gitignore 0000664 0000000 0000000 00000002224 13520106167 0015747 0 ustar 00root root 0000000 0000000 # Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
env/
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*,cover
.hypothesis/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
target/
# Jupyter Notebook
.ipynb_checkpoints
# pyenv
.python-version
# celery beat schedule file
celerybeat-schedule
# SageMath parsed files
*.sage.py
# dotenv
.env
# virtualenv
.venv
venv/
ENV/
# Spyder project settings
.spyderproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# PyCharm IDE
.idea/
# Type-checking
.pytype/
python-fire-0.2.1/.travis.yml 0000664 0000000 0000000 00000001712 13520106167 0016071 0 ustar 00root root 0000000 0000000 language: python
python:
- "2.7"
- "3.4"
- "3.5"
- "3.6"
# Workaround for testing Python 3.7:
# https://github.com/travis-ci/travis-ci/issues/9815
matrix:
include:
- python: 3.7
dist: xenial
sudo: yes
before_install:
- pip install --upgrade setuptools pip
- pip install --upgrade pylint pytest pytest-pylint pytest-runner
install:
- pip install termcolor
- pip install hypothesis python-Levenshtein
- python setup.py develop
script:
- python -m pytest # Run the tests without IPython.
- pip install ipython
- python -m pytest # Now run the tests with IPython.
- pylint fire --ignore=test_components_py3.py,parser_fuzz_test.py,console
- pip install pytype
# Run type-checking, excluding files that define or use py3 features in py2.
- if [[ $TRAVIS_PYTHON_VERSION == 2.7 ]]; then
pytype -x
fire/fire_test.py
fire/inspectutils_test.py
fire/test_components_py3.py;
else
pytype; fi
python-fire-0.2.1/CONTRIBUTING.md 0000664 0000000 0000000 00000001730 13520106167 0016211 0 ustar 00root root 0000000 0000000 # 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 )`
Let's modify our program slightly to only expose the `hello` function to the
command line.
```python
import fire
def hello(name):
return 'Hello {name}!'.format(name=name)
if __name__ == '__main__':
fire.Fire(hello)
```
Here's how we can run this from the command line:
```bash
$ 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:
```python
import fire
def hello(name):
return 'Hello {name}!'.format(name=name)
def main():
fire.Fire(hello)
if __name__ == '__main__':
main()
```
Or if we're using
[entry points](https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points),
then simply this:
```python
import fire
def hello(name):
return 'Hello {name}!'.format(name=name)
def main():
fire.Fire(hello)
```
### Exposing Multiple Commands
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.
```python
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:
```bash
$ 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](#argument-parsing).
##### 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.
```python
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:
```bash
$ python example.py add 10 20
30
$ python example.py multiply 10 20
200
```
##### Version 3: `fire.Fire()`
Fire also works on objects, as in this variant. This is a good way to expose
multiple commands.
```python
import fire
class Calculator(object):
def add(self, x, y):
return x + y
def multiply(self, x, y):
return x * y
if __name__ == '__main__':
calculator = Calculator()
fire.Fire(calculator)
```
We can use this in the same way as before:
```bash
$ python example.py add 10 20
30
$ python example.py multiply 10 20
200
```
##### Version 4: `fire.Fire()`
Fire also works on classes. This is another good way to expose multiple
commands.
```python
import fire
class Calculator(object):
def add(self, x, y):
return x + y
def multiply(self, x, y):
return x * y
if __name__ == '__main__':
fire.Fire(Calculator)
```
We can use this in the same way as before:
```bash
$ python example.py add 10 20
30
$ python example.py multiply 10 20
200
```
Why might you prefer a class over an object? One reason is that you can pass
arguments for constructing the class too, as in this broken calculator example.
```python
import fire
class BrokenCalculator(object):
def __init__(self, offset=1):
self._offset = offset
def add(self, x, y):
return x + y + self._offset
def multiply(self, x, y):
return x * y + self._offset
if __name__ == '__main__':
fire.Fire(BrokenCalculator)
```
When you use a broken calculator, you get wrong answers:
```bash
$ python example.py add 10 20
31
$ python example.py multiply 10 20
201
```
But you can always fix it:
```bash
$ python example.py add 10 20 --offset=0
30
$ python example.py multiply 10 20 --offset=0
200
```
Unlike calling ordinary functions, which can be done both with positional
arguments and named arguments (--flag syntax), arguments to \_\_init\_\_
functions must be passed with the --flag syntax. See the section on
[calling functions](#calling-functions) for more.
### Grouping Commands
Here's an example of how you might make a command line interface with grouped
commands.
```python
class IngestionStage(object):
def run(self):
return 'Ingesting! Nom nom nom...'
class DigestionStage(object):
def run(self, volume=1):
return ' '.join(['Burp!'] * volume)
def status(self):
return 'Satiated.'
class Pipeline(object):
def __init__(self):
self.ingestion = IngestionStage()
self.digestion = DigestionStage()
def run(self):
self.ingestion.run()
self.digestion.run()
if __name__ == '__main__':
fire.Fire(Pipeline)
```
Here's how this looks at the command line:
```bash
$ python example.py run
Ingesting! Nom nom nom...
Burp!
$ python example.py ingestion run
Ingesting! Nom nom nom...
$ python example.py digestion run
Burp!
$ python example.py digestion status
Satiated.
```
You can nest your commands in arbitrarily complex ways, if you're feeling grumpy
or adventurous.
### Accessing Properties
In the examples we've looked at so far, our invocations of `python example.py`
have all run some function from the example program. In this example, we simply
access a property.
```python
from airports import airports
import fire
class Airport(object):
def __init__(self, code):
self.code = code
self.name = dict(airports).get(self.code)
self.city = self.name.split(',')[0] if self.name else None
if __name__ == '__main__':
fire.Fire(Airport)
```
Now we can use this program to learn about airport codes!
```bash
$ python example.py --code=JFK code
JFK
$ python example.py --code=SJC name
San Jose-Sunnyvale-Santa Clara, CA - Norman Y. Mineta San Jose International (SJC)
$ python example.py --code=ALB city
Albany-Schenectady-Troy
```
By the way, you can find this
[airports module here](https://github.com/trendct-data/airports.py).
### Chaining Function Calls
When you run a Fire CLI, you can take all the same actions on the _result_ of
the call to Fire that you can take on the original object passed in.
For example, we can use our Airport CLI from the previous example like this:
```bash
$ python example.py --code=ALB city upper
ALBANY-SCHENECTADY-TROY
```
This works since `upper` is a method on all strings.
So, if you want to set up your functions to chain nicely, all you have to do is
have a class whose methods return self. Here's an example.
```python
import fire
class BinaryCanvas(object):
"""A canvas with which to make binary art, one bit at a time."""
def __init__(self, size=10):
self.pixels = [[0] * size for _ in range(size)]
self._size = size
self._row = 0 # The row of the cursor.
self._col = 0 # The column of the cursor.
def __str__(self):
return '\n'.join(' '.join(str(pixel) for pixel in row) for row in self.pixels)
def show(self):
print(self)
return self
def move(self, row, col):
self._row = row % self._size
self._col = col % self._size
return self
def on(self):
return self.set(1)
def off(self):
return self.set(0)
def set(self, value):
self.pixels[self._row][self._col] = value
return self
if __name__ == '__main__':
fire.Fire(BinaryCanvas)
```
Now we can draw stuff :).
```bash
$ python example.py move 3 3 on move 3 6 on move 6 3 on move 6 6 on move 7 4 on move 7 5 on
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 1 0 0 1 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 1 0 0 1 0 0 0
0 0 0 0 1 1 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
```
It's supposed to be a smiley face.
### Custom Serialization
You'll notice in the BinaryCanvas example, the canvas with the smiley face was
printed to the screen. You can determine how a component will be serialized by
defining its `__str__` method.
If a custom `__str__` method is present on the final component, the object is
serialized and printed. If there's no custom `__str__` method, then the help
screen for the object is shown instead.
### Can we make an even simpler example than Hello World?
Yes, this program is even simpler than our original Hello World example.
```python
import fire
english = 'Hello World'
spanish = 'Hola Mundo'
fire.Fire()
```
You can use it like this:
```bash
$ python example.py english
Hello World
$ python example.py spanish
Hola Mundo
```
### Calling Functions
Arguments to a constructor are passed by name using flag syntax `--name=value`.
For example, consider this simple class:
```python
import fire
class Building(object):
def __init__(self, name, stories=1):
self.name = name
self.stories = stories
def climb_stairs(self, stairs_per_story=10):
for story in range(self.stories):
for stair in range(1, stairs_per_story):
yield stair
yield 'Phew!'
yield 'Done!'
if __name__ == '__main__':
fire.Fire(Building)
```
We can instantiate it as follows: `python example.py --name="Sherrerd Hall"`
Arguments to other functions may be passed positionally or by name using flag
syntax.
To instantiate a `Building` and then run the `climb_stairs` function, the
following commands are all valid:
```bash
$ python example.py --name="Sherrerd Hall" --stories=3 climb_stairs 10
$ python example.py --name="Sherrerd Hall" climb_stairs --stairs_per_story=10
$ python example.py --name="Sherrerd Hall" climb_stairs --stairs-per-story 10
$ python example.py climb-stairs --stairs-per-story 10 --name="Sherrerd Hall"
```
You'll notice that hyphens and underscores (`-` and `_`) are interchangeable in
member names and flag names.
You'll also notice that the constructor's arguments can come after the
function's arguments or before the function.
You'll also notice that the equal sign between the flag name and its value is
optional.
##### Functions with `*varargs` and `**kwargs`
Fire supports functions that take \*varargs or \*\*kwargs. Here's an example:
```python
import fire
def order_by_length(*items):
"""Orders items by length, breaking ties alphabetically."""
sorted_items = sorted(items, key=lambda item: (len(str(item)), str(item)))
return ' '.join(sorted_items)
if __name__ == '__main__':
fire.Fire(order_by_length)
```
To use it, we run:
```bash
$ python example.py dog cat elephant
cat dog elephant
```
You can use a separator to indicate that you're done providing arguments to a
function. All arguments after the separator will be used to process the result
of the function, rather than being passed to the function itself. The default
separator is the hyphen `-`.
Here's an example where we use a separator.
```bash
$ python example.py dog cat elephant - upper
CAT DOG ELEPHANT
```
Without the separator, upper would have been treated as another argument.
```bash
$ python example.py dog cat elephant upper
cat dog upper elephant
```
You can change the separator with the `--separator` flag. Flags are always
separated from your Fire command by an isolated `--`. Here's an example where we
change the separator.
```bash
$ python example.py dog cat elephant X upper -- --separator=X
CAT DOG ELEPHANT
```
Separators can be useful when a function accepts \*varargs, \*\*kwargs, or
default values that you don't want to specify. It is also important to remember
to change the separator if you want to pass `-` as an argument.
### Argument Parsing
The types of the arguments are determined by their values, rather than by the
function signature where they're used. You can pass any Python literal from the
command line: numbers, strings, tuples, lists, dictionaries, (sets are only
supported in some versions of Python). You can also nest the collections
arbitrarily as long as they only contain literals.
To demonstrate this, we'll make a small example program that tells us the type
of any argument we give it:
```python
import fire
fire.Fire(lambda obj: type(obj).__name__)
```
And we'll use it like so:
```bash
$ python example.py 10
int
$ python example.py 10.0
float
$ python example.py hello
str
$ python example.py '(1,2)'
tuple
$ python example.py [1,2]
list
$ python example.py True
bool
$ python example.py {name: David}
dict
```
You'll notice in that last example that bare-words are automatically replaced
with strings.
Be careful with your quotes! If you want to pass the string `"10"`, rather than
the int `10`, you'll need to either escape or quote your quotes. Otherwise Bash
will eat your quotes and pass an unquoted `10` to your Python program, where
Fire will interpret it as a number.
```bash
$ python example.py 10
int
$ python example.py "10"
int
$ python example.py '"10"'
str
$ python example.py "'10'"
str
$ python example.py \"10\"
str
```
Be careful with your quotes! Remember that Bash processes your arguments first,
and then Fire parses the result of that.
If you wanted to pass the dict `{"name": "David Bieber"}` to your program, you
might try this:
```bash
$ python example.py '{"name": "David Bieber"}' # Good! Do this.
dict
$ python example.py {"name":'"David Bieber"'} # Okay.
dict
$ python example.py {"name":"David Bieber"} # Wrong. This is parsed as a string.
str
$ python example.py {"name": "David Bieber"} # Wrong. This isn't even treated as a single argument.
$ python example.py '{"name": "Justin Bieber"}' # Wrong. This is not the Bieber you're looking for. (The syntax is fine though :))
dict
```
##### Boolean Arguments
The tokens `True` and `False` are parsed as boolean values.
You may also specify booleans via flag syntax `--name` and `--noname`, which set
`name` to `True` and `False` respectively.
Continuing the previous example, we could run any of the following:
```bash
$ python example.py --obj=True
bool
$ python example.py --obj=False
bool
$ python example.py --obj
bool
$ python example.py --noobj
bool
```
Be careful with boolean flags! If a token other than another flag immediately
follows a flag that's supposed to be a boolean, the flag will take on the value
of the token rather than the boolean value. You can resolve this: by putting a
separator after your last flag, by explicitly stating the value of the boolean
flag (as in `--obj=True`), or by making sure there's another flag after any
boolean flag argument.
### Using Fire Flags
Fire CLIs all come with a number of flags. These flags should be separated from
the Fire command by an isolated `--`. If there is at least one isolated `--`
argument, then arguments after the final isolated `--` are treated as flags,
whereas all arguments before the final isolated `--` are considered part of the
Fire command.
One useful flag is the `--interactive` flag. Use the `--interactive` flag on any
CLI to enter a Python REPL with all the modules and variables used in the
context where `Fire` was called already available to you for use. Other useful
variables, such as the result of the Fire command will also be available. Use
this feature like this: `python example.py -- --interactive`.
You can add the help flag to any command to see help and usage information. Fire
incorporates your docstrings into the help and usage information that it
generates. Fire will try to provide help even if you omit the isolated `--`
separating the flags from the Fire command, but may not always be able to, since
`help` is a valid argument name. Use this feature like this:
`python example.py -- --help`.
The complete set of flags available is shown below, in the reference section.
### Reference
| Setup | Command | Notes
| :------ | :------------------ | :---------
| install | `pip install fire` |
##### Creating a CLI
| 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.
##### Flags
| Using a CLI | Command | Notes
| :------------- | :------------------------- | :---------
| [Help](using-cli.md#help-flag) | `command -- --help` | Show help and usage information for the command.
| [REPL](using-cli.md#interactive-flag) | `command -- --interactive` | Enter interactive mode.
| [Separator](using-cli.md#separator-flag) | `command -- --separator=X` | This sets the separator to `X`. The default separator is `-`.
| [Completion](using-cli.md#completion-flag) | `command -- --completion [shell]` | Generate a completion script for the CLI.
| [Trace](using-cli.md#trace-flag) | `command -- --trace` | Gets a Fire trace for the command.
| [Verbose](using-cli.md#verbose-flag) | `command -- --verbose` | Include private members in the output.
_Note that flags are separated from the Fire command by an isolated `--` arg._
### Disclaimer
Python Fire is not an official Google product.
python-fire-0.2.1/docs/index.md 0000664 0000000 0000000 00000007535 13520106167 0016352 0 ustar 00root root 0000000 0000000 # 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]](benefits.md#simple-cli)
- Python Fire is a helpful tool for developing and debugging Python code. [[2]](benefits.md#debugging)
- Python Fire helps with exploring existing code or turning other people's code
into a CLI. [[3]](benefits.md#exploring)
- Python Fire makes transitioning between Bash and Python easier. [[4]](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]](benefits.md#repl)
## Installation
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
You can call `Fire` on any Python object: for function keys, otherwise a
character.
"""
return self._get_raw_key[0]()
def GetTermIdentifier(self):
"""Returns the TERM envrionment variable for the console.
Returns:
str: A str that describes the console's text capabilities
"""
return self._term
def GetTermSize(self):
"""Returns the terminal (x, y) dimensions in characters.
Returns:
(x, y): A tuple of the terminal x and y dimensions.
"""
return self._term_size
def DisplayWidth(self, buf):
"""Returns the display width of buf, handling unicode and ANSI controls.
Args:
buf: The string to count from.
Returns:
The display width of buf, handling unicode and ANSI controls.
"""
if not isinstance(buf, six.string_types):
# Handle non-string objects like Colorizer().
return len(buf)
cached = self._display_width_cache.get(buf, None)
if cached is not None:
return cached
width = 0
max_width = 0
i = 0
while i < len(buf):
if self._csi and buf[i:].startswith(self._csi):
i += self.GetControlSequenceLen(buf[i:])
elif buf[i] == '\n':
# A newline incidates the start of a new line.
# Newline characters have 0 width.
max_width = max(width, max_width)
width = 0
i += 1
else:
width += GetCharacterDisplayWidth(buf[i])
i += 1
max_width = max(width, max_width)
self._display_width_cache[buf] = max_width
return max_width
def SplitIntoNormalAndControl(self, buf):
"""Returns a list of (normal_string, control_sequence) tuples from buf.
Args:
buf: The input string containing one or more control sequences
interspersed with normal strings.
Returns:
A list of (normal_string, control_sequence) tuples.
"""
if not self._csi or not buf:
return [(buf, '')]
seq = []
i = 0
while i < len(buf):
c = buf.find(self._csi, i)
if c < 0:
seq.append((buf[i:], ''))
break
normal = buf[i:c]
i = c + self.GetControlSequenceLen(buf[c:])
seq.append((normal, buf[c:i]))
return seq
def SplitLine(self, line, width):
"""Splits line into width length chunks.
Args:
line: The line to split.
width: The width of each chunk except the last which could be smaller than
width.
Returns:
A list of chunks, all but the last with display width == width.
"""
lines = []
chunk = ''
w = 0
keep = False
for normal, control in self.SplitIntoNormalAndControl(line):
keep = True
while True:
n = width - w
w += len(normal)
if w <= width:
break
lines.append(chunk + normal[:n])
chunk = ''
keep = False
w = 0
normal = normal[n:]
chunk += normal + control
if chunk or keep:
lines.append(chunk)
return lines
def SupportsAnsi(self):
return (self._encoding != 'ascii' and
('screen' in self._term or 'xterm' in self._term))
class Colorizer(object):
"""Resource string colorizer.
Attributes:
_con: ConsoleAttr object.
_color: Color name.
_string: The string to colorize.
_justify: The justification function, no justification if None. For example,
justify=lambda s: s.center(10)
"""
def __init__(self, string, color, justify=None):
"""Constructor.
Args:
string: The string to colorize.
color: Color name used to index ConsoleAttr._ANSI_COLOR.
justify: The justification function, no justification if None. For
example, justify=lambda s: s.center(10)
"""
self._con = GetConsoleAttr()
self._color = color
self._string = string
self._justify = justify
def __eq__(self, other):
return self._string == six.text_type(other)
def __ne__(self, other):
return not self == other
def __gt__(self, other):
return self._string > six.text_type(other)
def __lt__(self, other):
return self._string < six.text_type(other)
def __ge__(self, other):
return not self < other
def __le__(self, other):
return not self > other
def __len__(self):
return self._con.DisplayWidth(self._string)
def __str__(self):
return self._string
def Render(self, stream, justify=None):
"""Renders the string as self._color on the console.
Args:
stream: The stream to render the string to. The stream given here *must*
have the same encoding as sys.stdout for this to work properly.
justify: The justification function, self._justify if None.
"""
stream.write(
self._con.Colorize(self._string, self._color, justify or self._justify))
def GetConsoleAttr(encoding=None, reset=False):
"""Gets the console attribute state.
If this is the first call or reset is True or encoding is not None and does
not match the current encoding or out is not None and does not match the
current out then the state is (re)initialized. Otherwise the current state
is returned.
This call associates the out file stream with the console. All console related
output should go to the same stream.
Args:
encoding: Encoding override.
ascii -- ASCII. This is the default.
utf8 -- UTF-8 unicode.
win -- Windows code page 437.
reset: Force re-initialization if True.
Returns:
The global ConsoleAttr state object.
"""
attr = ConsoleAttr._CONSOLE_ATTR_STATE # pylint: disable=protected-access
if not reset:
if not attr:
reset = True
elif encoding and encoding != attr.GetEncoding():
reset = True
if reset:
attr = ConsoleAttr(encoding=encoding)
ConsoleAttr._CONSOLE_ATTR_STATE = attr # pylint: disable=protected-access
return attr
def ResetConsoleAttr(encoding=None):
"""Resets the console attribute state to the console default.
Args:
encoding: Reset to this encoding instead of the default.
ascii -- ASCII. This is the default.
utf8 -- UTF-8 unicode.
win -- Windows code page 437.
Returns:
The global ConsoleAttr state object.
"""
return GetConsoleAttr(encoding=encoding, reset=True)
def GetCharacterDisplayWidth(char):
"""Returns the monospaced terminal display width of char.
Assumptions:
- monospaced display
- ambiguous or unknown chars default to width 1
- ASCII control char width is 1 => don't use this for control chars
Args:
char: The character to determine the display width of.
Returns:
The monospaced terminal display width of char: either 0, 1, or 2.
"""
if not isinstance(char, six.text_type):
# Non-unicode chars have width 1. Don't use this function on control chars.
return 1
# Normalize to avoid special cases.
char = unicodedata.normalize('NFC', char)
if unicodedata.combining(char) != 0:
# Modifies the previous character and does not move the cursor.
return 0
elif unicodedata.category(char) == 'Cf':
# Unprintable formatting char.
return 0
elif unicodedata.east_asian_width(char) in 'FW':
# Fullwidth or Wide chars take 2 character positions.
return 2
else:
# Don't use this function on control chars.
return 1
def SafeText(data, encoding=None, escape=True):
br"""Converts the data to a text string compatible with the given encoding.
This works the same way as Decode() below except it guarantees that any
characters in the resulting text string can be re-encoded using the given
encoding (or GetConsoleAttr().GetEncoding() if None is given). This means
that the string will be safe to print to sys.stdout (for example) without
getting codec exceptions if the user's terminal doesn't support the encoding
used by the source of the text.
Args:
data: Any bytes, string, or object that has str() or unicode() methods.
encoding: The encoding name to ensure compatibility with. Defaults to
GetConsoleAttr().GetEncoding().
escape: Replace unencodable characters with a \uXXXX or \xXX equivalent if
True. Otherwise replace unencodable characters with an appropriate unknown
character, '?' for ASCII, and the unicode unknown replacement character
\uFFFE for unicode.
Returns:
A text string representation of the data, but modified to remove any
characters that would result in an encoding exception with the target
encoding. In the worst case, with escape=False, it will contain only ?
characters.
"""
if data is None:
return 'None'
encoding = encoding or GetConsoleAttr().GetEncoding()
string = encoding_util.Decode(data, encoding=encoding)
try:
# No change needed if the string encodes to the output encoding.
string.encode(encoding)
return string
except UnicodeError:
# The string does not encode to the output encoding. Encode it with error
# handling then convert it back into a text string (which will be
# guaranteed to only contain characters that can be encoded later.
return (string
.encode(encoding, 'backslashreplace' if escape else 'replace')
.decode(encoding))
def EncodeToBytes(data):
r"""Encode data to bytes.
The primary use case is for base64/mime style 7-bit ascii encoding where the
encoder input must be bytes. "safe" means that the conversion always returns
bytes and will not raise codec exceptions.
If data is text then an 8-bit ascii encoding is attempted, then the console
encoding, and finally utf-8.
Args:
data: Any bytes, string, or object that has str() or unicode() methods.
Returns:
A bytes string representation of the data.
"""
if data is None:
return b''
if isinstance(data, bytes):
# Already bytes - our work is done.
return data
# Coerce to text that will be converted to bytes.
s = six.text_type(data)
try:
# Assume the text can be directly converted to bytes (8-bit ascii).
return s.encode('iso-8859-1')
except UnicodeEncodeError:
pass
try:
# Try the output encoding.
return s.encode(GetConsoleAttr().GetEncoding())
except UnicodeEncodeError:
pass
# Punt to utf-8.
return s.encode('utf-8')
def Decode(data, encoding=None):
"""Converts the given string, bytes, or object to a text string.
Args:
data: Any bytes, string, or object that has str() or unicode() methods.
encoding: A suggesting encoding used to decode. If this encoding doesn't
work, other defaults are tried. Defaults to
GetConsoleAttr().GetEncoding().
Returns:
A text string representation of the data.
"""
encoding = encoding or GetConsoleAttr().GetEncoding()
return encoding_util.Decode(data, encoding=encoding)
python-fire-0.2.1/fire/console/console_attr_os.py 0000664 0000000 0000000 00000016615 13520106167 0022126 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*- #
# Copyright 2015 Google LLC. 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.
"""OS specific console_attr helper functions."""
# This file contains platform specific code which is not currently handled
# by pytype.
# pytype: skip-file
from __future__ import absolute_import
from __future__ import division
from __future__ import unicode_literals
import os
import sys
from fire.console import encoding
def GetTermSize():
"""Gets the terminal x and y dimensions in characters.
_GetTermSize*() helper functions taken from:
http://stackoverflow.com/questions/263890/
Returns:
(columns, lines): A tuple containing the terminal x and y dimensions.
"""
xy = None
# Believe the first helper that doesn't bail.
for get_terminal_size in (_GetTermSizePosix,
_GetTermSizeWindows,
_GetTermSizeEnvironment,
_GetTermSizeTput):
try:
xy = get_terminal_size()
if xy:
break
except: # pylint: disable=bare-except
pass
return xy or (80, 24)
def _GetTermSizePosix():
"""Returns the Posix terminal x and y dimensions."""
# pylint: disable=g-import-not-at-top
import fcntl
# pylint: disable=g-import-not-at-top
import struct
# pylint: disable=g-import-not-at-top
import termios
def _GetXY(fd):
"""Returns the terminal (x,y) size for fd.
Args:
fd: The terminal file descriptor.
Returns:
The terminal (x,y) size for fd or None on error.
"""
try:
# This magic incantation converts a struct from ioctl(2) containing two
# binary shorts to a (rows, columns) int tuple.
rc = struct.unpack(b'hh', fcntl.ioctl(fd, termios.TIOCGWINSZ, 'junk'))
return (rc[1], rc[0]) if rc else None
except: # pylint: disable=bare-except
return None
xy = _GetXY(0) or _GetXY(1) or _GetXY(2)
if not xy:
fd = None
try:
fd = os.open(os.ctermid(), os.O_RDONLY)
xy = _GetXY(fd)
except: # pylint: disable=bare-except
xy = None
finally:
if fd is not None:
os.close(fd)
return xy
def _GetTermSizeWindows():
"""Returns the Windows terminal x and y dimensions."""
# pylint:disable=g-import-not-at-top
import struct
# pylint: disable=g-import-not-at-top
from ctypes import create_string_buffer
# pylint:disable=g-import-not-at-top
from ctypes import windll
# stdin handle is -10
# stdout handle is -11
# stderr handle is -12
h = windll.kernel32.GetStdHandle(-12)
csbi = create_string_buffer(22)
if not windll.kernel32.GetConsoleScreenBufferInfo(h, csbi):
return None
(unused_bufx, unused_bufy, unused_curx, unused_cury, unused_wattr,
left, top, right, bottom,
unused_maxx, unused_maxy) = struct.unpack(b'hhhhHhhhhhh', csbi.raw)
x = right - left + 1
y = bottom - top + 1
return (x, y)
def _GetTermSizeEnvironment():
"""Returns the terminal x and y dimensions from the environment."""
return (int(os.environ['COLUMNS']), int(os.environ['LINES']))
def _GetTermSizeTput():
"""Returns the terminal x and y dimemsions from tput(1)."""
import subprocess # pylint: disable=g-import-not-at-top
output = encoding.Decode(subprocess.check_output(['tput', 'cols'],
stderr=subprocess.STDOUT))
cols = int(output)
output = encoding.Decode(subprocess.check_output(['tput', 'lines'],
stderr=subprocess.STDOUT))
rows = int(output)
return (cols, rows)
_ANSI_CSI = '\x1b' # ANSI control sequence indicator (ESC)
_CONTROL_D = '\x04' # unix EOF (^D)
_CONTROL_Z = '\x1a' # Windows EOF (^Z)
_WINDOWS_CSI_1 = '\x00' # Windows control sequence indicator #1
_WINDOWS_CSI_2 = '\xe0' # Windows control sequence indicator #2
def GetRawKeyFunction():
"""Returns a function that reads one keypress from stdin with no echo.
Returns:
A function that reads one keypress from stdin with no echo or a function
that always returns None if stdin does not support it.
"""
# Believe the first helper that doesn't bail.
for get_raw_key_function in (_GetRawKeyFunctionPosix,
_GetRawKeyFunctionWindows):
try:
return get_raw_key_function()
except: # pylint: disable=bare-except
pass
return lambda: None
def _GetRawKeyFunctionPosix():
"""_GetRawKeyFunction helper using Posix APIs."""
# pylint: disable=g-import-not-at-top
import tty
# pylint: disable=g-import-not-at-top
import termios
def _GetRawKeyPosix():
"""Reads and returns one keypress from stdin, no echo, using Posix APIs.
Returns:
The key name, None for EOF, <*> for function keys, otherwise a
character.
"""
ansi_to_key = {
'A': '',
'B': '',
'D': '',
'C': '',
'5': '',
'6': '',
'H': '',
'F': '',
'M': '',
'S': '',
'T': '',
}
# Flush pending output. sys.stdin.read() would do this, but it's explicitly
# bypassed in _GetKeyChar().
sys.stdout.flush()
fd = sys.stdin.fileno()
def _GetKeyChar():
return encoding.Decode(os.read(fd, 1))
old_settings = termios.tcgetattr(fd)
try:
tty.setraw(fd)
c = _GetKeyChar()
if c == _ANSI_CSI:
c = _GetKeyChar()
while True:
if c == _ANSI_CSI:
return c
if c.isalpha():
break
prev_c = c
c = _GetKeyChar()
if c == '~':
c = prev_c
break
return ansi_to_key.get(c, '')
except: # pylint:disable=bare-except
c = None
finally:
termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
return None if c in (_CONTROL_D, _CONTROL_Z) else c
return _GetRawKeyPosix
def _GetRawKeyFunctionWindows():
"""_GetRawKeyFunction helper using Windows APIs."""
# pylint: disable=g-import-not-at-top
import msvcrt
def _GetRawKeyWindows():
"""Reads and returns one keypress from stdin, no echo, using Windows APIs.
Returns:
The key name, None for EOF, <*> for function keys, otherwise a
character.
"""
windows_to_key = {
'H': '',
'P': '',
'K': '',
'M': '',
'I': '',
'Q': '',
'G': '',
'O': '',
}
# Flush pending output. sys.stdin.read() would do this it's explicitly
# bypassed in _GetKeyChar().
sys.stdout.flush()
def _GetKeyChar():
return encoding.Decode(msvcrt.getch())
c = _GetKeyChar()
# Special function key is a two character sequence; return the second char.
if c in (_WINDOWS_CSI_1, _WINDOWS_CSI_2):
return windows_to_key.get(_GetKeyChar(), '')
return None if c in (_CONTROL_D, _CONTROL_Z) else c
return _GetRawKeyWindows
python-fire-0.2.1/fire/console/console_io.py 0000664 0000000 0000000 00000007561 13520106167 0021062 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*- #
# Copyright 2013 Google LLC. 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.
"""General console printing utilities used by the Cloud SDK."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import os
import subprocess
import sys
from fire.console import console_attr
from fire.console import console_pager
from fire.console import encoding
from fire.console import files
def IsInteractive(output=False, error=False, heuristic=False):
"""Determines if the current terminal session is interactive.
sys.stdin must be a terminal input stream.
Args:
output: If True then sys.stdout must also be a terminal output stream.
error: If True then sys.stderr must also be a terminal output stream.
heuristic: If True then we also do some additional heuristics to check if
we are in an interactive context. Checking home path for example.
Returns:
True if the current terminal session is interactive.
"""
if not sys.stdin.isatty():
return False
if output and not sys.stdout.isatty():
return False
if error and not sys.stderr.isatty():
return False
if heuristic:
# Check the home path. Most startup scripts for example are executed by
# users that don't have a home path set. Home is OS dependent though, so
# check everything.
# *NIX OS usually sets the HOME env variable. It is usually '/home/user',
# but can also be '/root'. If it's just '/' we are most likely in an init
# script.
# Windows usually sets HOMEDRIVE and HOMEPATH. If they don't exist we are
# probably being run from a task scheduler context. HOMEPATH can be '\'
# when a user has a network mapped home directory.
# Cygwin has it all! Both Windows and Linux. Checking both is perfect.
home = os.getenv('HOME')
homepath = os.getenv('HOMEPATH')
if not homepath and (not home or home == '/'):
return False
return True
def More(contents, out, prompt=None, check_pager=True):
"""Run a user specified pager or fall back to the internal pager.
Args:
contents: The entire contents of the text lines to page.
out: The output stream.
prompt: The page break prompt.
check_pager: Checks the PAGER env var and uses it if True.
"""
if not IsInteractive(output=True):
out.write(contents)
return
if check_pager:
pager = encoding.GetEncodedValue(os.environ, 'PAGER', None)
if pager == '-':
# Use the fallback Pager.
pager = None
elif not pager:
# Search for a pager that handles ANSI escapes.
for command in ('less', 'pager'):
if files.FindExecutableOnPath(command):
pager = command
break
if pager:
# If the pager is less(1) then instruct it to display raw ANSI escape
# sequences to enable colors and font embellishments.
less_orig = encoding.GetEncodedValue(os.environ, 'LESS', None)
less = '-R' + (less_orig or '')
encoding.SetEncodedValue(os.environ, 'LESS', less)
p = subprocess.Popen(pager, stdin=subprocess.PIPE, shell=True)
enc = console_attr.GetConsoleAttr().GetEncoding()
p.communicate(input=contents.encode(enc))
p.wait()
if less_orig is None:
encoding.SetEncodedValue(os.environ, 'LESS', None)
return
# Fall back to the internal pager.
console_pager.Pager(contents, out, prompt).Run()
python-fire-0.2.1/fire/console/console_pager.py 0000664 0000000 0000000 00000022532 13520106167 0021544 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*- #
# Copyright 2015 Google LLC. 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.
"""Simple console pager."""
from __future__ import absolute_import
from __future__ import division
from __future__ import unicode_literals
import re
import sys
from fire.console import console_attr
class Pager(object):
"""A simple console text pager.
This pager requires the entire contents to be available. The contents are
written one page of lines at a time. The prompt is written after each page of
lines. A one character response is expected. See HELP_TEXT below for more
info.
The contents are written as is. For example, ANSI control codes will be in
effect. This is different from pagers like more(1) which is ANSI control code
agnostic and miscalculates line lengths, and less(1) which displays control
character names by default.
Attributes:
_attr: The current ConsoleAttr handle.
_clear: A string that clears the prompt when written to _out.
_contents: The entire contents of the text lines to page.
_height: The terminal height in characters.
_out: The output stream, log.out (effectively) if None.
_prompt: The page break prompt.
_search_direction: The search direction command, n:forward, N:reverse.
_search_pattern: The current forward/reverse search compiled RE.
_width: The termonal width in characters.
"""
HELP_TEXT = """
Simple pager commands:
b, ^B, ,
Back one page.
f, ^F, , ,
Forward one page. Does not quit if there are no more lines.
g,
Back to the first page.
g
Go to lines from the top.
G,
Forward to the last page.
G
Go to lines from the bottom.
h
Print pager command help.
j, +,
Forward one line.
k, -,
Back one line.
/pattern
Forward search for pattern.
?pattern
Backward search for pattern.
n
Repeat current search.
N
Repeat current search in the opposite direction.
q, Q, ^C, ^D, ^Z
Quit return to the caller.
any other character
Prompt again.
Hit any key to continue:"""
PREV_POS_NXT_REPRINT = -1, -1
def __init__(self, contents, out=None, prompt=None):
"""Constructor.
Args:
contents: The entire contents of the text lines to page.
out: The output stream, log.out (effectively) if None.
prompt: The page break prompt, a defalt prompt is used if None..
"""
self._contents = contents
self._out = out or sys.stdout
self._search_pattern = None
self._search_direction = None
# prev_pos, prev_next values to force reprint
self.prev_pos, self.prev_nxt = self.PREV_POS_NXT_REPRINT
# Initialize the console attributes.
self._attr = console_attr.GetConsoleAttr()
self._width, self._height = self._attr.GetTermSize()
# Initialize the prompt and the prompt clear string.
if not prompt:
prompt = '{bold}--({{percent}}%)--{normal}'.format(
bold=self._attr.GetFontCode(bold=True),
normal=self._attr.GetFontCode())
self._clear = '\r{0}\r'.format(' ' * (self._attr.DisplayWidth(prompt) - 6))
self._prompt = prompt
# Initialize a list of lines with long lines split into separate display
# lines.
self._lines = []
for line in contents.splitlines():
self._lines += self._attr.SplitLine(line, self._width)
def _Write(self, s):
"""Mockable helper that writes s to self._out."""
self._out.write(s)
def _GetSearchCommand(self, c):
"""Consumes a search command and returns the equivalent pager command.
The search pattern is an RE that is pre-compiled and cached for subsequent
/, ?, n, or N commands.
Args:
c: The search command char.
Returns:
The pager command char.
"""
self._Write(c)
buf = ''
while True:
p = self._attr.GetRawKey()
if p in (None, '\n', '\r') or len(p) != 1:
break
self._Write(p)
buf += p
self._Write('\r' + ' ' * len(buf) + '\r')
if buf:
try:
self._search_pattern = re.compile(buf)
except re.error:
# Silently ignore pattern errors.
self._search_pattern = None
return ''
self._search_direction = 'n' if c == '/' else 'N'
return 'n'
def _Help(self):
"""Print command help and wait for any character to continue."""
clear = self._height - (len(self.HELP_TEXT) -
len(self.HELP_TEXT.replace('\n', '')))
if clear > 0:
self._Write('\n' * clear)
self._Write(self.HELP_TEXT)
self._attr.GetRawKey()
self._Write('\n')
def Run(self):
"""Run the pager."""
# No paging if the contents are small enough.
if len(self._lines) <= self._height:
self._Write(self._contents)
return
# We will not always reset previous values.
reset_prev_values = True
# Save room for the prompt at the bottom of the page.
self._height -= 1
# Loop over all the pages.
pos = 0
while pos < len(self._lines):
# Write a page of lines.
nxt = pos + self._height
if nxt > len(self._lines):
nxt = len(self._lines)
pos = nxt - self._height
# Checks if the starting position is in between the current printed lines
# so we don't need to reprint all the lines.
if self.prev_pos < pos < self.prev_nxt:
# we start where the previous page ended.
self._Write('\n'.join(self._lines[self.prev_nxt:nxt]) + '\n')
elif pos != self.prev_pos and nxt != self.prev_nxt:
self._Write('\n'.join(self._lines[pos:nxt]) + '\n')
# Handle the prompt response.
percent = self._prompt.format(percent=100 * nxt // len(self._lines))
digits = ''
while True:
# We want to reset prev values if we just exited out of the while loop
if reset_prev_values:
self.prev_pos, self.prev_nxt = pos, nxt
reset_prev_values = False
self._Write(percent)
c = self._attr.GetRawKey()
self._Write(self._clear)
# Parse the command.
if c in (None, # EOF.
'q', # Quit.
'Q', # Quit.
'\x03', # ^C (unix & windows terminal interrupt)
'\x1b', # ESC.
):
# Quit.
return
elif c in ('/', '?'):
c = self._GetSearchCommand(c)
elif c.isdigit():
# Collect digits for operation count.
digits += c
continue
# Set the optional command count.
if digits:
count = int(digits)
digits = ''
else:
count = 0
# Finally commit to command c.
if c in ('', '', 'b', '\x02'):
# Previous page.
nxt = pos - self._height
if nxt < 0:
nxt = 0
elif c in ('', '', 'f', '\x06', ' '):
# Next page.
if nxt >= len(self._lines):
continue
nxt = pos + self._height
if nxt >= len(self._lines):
nxt = pos
elif c in ('', 'g'):
# First page.
nxt = count - 1
if nxt > len(self._lines) - self._height:
nxt = len(self._lines) - self._height
if nxt < 0:
nxt = 0
elif c in ('', 'G'):
# Last page.
nxt = len(self._lines) - count
if nxt > len(self._lines) - self._height:
nxt = len(self._lines) - self._height
if nxt < 0:
nxt = 0
elif c == 'h':
self._Help()
# Special case when we want to reprint the previous display.
self.prev_pos, self.prev_nxt = self.PREV_POS_NXT_REPRINT
nxt = pos
break
elif c in ('', 'j', '+', '\n', '\r'):
# Next line.
if nxt >= len(self._lines):
continue
nxt = pos + 1
if nxt >= len(self._lines):
nxt = pos
elif c in ('', 'k', '-'):
# Previous line.
nxt = pos - 1
if nxt < 0:
nxt = 0
elif c in ('n', 'N'):
# Next pattern match search.
if not self._search_pattern:
continue
nxt = pos
i = pos
direction = 1 if c == self._search_direction else -1
while True:
i += direction
if i < 0 or i >= len(self._lines):
break
if self._search_pattern.search(self._lines[i]):
nxt = i
break
else:
# Silently ignore everything else.
continue
if nxt != pos:
# We will exit the while loop because position changed so we can reset
# prev values.
reset_prev_values = True
break
pos = nxt
python-fire-0.2.1/fire/console/encoding.py 0000664 0000000 0000000 00000015216 13520106167 0020513 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*- #
# Copyright 2015 Google LLC. 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.
"""A module for dealing with unknown string and environment encodings."""
from __future__ import absolute_import
from __future__ import division
from __future__ import unicode_literals
import sys
import six
def Encode(string, encoding=None):
"""Encode the text string to a byte string.
Args:
string: str, The text string to encode.
encoding: The suggested encoding if known.
Returns:
str, The binary string.
"""
if string is None:
return None
if not six.PY2:
# In Python 3, the environment sets and gets accept and return text strings
# only, and it handles the encoding itself so this is not necessary.
return string
if isinstance(string, six.binary_type):
# Already an encoded byte string, we are done
return string
encoding = encoding or _GetEncoding()
return string.encode(encoding)
def Decode(data, encoding=None):
"""Returns string with non-ascii characters decoded to UNICODE.
UTF-8, the suggested encoding, and the usual suspects will be attempted in
order.
Args:
data: A string or object that has str() and unicode() methods that may
contain an encoding incompatible with the standard output encoding.
encoding: The suggested encoding if known.
Returns:
A text string representing the decoded byte string.
"""
if data is None:
return None
# First we are going to get the data object to be a text string.
# Don't use six.string_types here because on Python 3 bytes is not considered
# a string type and we want to include that.
if isinstance(data, six.text_type) or isinstance(data, six.binary_type):
string = data
else:
# Some non-string type of object.
try:
string = six.text_type(data)
except (TypeError, UnicodeError):
# The string cannot be converted to unicode -- default to str() which will
# catch objects with special __str__ methods.
string = str(data)
if isinstance(string, six.text_type):
# Our work is done here.
return string
try:
# Just return the string if its pure ASCII.
return string.decode('ascii')
except UnicodeError:
# The string is not ASCII encoded.
pass
# Try the suggested encoding if specified.
if encoding:
try:
return string.decode(encoding)
except UnicodeError:
# Bad suggestion.
pass
# Try UTF-8 because the other encodings could be extended ASCII. It would
# be exceptional if a valid extended ascii encoding with extended chars
# were also a valid UITF-8 encoding.
try:
return string.decode('utf8')
except UnicodeError:
# Not a UTF-8 encoding.
pass
# Try the filesystem encoding.
try:
return string.decode(sys.getfilesystemencoding())
except UnicodeError:
# string is not encoded for filesystem paths.
pass
# Try the system default encoding.
try:
return string.decode(sys.getdefaultencoding())
except UnicodeError:
# string is not encoded using the default encoding.
pass
# We don't know the string encoding.
# This works around a Python str.encode() "feature" that throws
# an ASCII *decode* exception on str strings that contain 8th bit set
# bytes. For example, this sequence throws an exception:
# string = '\xdc' # iso-8859-1 'Ü'
# string = string.encode('ascii', 'backslashreplace')
# even though 'backslashreplace' is documented to handle encoding
# errors. We work around the problem by first decoding the str string
# from an 8-bit encoding to unicode, selecting any 8-bit encoding that
# uses all 256 bytes (such as ISO-8559-1):
# string = string.decode('iso-8859-1')
# Using this produces a sequence that works:
# string = '\xdc'
# string = string.decode('iso-8859-1')
# string = string.encode('ascii', 'backslashreplace')
return string.decode('iso-8859-1')
def GetEncodedValue(env, name, default=None):
"""Returns the decoded value of the env var name.
Args:
env: {str: str}, The env dict.
name: str, The env var name.
default: The value to return if name is not in env.
Returns:
The decoded value of the env var name.
"""
name = Encode(name)
value = env.get(name)
if value is None:
return default
# In Python 3, the environment sets and gets accept and return text strings
# only, and it handles the encoding itself so this is not necessary.
return Decode(value)
def SetEncodedValue(env, name, value, encoding=None):
"""Sets the value of name in env to an encoded value.
Args:
env: {str: str}, The env dict.
name: str, The env var name.
value: str or unicode, The value for name. If None then name is removed from
env.
encoding: str, The encoding to use or None to try to infer it.
"""
# Python 2 *and* 3 unicode support falls apart at filesystem/argv/environment
# boundaries. The encoding used for filesystem paths and environment variable
# names/values is under user control on most systems. With one of those values
# in hand there is no way to tell exactly how the value was encoded. We get
# some reasonable hints from sys.getfilesystemencoding() or
# sys.getdefaultencoding() and use them to encode values that the receiving
# process will have a chance at decoding. Leaving the values as unicode
# strings will cause os module Unicode exceptions. What good is a language
# unicode model when the module support could care less?
name = Encode(name, encoding=encoding)
if value is None:
env.pop(name, None)
return
env[name] = Encode(value, encoding=encoding)
def EncodeEnv(env, encoding=None):
"""Encodes all the key value pairs in env in preparation for subprocess.
Args:
env: {str: str}, The environment you are going to pass to subprocess.
encoding: str, The encoding to use or None to use the default.
Returns:
{bytes: bytes}, The environment to pass to subprocess.
"""
encoding = encoding or _GetEncoding()
return {
Encode(k, encoding=encoding): Encode(v, encoding=encoding)
for k, v in six.iteritems(env)}
def _GetEncoding():
"""Gets the default encoding to use."""
return sys.getfilesystemencoding() or sys.getdefaultencoding()
python-fire-0.2.1/fire/console/files.py 0000664 0000000 0000000 00000007761 13520106167 0020035 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*- #
# Copyright 2013 Google LLC. 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.
"""Some general file utilities used that can be used by the Cloud SDK."""
from __future__ import absolute_import
from __future__ import division
from __future__ import unicode_literals
import os
from fire.console import encoding as encoding_util
from fire.console import platforms
import six
def _GetSystemPath():
"""Returns properly encoded system PATH variable string."""
return encoding_util.GetEncodedValue(os.environ, 'PATH')
def _FindExecutableOnPath(executable, path, pathext):
"""Internal function to a find an executable.
Args:
executable: The name of the executable to find.
path: A list of directories to search separated by 'os.pathsep'.
pathext: An iterable of file name extensions to use.
Returns:
str, the path to a file on `path` with name `executable` + `p` for
`p` in `pathext`.
Raises:
ValueError: invalid input.
"""
if isinstance(pathext, six.string_types):
raise ValueError('_FindExecutableOnPath(..., pathext=\'{0}\') failed '
'because pathext must be an iterable of strings, but got '
'a string.'.format(pathext))
# Prioritize preferred extension over earlier in path.
for ext in pathext:
for directory in path.split(os.pathsep):
# Windows can have paths quoted.
directory = directory.strip('"')
full = os.path.normpath(os.path.join(directory, executable) + ext)
# On Windows os.access(full, os.X_OK) is always True.
if os.path.isfile(full) and os.access(full, os.X_OK):
return full
return None
def _PlatformExecutableExtensions(platform):
if platform == platforms.OperatingSystem.WINDOWS:
return ('.exe', '.cmd', '.bat', '.com', '.ps1')
else:
return ('', '.sh')
def FindExecutableOnPath(executable, path=None, pathext=None,
allow_extensions=False):
"""Searches for `executable` in the directories listed in `path` or $PATH.
Executable must not contain a directory or an extension.
Args:
executable: The name of the executable to find.
path: A list of directories to search separated by 'os.pathsep'. If None
then the system PATH is used.
pathext: An iterable of file name extensions to use. If None then
platform specific extensions are used.
allow_extensions: A boolean flag indicating whether extensions in the
executable are allowed.
Returns:
The path of 'executable' (possibly with a platform-specific extension) if
found and executable, None if not found.
Raises:
ValueError: if executable has a path or an extension, and extensions are
not allowed, or if there's an internal error.
"""
if not allow_extensions and os.path.splitext(executable)[1]:
raise ValueError('FindExecutableOnPath({0},...) failed because first '
'argument must not have an extension.'.format(executable))
if os.path.dirname(executable):
raise ValueError('FindExecutableOnPath({0},...) failed because first '
'argument must not have a path.'.format(executable))
if path is None:
effective_path = _GetSystemPath()
else:
effective_path = path
effective_pathext = (pathext if pathext is not None
else _PlatformExecutableExtensions(
platforms.OperatingSystem.Current()))
return _FindExecutableOnPath(executable, effective_path,
effective_pathext)
python-fire-0.2.1/fire/console/platforms.py 0000664 0000000 0000000 00000040044 13520106167 0020731 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*- #
# Copyright 2013 Google LLC. 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.
"""Utilities for determining the current platform and architecture."""
from __future__ import absolute_import
from __future__ import division
from __future__ import unicode_literals
import os
import platform
import subprocess
import sys
class Error(Exception):
"""Base class for exceptions in the platforms module."""
pass
class InvalidEnumValue(Error): # pylint: disable=g-bad-exception-name
"""Exception for when a string could not be parsed to a valid enum value."""
def __init__(self, given, enum_type, options):
"""Constructs a new exception.
Args:
given: str, The given string that could not be parsed.
enum_type: str, The human readable name of the enum you were trying to
parse.
options: list(str), The valid values for this enum.
"""
super(InvalidEnumValue, self).__init__(
'Could not parse [{0}] into a valid {1}. Valid values are [{2}]'
.format(given, enum_type, ', '.join(options)))
class OperatingSystem(object):
"""An enum representing the operating system you are running on."""
class _OS(object):
"""A single operating system."""
# pylint: disable=redefined-builtin
def __init__(self, id, name, file_name):
self.id = id
self.name = name
self.file_name = file_name
def __str__(self):
return self.id
def __eq__(self, other):
return (isinstance(other, type(self)) and
self.id == other.id and
self.name == other.name and
self.file_name == other.file_name)
def __hash__(self):
return hash(self.id) + hash(self.name) + hash(self.file_name)
def __ne__(self, other):
return not self == other
@classmethod
def _CmpHelper(cls, x, y):
"""Just a helper equivalent to the cmp() function in Python 2."""
return (x > y) - (x < y)
def __lt__(self, other):
return self._CmpHelper(
(self.id, self.name, self.file_name),
(other.id, other.name, other.file_name)) < 0
def __gt__(self, other):
return self._CmpHelper(
(self.id, self.name, self.file_name),
(other.id, other.name, other.file_name)) > 0
def __le__(self, other):
return not self.__gt__(other)
def __ge__(self, other):
return not self.__lt__(other)
WINDOWS = _OS('WINDOWS', 'Windows', 'windows')
MACOSX = _OS('MACOSX', 'Mac OS X', 'darwin')
LINUX = _OS('LINUX', 'Linux', 'linux')
CYGWIN = _OS('CYGWIN', 'Cygwin', 'cygwin')
MSYS = _OS('MSYS', 'Msys', 'msys')
_ALL = [WINDOWS, MACOSX, LINUX, CYGWIN, MSYS]
@staticmethod
def AllValues():
"""Gets all possible enum values.
Returns:
list, All the enum values.
"""
return list(OperatingSystem._ALL)
@staticmethod
def FromId(os_id, error_on_unknown=True):
"""Gets the enum corresponding to the given operating system id.
Args:
os_id: str, The operating system id to parse
error_on_unknown: bool, True to raise an exception if the id is unknown,
False to just return None.
Raises:
InvalidEnumValue: If the given value cannot be parsed.
Returns:
OperatingSystemTuple, One of the OperatingSystem constants or None if the
input is None.
"""
if not os_id:
return None
for operating_system in OperatingSystem._ALL:
if operating_system.id == os_id:
return operating_system
if error_on_unknown:
raise InvalidEnumValue(os_id, 'Operating System',
[value.id for value in OperatingSystem._ALL])
return None
@staticmethod
def Current():
"""Determines the current operating system.
Returns:
OperatingSystemTuple, One of the OperatingSystem constants or None if it
cannot be determined.
"""
if os.name == 'nt':
return OperatingSystem.WINDOWS
elif 'linux' in sys.platform:
return OperatingSystem.LINUX
elif 'darwin' in sys.platform:
return OperatingSystem.MACOSX
elif 'cygwin' in sys.platform:
return OperatingSystem.CYGWIN
return None
@staticmethod
def IsWindows():
"""Returns True if the current operating system is Windows."""
return OperatingSystem.Current() is OperatingSystem.WINDOWS
class Architecture(object):
"""An enum representing the system architecture you are running on."""
class _ARCH(object):
"""A single architecture."""
# pylint: disable=redefined-builtin
def __init__(self, id, name, file_name):
self.id = id
self.name = name
self.file_name = file_name
def __str__(self):
return self.id
def __eq__(self, other):
return (isinstance(other, type(self)) and
self.id == other.id and
self.name == other.name and
self.file_name == other.file_name)
def __hash__(self):
return hash(self.id) + hash(self.name) + hash(self.file_name)
def __ne__(self, other):
return not self == other
@classmethod
def _CmpHelper(cls, x, y):
"""Just a helper equivalent to the cmp() function in Python 2."""
return (x > y) - (x < y)
def __lt__(self, other):
return self._CmpHelper(
(self.id, self.name, self.file_name),
(other.id, other.name, other.file_name)) < 0
def __gt__(self, other):
return self._CmpHelper(
(self.id, self.name, self.file_name),
(other.id, other.name, other.file_name)) > 0
def __le__(self, other):
return not self.__gt__(other)
def __ge__(self, other):
return not self.__lt__(other)
x86 = _ARCH('x86', 'x86', 'x86')
x86_64 = _ARCH('x86_64', 'x86_64', 'x86_64')
ppc = _ARCH('PPC', 'PPC', 'ppc')
arm = _ARCH('arm', 'arm', 'arm')
_ALL = [x86, x86_64, ppc, arm]
# Possible values for `uname -m` and what arch they map to.
# Examples of possible values: https://en.wikipedia.org/wiki/Uname
_MACHINE_TO_ARCHITECTURE = {
'amd64': x86_64, 'x86_64': x86_64, 'i686-64': x86_64,
'i386': x86, 'i686': x86, 'x86': x86,
'ia64': x86, # Itanium is different x64 arch, treat it as the common x86.
'powerpc': ppc, 'power macintosh': ppc, 'ppc64': ppc,
'armv6': arm, 'armv6l': arm, 'arm64': arm, 'armv7': arm, 'armv7l': arm}
@staticmethod
def AllValues():
"""Gets all possible enum values.
Returns:
list, All the enum values.
"""
return list(Architecture._ALL)
@staticmethod
def FromId(architecture_id, error_on_unknown=True):
"""Gets the enum corresponding to the given architecture id.
Args:
architecture_id: str, The architecture id to parse
error_on_unknown: bool, True to raise an exception if the id is unknown,
False to just return None.
Raises:
InvalidEnumValue: If the given value cannot be parsed.
Returns:
ArchitectureTuple, One of the Architecture constants or None if the input
is None.
"""
if not architecture_id:
return None
for arch in Architecture._ALL:
if arch.id == architecture_id:
return arch
if error_on_unknown:
raise InvalidEnumValue(architecture_id, 'Architecture',
[value.id for value in Architecture._ALL])
return None
@staticmethod
def Current():
"""Determines the current system architecture.
Returns:
ArchitectureTuple, One of the Architecture constants or None if it cannot
be determined.
"""
return Architecture._MACHINE_TO_ARCHITECTURE.get(platform.machine().lower())
class Platform(object):
"""Holds an operating system and architecture."""
def __init__(self, operating_system, architecture):
"""Constructs a new platform.
Args:
operating_system: OperatingSystem, The OS
architecture: Architecture, The machine architecture.
"""
self.operating_system = operating_system
self.architecture = architecture
def __str__(self):
return '{}-{}'.format(self.operating_system, self.architecture)
@staticmethod
def Current(os_override=None, arch_override=None):
"""Determines the current platform you are running on.
Args:
os_override: OperatingSystem, A value to use instead of the current.
arch_override: Architecture, A value to use instead of the current.
Returns:
Platform, The platform tuple of operating system and architecture. Either
can be None if it could not be determined.
"""
return Platform(
os_override if os_override else OperatingSystem.Current(),
arch_override if arch_override else Architecture.Current())
def UserAgentFragment(self):
"""Generates the fragment of the User-Agent that represents the OS.
Examples:
(Linux 3.2.5-gg1236)
(Windows NT 6.1.7601)
(Macintosh; PPC Mac OS X 12.4.0)
(Macintosh; Intel Mac OS X 12.4.0)
Returns:
str, The fragment of the User-Agent string.
"""
# Below, there are examples of the value of platform.uname() per platform.
# platform.release() is uname[2], platform.version() is uname[3].
if self.operating_system == OperatingSystem.LINUX:
# ('Linux', '', '3.2.5-gg1236',
# '#1 SMP Tue May 21 02:35:06 PDT 2013', 'x86_64', 'x86_64')
return '({name} {version})'.format(
name=self.operating_system.name, version=platform.release())
elif self.operating_system == OperatingSystem.WINDOWS:
# ('Windows', '', '7', '6.1.7601', 'AMD64',
# 'Intel64 Family 6 Model 45 Stepping 7, GenuineIntel')
return '({name} NT {version})'.format(
name=self.operating_system.name, version=platform.version())
elif self.operating_system == OperatingSystem.MACOSX:
# ('Darwin', '', '12.4.0',
# 'Darwin Kernel Version 12.4.0: Wed May 1 17:57:12 PDT 2013;
# root:xnu-2050.24.15~1/RELEASE_X86_64', 'x86_64', 'i386')
format_string = '(Macintosh; {name} Mac OS X {version})'
arch_string = (self.architecture.name
if self.architecture == Architecture.ppc else 'Intel')
return format_string.format(
name=arch_string, version=platform.release())
else:
return '()'
def AsyncPopenArgs(self):
"""Returns the args for spawning an async process using Popen on this OS.
Make sure the main process does not wait for the new process. On windows
this means setting the 0x8 creation flag to detach the process.
Killing a group leader kills the whole group. Setting creation flag 0x200 on
Windows or running setsid on *nix makes sure the new process is in a new
session with the new process the group leader. This means it can't be killed
if the parent is killed.
Finally, all file descriptors (FD) need to be closed so that waiting for the
output of the main process does not inadvertently wait for the output of the
new process, which means waiting for the termination of the new process.
If the new process wants to write to a file, it can open new FDs.
Returns:
{str:}, The args for spawning an async process using Popen on this OS.
"""
args = {}
if self.operating_system == OperatingSystem.WINDOWS:
args['close_fds'] = True # This is enough to close _all_ FDs on windows.
detached_process = 0x00000008
create_new_process_group = 0x00000200
# 0x008 | 0x200 == 0x208
args['creationflags'] = detached_process | create_new_process_group
else:
# Killing a group leader kills the whole group.
# Create a new session with the new process the group leader.
args['preexec_fn'] = os.setsid
args['close_fds'] = True # This closes all FDs _except_ 0, 1, 2 on *nix.
args['stdin'] = subprocess.PIPE
args['stdout'] = subprocess.PIPE
args['stderr'] = subprocess.PIPE
return args
class PythonVersion(object):
"""Class to validate the Python version we are using.
The Cloud SDK officially supports Python 2.7.
However, many commands do work with Python 2.6, so we don't error out when
users are using this (we consider it sometimes "compatible" but not
"supported").
"""
# See class docstring for descriptions of what these mean
MIN_REQUIRED_PY2_VERSION = (2, 6)
MIN_SUPPORTED_PY2_VERSION = (2, 7)
MIN_SUPPORTED_PY3_VERSION = (3, 4)
ENV_VAR_MESSAGE = """\
If you have a compatible Python interpreter installed, you can use it by setting
the CLOUDSDK_PYTHON environment variable to point to it.
"""
def __init__(self, version=None):
if version:
self.version = version
elif hasattr(sys, 'version_info'):
self.version = sys.version_info[:2]
else:
self.version = None
def SupportedVersionMessage(self, allow_py3):
if allow_py3:
return 'Please use Python version {0}.{1}.x or {2}.{3} and up.'.format(
PythonVersion.MIN_SUPPORTED_PY2_VERSION[0],
PythonVersion.MIN_SUPPORTED_PY2_VERSION[1],
PythonVersion.MIN_SUPPORTED_PY3_VERSION[0],
PythonVersion.MIN_SUPPORTED_PY3_VERSION[1])
else:
return 'Please use Python version {0}.{1}.x.'.format(
PythonVersion.MIN_SUPPORTED_PY2_VERSION[0],
PythonVersion.MIN_SUPPORTED_PY2_VERSION[1])
def IsCompatible(self, allow_py3=False, raise_exception=False):
"""Ensure that the Python version we are using is compatible.
This will print an error message if not compatible.
Compatible versions are 2.6 and 2.7 and > 3.4 if allow_py3 is True.
We don't guarantee support for 2.6 so we want to warn about it.
Args:
allow_py3: bool, True if we should allow a Python 3 interpreter to run
gcloud. If False, this returns an error for Python 3.
raise_exception: bool, True to raise an exception rather than printing
the error and exiting.
Raises:
Error: If not compatible and raise_exception is True.
Returns:
bool, True if the version is valid, False otherwise.
"""
error = None
if not self.version:
# We don't know the version, not a good sign.
error = ('ERROR: Your current version of Python is not compatible with '
'the Google Cloud SDK. {0}\n'
.format(self.SupportedVersionMessage(allow_py3)))
else:
if self.version[0] < 3:
# Python 2 Mode
if self.version < PythonVersion.MIN_REQUIRED_PY2_VERSION:
error = ('ERROR: Python {0}.{1} is not compatible with the Google '
'Cloud SDK. {2}\n'
.format(self.version[0], self.version[1],
self.SupportedVersionMessage(allow_py3)))
else:
# Python 3 Mode
if not allow_py3:
error = ('ERROR: Python 3 and later is not compatible with the '
'Google Cloud SDK. {0}\n'
.format(self.SupportedVersionMessage(allow_py3)))
elif self.version < PythonVersion.MIN_SUPPORTED_PY3_VERSION:
error = ('ERROR: Python {0}.{1} is not compatible with the Google '
'Cloud SDK. {2}\n'
.format(self.version[0], self.version[1],
self.SupportedVersionMessage(allow_py3)))
if error:
if raise_exception:
raise Error(error)
sys.stderr.write(error)
sys.stderr.write(PythonVersion.ENV_VAR_MESSAGE)
return False
# Warn that 2.6 might not work.
if (self.version >= self.MIN_REQUIRED_PY2_VERSION and
self.version < self.MIN_SUPPORTED_PY2_VERSION):
sys.stderr.write("""\
WARNING: Python 2.6.x is no longer officially supported by the Google Cloud SDK
and may not function correctly. {0}
{1}""".format(self.SupportedVersionMessage(allow_py3),
PythonVersion.ENV_VAR_MESSAGE))
return True
python-fire-0.2.1/fire/console/text.py 0000664 0000000 0000000 00000005330 13520106167 0017705 0 ustar 00root root 0000000 0000000 # -*- coding: utf-8 -*- #
# Copyright 2018 Google LLC. 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.
"""Semantic text objects that are used for styled outputting."""
from __future__ import absolute_import
from __future__ import division
from __future__ import unicode_literals
import enum
class TextAttributes(object):
"""Attributes to use to style text with."""
def __init__(self, format_str=None, color=None, attrs=None):
"""Defines a set of attributes for a piece of text.
Args:
format_str: (str), string that will be used to format the text
with. For example '[{}]', to enclose text in brackets.
color: (Colors), the color the text should be formatted with.
attrs: (Attrs), the attributes to apply to text.
"""
self._format_str = format_str
self._color = color
self._attrs = attrs or []
@property
def format_str(self):
return self._format_str
@property
def color(self):
return self._color
@property
def attrs(self):
return self._attrs
class TypedText(object):
"""Text with a semantic type that will be used for styling."""
def __init__(self, texts, text_type=None):
"""String of text and a corresponding type to use to style that text.
Args:
texts: (list[str]), list of strs or TypedText objects
that should be styled using text_type.
text_type: (TextTypes), the semantic type of the text that
will be used to style text.
"""
self.texts = texts
self.text_type = text_type
def __len__(self):
length = 0
for text in self.texts:
length += len(text)
return length
def __add__(self, other):
texts = [self, other]
return TypedText(texts)
def __radd__(self, other):
texts = [other, self]
return TypedText(texts)
class _TextTypes(enum.Enum):
"""Text types base class that defines base functionality."""
def __call__(self, *args):
"""Returns a TypedText object using this style."""
return TypedText(list(args), self)
# TODO: Add more types.
class TextTypes(_TextTypes):
"""Defines text types that can be used for styling text."""
RESOURCE_NAME = 1
URL = 2
USER_INPUT = 3
COMMAND = 4
INFO = 5
URI = 6
OUTPUT = 7
PT_SUCCESS = 8
PT_FAILURE = 9
python-fire-0.2.1/fire/core.py 0000664 0000000 0000000 00000107131 13520106167 0016211 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Python Fire is a library for creating CLIs from absolutely any Python object.
You can call Fire on any Python object:
functions, classes, modules, objects, dictionaries, lists, tuples, etc.
They all work!
Python Fire turns any Python object into a command line interface.
Simply call the Fire function as your main method to create a CLI.
When using Fire to build a CLI, your main method includes a call to Fire. Eg:
def main(argv):
fire.Fire(Component)
A Fire CLI command is run by consuming the arguments in the command in order to
access a member of current component, call the current component (if it's a
function), or instantiate the current component (if it's a class). The target
component begins as Component, and at each operation the component becomes the
result of the preceding operation.
For example "command fn arg1 arg2" might access the "fn" property of the initial
target component, and then call that function with arguments 'arg1' and 'arg2'.
Additional examples are available in the examples directory.
Fire Flags, common to all Fire CLIs, must go after a separating "--". For
example, to get help for a command you might run: `command -- --help`.
The available flags for all Fire CLIs are:
-v --verbose: Include private members in help and usage information.
-h --help: Provide help and usage information for the command.
-i --interactive: Drop into a Python REPL after running the command.
--completion: Write the Bash completion script for the tool to stdout.
--completion fish: Write the Fish completion script for the tool to stdout.
--separator SEPARATOR: Use SEPARATOR in place of the default separator, '-'.
--trace: Get the Fire Trace for the command.
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import inspect
import json
import os
import pipes
import re
import shlex
import sys
import types
from fire import completion
from fire import decorators
from fire import formatting
from fire import helptext
from fire import inspectutils
from fire import interact
from fire import parser
from fire import trace
from fire import value_types
from fire.console import console_io
import six
def Fire(component=None, command=None, name=None):
"""This function, Fire, is the main entrypoint for Python Fire.
Executes a command either from the `command` argument or from sys.argv by
recursively traversing the target object `component`'s members consuming
arguments, evaluating functions, and instantiating classes as it goes.
When building a CLI with Fire, your main method should call this function.
Args:
component: The initial target component.
command: Optional. If supplied, this is the command executed. If not
supplied, then the command is taken from sys.argv instead. This can be
a string or a list of strings; a list of strings is preferred.
name: Optional. The name of the command as entered at the command line.
Used in interactive mode and for generating the completion script.
Returns:
The result of executing the Fire command. Execution begins with the initial
target component. The component is updated by using the command arguments
to either access a member of the current component, call the current
component (if it's a function), or instantiate the current component (if
it's a class). When all arguments are consumed and there's no function left
to call or class left to instantiate, the resulting current component is
the final result.
Raises:
ValueError: If the command argument is supplied, but not a string or a
sequence of arguments.
FireExit: When Fire encounters a FireError, Fire will raise a FireExit with
code 2. When used with the help or trace flags, Fire will raise a
FireExit with code 0 if successful.
"""
name = name or os.path.basename(sys.argv[0])
# Get args as a list.
if isinstance(command, six.string_types):
args = shlex.split(command)
elif isinstance(command, (list, tuple)):
args = command
elif command is None:
# Use the command line args by default if no command is specified.
args = sys.argv[1:]
else:
raise ValueError('The command argument must be a string or a sequence of '
'arguments.')
args, flag_args = parser.SeparateFlagArgs(args)
argparser = parser.CreateParser()
parsed_flag_args, unused_args = argparser.parse_known_args(flag_args)
context = {}
if parsed_flag_args.interactive or component is None:
# Determine the calling context.
caller = inspect.stack()[1]
caller_frame = caller[0]
caller_globals = caller_frame.f_globals
caller_locals = caller_frame.f_locals
context.update(caller_globals)
context.update(caller_locals)
component_trace = _Fire(component, args, parsed_flag_args, context, name)
if component_trace.HasError():
_DisplayError(component_trace)
raise FireExit(2, component_trace)
if component_trace.show_trace and component_trace.show_help:
output = ['Fire trace:\n{trace}\n'.format(trace=component_trace)]
result = component_trace.GetResult()
help_text = helptext.HelpText(
result, trace=component_trace, verbose=component_trace.verbose)
output.append(help_text)
Display(output, out=sys.stderr)
raise FireExit(0, component_trace)
if component_trace.show_trace:
output = ['Fire trace:\n{trace}'.format(trace=component_trace)]
Display(output, out=sys.stderr)
raise FireExit(0, component_trace)
if component_trace.show_help:
result = component_trace.GetResult()
help_text = helptext.HelpText(
result, trace=component_trace, verbose=component_trace.verbose)
output = [help_text]
Display(output, out=sys.stderr)
raise FireExit(0, component_trace)
# The command succeeded normally; print the result.
_PrintResult(component_trace, verbose=component_trace.verbose)
result = component_trace.GetResult()
return result
def Display(lines, out):
text = '\n'.join(lines) + '\n'
console_io.More(text, out=out)
def CompletionScript(name, component, shell):
"""Returns the text of the completion script for a Fire CLI."""
return completion.Script(name, component, shell=shell)
class FireError(Exception):
"""Exception used by Fire when a Fire command cannot be executed.
These exceptions are not raised by the Fire function, but rather are caught
and added to the FireTrace.
"""
class FireExit(SystemExit): # pylint: disable=g-bad-exception-name
"""An exception raised by Fire to the client in the case of a FireError.
The trace of the Fire program is available on the `trace` property.
This exception inherits from SystemExit, so clients may explicitly catch it
with `except SystemExit` or `except FireExit`. If not caught, this exception
will cause the client program to exit without a stacktrace.
"""
def __init__(self, code, component_trace):
"""Constructs a FireExit exception.
Args:
code: (int) Exit code for the Fire CLI.
component_trace: (FireTrace) The trace for the Fire command.
"""
super(FireExit, self).__init__(code)
self.trace = component_trace
def _IsHelpShortcut(component_trace, remaining_args):
"""Determines if the user is trying to access help without '--' separator.
For example, mycmd.py --help instead of mycmd.py -- --help.
Args:
component_trace: (FireTrace) The trace for the Fire command.
remaining_args: List of remaining args that haven't been consumed yet.
Returns:
True if help is requested, False otherwise.
"""
show_help = False
if remaining_args:
target = remaining_args[0]
if target in ('-h', '--help'):
# Check if --help would be consumed as a keyword argument, or is a member.
component = component_trace.GetResult()
if inspect.isclass(component) or inspect.isroutine(component):
fn_spec = inspectutils.GetFullArgSpec(component)
_, remaining_kwargs, _ = _ParseKeywordArgs(remaining_args, fn_spec)
show_help = target in remaining_kwargs
else:
members = dict(inspect.getmembers(component))
show_help = target not in members
if show_help:
component_trace.show_help = True
command = '{cmd} -- --help'.format(cmd=component_trace.GetCommand())
print('INFO: Showing help with the command {cmd}.\n'.format(
cmd=pipes.quote(command)), file=sys.stderr)
return show_help
def _PrintResult(component_trace, verbose=False):
"""Prints the result of the Fire call to stdout in a human readable way."""
# TODO(dbieber): Design human readable deserializable serialization method
# and move serialization to its own module.
result = component_trace.GetResult()
if hasattr(result, '__str__'):
# If the object has a custom __str__ method, rather than one inherited from
# object, then we use that to serialize the object.
class_attrs = completion.GetClassAttrsDict(type(result)) or {}
str_attr = class_attrs.get('__str__')
if str_attr and str_attr.defining_class is not object:
print(str(result))
return
if isinstance(result, (list, set, frozenset, types.GeneratorType)):
for i in result:
print(_OneLineResult(i))
elif inspect.isgeneratorfunction(result):
raise NotImplementedError
elif isinstance(result, dict) and value_types.IsSimpleGroup(result):
print(_DictAsString(result, verbose))
elif isinstance(result, tuple):
print(_OneLineResult(result))
elif isinstance(result, value_types.VALUE_TYPES):
if result is not None:
print(result)
else:
help_text = helptext.HelpText(
result, trace=component_trace, verbose=verbose)
output = [help_text]
Display(output, out=sys.stdout)
def _DisplayError(component_trace):
"""Prints the Fire trace and the error to stdout."""
result = component_trace.GetResult()
output = []
show_help = False
for help_flag in ('-h', '--help'):
if help_flag in component_trace.elements[-1].args:
show_help = True
if show_help:
command = '{cmd} -- --help'.format(cmd=component_trace.GetCommand())
print('INFO: Showing help with the command {cmd}.\n'.format(
cmd=pipes.quote(command)), file=sys.stderr)
help_text = helptext.HelpText(result, trace=component_trace,
verbose=component_trace.verbose)
output.append(help_text)
Display(output, out=sys.stderr)
else:
print(formatting.Error('ERROR: ')
+ component_trace.elements[-1].ErrorAsStr(),
file=sys.stderr)
error_text = helptext.UsageText(result, trace=component_trace,
verbose=component_trace.verbose)
print(error_text, file=sys.stderr)
def _DictAsString(result, verbose=False):
"""Returns a dict as a string.
Args:
result: The dict to convert to a string
verbose: Whether to include 'hidden' members, those keys starting with _.
Returns:
A string representing the dict
"""
# We need to do 2 iterations over the items in the result dict
# 1) Getting visible items and the longest key for output formatting
# 2) Actually construct the output lines
class_attrs = completion.GetClassAttrsDict(result)
result_visible = {
key: value for key, value in result.items()
if completion.MemberVisible(result, key, value,
class_attrs=class_attrs, verbose=verbose)
}
if not result_visible:
return '{}'
longest_key = max(len(str(key)) for key in result_visible.keys())
format_string = '{{key:{padding}s}} {{value}}'.format(padding=longest_key + 1)
lines = []
for key, value in result.items():
if completion.MemberVisible(result, key, value, class_attrs=class_attrs,
verbose=verbose):
line = format_string.format(key=str(key) + ':',
value=_OneLineResult(value))
lines.append(line)
return '\n'.join(lines)
def _OneLineResult(result):
"""Returns result serialized to a single line string."""
# TODO(dbieber): Ensure line is fewer than eg 120 characters.
if isinstance(result, six.string_types):
return str(result).replace('\n', ' ')
# TODO(dbieber): Show a small amount of usage information about the function
# or module if it fits cleanly on the line.
if inspect.isfunction(result):
return ''.format(name=result.__name__)
if inspect.ismodule(result):
return ''.format(name=result.__name__)
try:
# Don't force conversion to ascii.
return json.dumps(result, ensure_ascii=False)
except (TypeError, ValueError):
return str(result).replace('\n', ' ')
def _Fire(component, args, parsed_flag_args, context, name=None):
"""Execute a Fire command on a target component using the args supplied.
Arguments that come after a final isolated '--' are treated as Flags, eg for
interactive mode or completion script generation.
Other arguments are consumed by the execution of the Fire command, eg in the
traversal of the members of the component, or in calling a function or
instantiating a class found during the traversal.
The steps performed by this method are:
1. Parse any Flag args (the args after the final --)
2. Start with component as the current component.
2a. If the current component is a class, instantiate it using args from args.
2b. If the component is a routine, call it using args from args.
2c. If the component is a sequence, index into it using an arg from
args.
2d. If possible, access a member from the component using an arg from args.
2e. If the component is a callable object, call it using args from args.
2f. Repeat 2a-2e until no args remain.
Note: Only the first applicable rule from 2a-2e is applied in each iteration.
After each iteration of step 2a-2e, the current component is updated to be the
result of the applied rule.
3a. Embed into ipython REPL if interactive mode is selected.
3b. Generate a completion script if that flag is provided.
In step 2, arguments will only ever be consumed up to a separator; a single
step will never consume arguments from both sides of a separator.
The separator defaults to a hyphen (-), and can be overwritten with the
--separator Fire argument.
Args:
component: The target component for Fire.
args: A list of args to consume in Firing on the component, usually from
the command line.
parsed_flag_args: The values of the flag args (e.g. --verbose, --separator)
that are part of every Fire CLI.
context: A dict with the local and global variables available at the call
to Fire.
name: Optional. The name of the command. Used in interactive mode and in
the tab completion script.
Returns:
FireTrace of components starting with component, tracing Fire's execution
path as it consumes args.
Raises:
ValueError: If there are arguments that cannot be consumed.
ValueError: If --completion is specified but no name available.
"""
verbose = parsed_flag_args.verbose
interactive = parsed_flag_args.interactive
separator = parsed_flag_args.separator
show_completion = parsed_flag_args.completion
show_help = parsed_flag_args.help
show_trace = parsed_flag_args.trace
# component can be a module, class, routine, object, etc.
if component is None:
component = context
initial_component = component
component_trace = trace.FireTrace(
initial_component=initial_component, name=name, separator=separator,
verbose=verbose, show_help=show_help, show_trace=show_trace)
instance = None
remaining_args = args
while True:
last_component = component
initial_args = remaining_args
if not remaining_args and (show_help or interactive or show_trace
or show_completion is not None):
# Don't initialize the final class or call the final function unless
# there's a separator after it, and instead process the current component.
break
if _IsHelpShortcut(component_trace, remaining_args):
remaining_args = []
break
saved_args = []
used_separator = False
if separator in remaining_args:
# For the current component, only use arguments up to the separator.
separator_index = remaining_args.index(separator)
saved_args = remaining_args[separator_index + 1:]
remaining_args = remaining_args[:separator_index]
used_separator = True
assert separator not in remaining_args
handled = False
candidate_errors = []
is_callable = inspect.isclass(component) or inspect.isroutine(component)
is_callable_object = callable(component) and not is_callable
is_sequence = isinstance(component, (list, tuple))
is_map = isinstance(component, dict) or inspectutils.IsNamedTuple(component)
if not handled and is_callable:
# The component is a class or a routine; we'll try to initialize it or
# call it.
is_class = inspect.isclass(component)
try:
component, remaining_args = _CallAndUpdateTrace(
component,
remaining_args,
component_trace,
treatment='class' if is_class else 'routine',
target=component.__name__)
handled = True
except FireError as error:
candidate_errors.append((error, initial_args))
if handled and last_component is initial_component:
# If the initial component is a class, keep an instance for use with -i.
instance = component
if not handled and is_sequence and remaining_args:
# The component is a tuple or list; we'll try to access a member.
arg = remaining_args[0]
try:
index = int(arg)
component = component[index]
handled = True
except (ValueError, IndexError):
error = FireError(
'Unable to index into component with argument:', arg)
candidate_errors.append((error, initial_args))
if handled:
remaining_args = remaining_args[1:]
filename = None
lineno = None
component_trace.AddAccessedProperty(
component, index, [arg], filename, lineno)
if not handled and is_map and remaining_args:
# The component is a dict or other key-value map; try to access a member.
target = remaining_args[0]
# Treat namedtuples as dicts when handling them as a map.
if inspectutils.IsNamedTuple(component):
component_dict = component._asdict() # pytype: disable=attribute-error
else:
component_dict = component
if target in component_dict:
component = component_dict[target]
handled = True
elif target.replace('-', '_') in component_dict:
component = component_dict[target.replace('-', '_')]
handled = True
else:
# The target isn't present in the dict as a string key, but maybe it is
# a key as another type.
# TODO(dbieber): Consider alternatives for accessing non-string keys.
for key, value in component_dict.items():
if target == str(key):
component = value
handled = True
break
if handled:
remaining_args = remaining_args[1:]
filename = None
lineno = None
component_trace.AddAccessedProperty(
component, target, [target], filename, lineno)
else:
error = FireError('Cannot find key:', target)
candidate_errors.append((error, initial_args))
if not handled and remaining_args:
# Object handler. We'll try to access a member of the component.
try:
target = remaining_args[0]
component, consumed_args, remaining_args = _GetMember(
component, remaining_args)
handled = True
filename, lineno = inspectutils.GetFileAndLine(component)
component_trace.AddAccessedProperty(
component, target, consumed_args, filename, lineno)
except FireError as error:
# Couldn't access member.
candidate_errors.append((error, initial_args))
if not handled and is_callable_object:
# The component is a callable object; we'll try to call it.
try:
component, remaining_args = _CallAndUpdateTrace(
component,
remaining_args,
component_trace,
treatment='callable')
handled = True
except FireError as error:
candidate_errors.append((error, initial_args))
if not handled and candidate_errors:
error, initial_args = candidate_errors[0]
component_trace.AddError(error, initial_args)
return component_trace
if used_separator:
# Add back in the arguments from after the separator.
if remaining_args:
remaining_args = remaining_args + [separator] + saved_args
elif (inspect.isclass(last_component)
or inspect.isroutine(last_component)):
remaining_args = saved_args
component_trace.AddSeparator()
elif component is not last_component:
remaining_args = [separator] + saved_args
else:
# It was an unnecessary separator.
remaining_args = saved_args
if component is last_component and remaining_args == initial_args:
# We're making no progress.
break
if remaining_args:
component_trace.AddError(
FireError('Could not consume arguments:', remaining_args),
initial_args)
return component_trace
if show_completion is not None:
if name is None:
raise ValueError('Cannot make completion script without command name')
script = CompletionScript(name, initial_component, shell=show_completion)
component_trace.AddCompletionScript(script)
if interactive:
variables = context.copy()
if name is not None:
variables[name] = initial_component
variables['component'] = initial_component
variables['result'] = component
variables['trace'] = component_trace
if instance is not None:
variables['self'] = instance
interact.Embed(variables, verbose)
component_trace.AddInteractiveMode()
return component_trace
def _GetMember(component, args):
"""Returns a subcomponent of component by consuming an arg from args.
Given a starting component and args, this function gets a member from that
component, consuming one arg in the process.
Args:
component: The component from which to get a member.
args: Args from which to consume in the search for the next component.
Returns:
component: The component that was found by consuming an arg.
consumed_args: The args that were consumed by getting this member.
remaining_args: The remaining args that haven't been consumed yet.
Raises:
FireError: If we cannot consume an argument to get a member.
"""
members = dict(inspect.getmembers(component))
arg = args[0]
arg_names = [
arg,
arg.replace('-', '_'), # treat '-' as '_'.
]
for arg_name in arg_names:
if arg_name in members:
return members[arg_name], [arg], args[1:]
raise FireError('Could not consume arg:', arg)
def _CallAndUpdateTrace(component, args, component_trace, treatment='class',
target=None):
"""Call the component by consuming args from args, and update the FireTrace.
The component could be a class, a routine, or a callable object. This function
calls the component and adds the appropriate action to component_trace.
Args:
component: The component to call
args: Args for calling the component
component_trace: FireTrace object that contains action trace
treatment: Type of treatment used. Indicating whether we treat the component
as a class, a routine, or a callable.
target: Target in FireTrace element, default is None. If the value is None,
the component itself will be used as target.
Returns:
component: The object that is the result of the callable call.
remaining_args: The remaining args that haven't been consumed yet.
"""
if not target:
target = component
filename, lineno = inspectutils.GetFileAndLine(component)
metadata = decorators.GetMetadata(component)
fn = component.__call__ if treatment == 'callable' else component
parse = _MakeParseFn(fn, metadata)
(varargs, kwargs), consumed_args, remaining_args, capacity = parse(args)
component = fn(*varargs, **kwargs)
if treatment == 'class':
action = trace.INSTANTIATED_CLASS
elif treatment == 'routine':
action = trace.CALLED_ROUTINE
else:
action = trace.CALLED_CALLABLE
component_trace.AddCalledComponent(
component, target, consumed_args, filename, lineno, capacity,
action=action)
return component, remaining_args
def _MakeParseFn(fn, metadata):
"""Creates a parse function for fn.
Args:
fn: The function or class to create the parse function for.
metadata: Additional metadata about the component the parse function is for.
Returns:
A parse function for fn. The parse function accepts a list of arguments
and returns (varargs, kwargs), remaining_args. The original function fn
can then be called with fn(*varargs, **kwargs). The remaining_args are
the leftover args from the arguments to the parse function.
"""
fn_spec = inspectutils.GetFullArgSpec(fn)
# Note: num_required_args is the number of positional arguments without
# default values. All of these arguments are required.
num_required_args = len(fn_spec.args) - len(fn_spec.defaults)
required_kwonly = set(fn_spec.kwonlyargs) - set(fn_spec.kwonlydefaults)
def _ParseFn(args):
"""Parses the list of `args` into (varargs, kwargs), remaining_args."""
kwargs, remaining_kwargs, remaining_args = _ParseKeywordArgs(args, fn_spec)
# Note: _ParseArgs modifies kwargs.
parsed_args, kwargs, remaining_args, capacity = _ParseArgs(
fn_spec.args, fn_spec.defaults, num_required_args, kwargs,
remaining_args, metadata)
if fn_spec.varargs or fn_spec.varkw:
# If we're allowed *varargs or **kwargs, there's always capacity.
capacity = True
extra_kw = set(kwargs) - set(fn_spec.kwonlyargs)
if fn_spec.varkw is None and extra_kw:
raise FireError('Unexpected kwargs present:', extra_kw)
missing_kwonly = set(required_kwonly) - set(kwargs)
if missing_kwonly:
raise FireError('Missing required flags:', missing_kwonly)
# If we accept *varargs, then use all remaining arguments for *varargs.
if fn_spec.varargs is not None:
varargs, remaining_args = remaining_args, []
else:
varargs = []
for index, value in enumerate(varargs):
varargs[index] = _ParseValue(value, None, None, metadata)
varargs = parsed_args + varargs
remaining_args += remaining_kwargs
consumed_args = args[:len(args) - len(remaining_args)]
return (varargs, kwargs), consumed_args, remaining_args, capacity
return _ParseFn
def _ParseArgs(fn_args, fn_defaults, num_required_args, kwargs,
remaining_args, metadata):
"""Parses the positional and named arguments from the available supplied args.
Modifies kwargs, removing args as they are used.
Args:
fn_args: A list of argument names that the target function accepts,
including positional and named arguments, but not the varargs or kwargs
names.
fn_defaults: A list of the default values in the function argspec.
num_required_args: The number of required arguments from the function's
argspec. This is the number of arguments without a default value.
kwargs: Dict with named command line arguments and their values.
remaining_args: The remaining command line arguments, which may still be
used as positional arguments.
metadata: Metadata about the function, typically from Fire decorators.
Returns:
parsed_args: A list of values to be used as positional arguments for calling
the target function.
kwargs: The input dict kwargs modified with the used kwargs removed.
remaining_args: A list of the supplied args that have not been used yet.
capacity: Whether the call could have taken args in place of defaults.
Raises:
FireError: If additional positional arguments are expected, but none are
available.
"""
accepts_positional_args = metadata.get(decorators.ACCEPTS_POSITIONAL_ARGS)
capacity = False # If we see a default get used, we'll set capacity to True
# Select unnamed args.
parsed_args = []
for index, arg in enumerate(fn_args):
value = kwargs.pop(arg, None)
if value is not None: # A value is specified at the command line.
value = _ParseValue(value, index, arg, metadata)
parsed_args.append(value)
else: # No value has been explicitly specified.
if remaining_args and accepts_positional_args:
# Use a positional arg.
value = remaining_args.pop(0)
value = _ParseValue(value, index, arg, metadata)
parsed_args.append(value)
elif index < num_required_args:
raise FireError(
'The function received no value for the required argument:', arg)
else:
# We're past the args for which there's no default value.
# There's a default value for this arg.
capacity = True
default_index = index - num_required_args # index into the defaults.
parsed_args.append(fn_defaults[default_index])
for key, value in kwargs.items():
kwargs[key] = _ParseValue(value, None, key, metadata)
return parsed_args, kwargs, remaining_args, capacity
def _ParseKeywordArgs(args, fn_spec):
"""Parses the supplied arguments for keyword arguments.
Given a list of arguments, finds occurrences of --name value, and uses 'name'
as the keyword and 'value' as the value. Constructs and returns a dictionary
of these keyword arguments, and returns a list of the remaining arguments.
Only if fn_keywords is None, this only finds argument names used by the
function, specified through fn_args.
This returns the values of the args as strings. They are later processed by
_ParseArgs, which converts them to the appropriate type.
Args:
args: A list of arguments.
fn_spec: The inspectutils.FullArgSpec describing the given callable.
Returns:
kwargs: A dictionary mapping keywords to values.
remaining_kwargs: A list of the unused kwargs from the original args.
remaining_args: A list of the unused arguments from the original args.
Raises:
FireError: If a single-character flag is passed that could refer to multiple
possible args.
"""
kwargs = {}
remaining_kwargs = []
remaining_args = []
fn_keywords = fn_spec.varkw
fn_args = fn_spec.args + fn_spec.kwonlyargs
if not args:
return kwargs, remaining_kwargs, remaining_args
skip_argument = False
for index, argument in enumerate(args):
if skip_argument:
skip_argument = False
continue
if _IsFlag(argument):
# This is a named argument. We get its value from this arg or the next.
# Terminology:
# argument: A full token from the command line, e.g. '--alpha=10'
# stripped_argument: An argument without leading hyphens.
# key: The contents of the stripped argument up to the first equal sign.
# "shortcut flag": refers to an argument where the key is just the first
# letter of a longer keyword.
# keyword: The Python function argument being set by this argument.
# value: The unparsed value for that Python function argument.
contains_equals = '=' in argument
stripped_argument = argument.lstrip('-')
if contains_equals:
key, value = stripped_argument.split('=', 1)
else:
key = stripped_argument
key = key.replace('-', '_')
is_bool_syntax = (not contains_equals and
(index + 1 == len(args) or _IsFlag(args[index + 1])))
# Determine the keyword.
keyword = '' # Indicates no valid keyword has been found yet.
if (key in fn_args
or (is_bool_syntax and key.startswith('no') and key[2:] in fn_args)
or fn_keywords):
keyword = key
elif len(key) == 1:
# This may be a shortcut flag.
matching_fn_args = [arg for arg in fn_args if arg[0] == key]
if len(matching_fn_args) == 1:
keyword = matching_fn_args[0]
elif len(matching_fn_args) > 1:
raise FireError("The argument '{}' is ambiguous as it could "
"refer to any of the following arguments: {}".format(
argument, matching_fn_args))
# Determine the value.
if not keyword:
got_argument = False
elif contains_equals:
# Already got the value above.
got_argument = True
elif is_bool_syntax:
# There's no next arg or the next arg is a Flag, so we consider this
# flag to be a boolean.
got_argument = True
if keyword in fn_args:
value = 'True'
elif keyword.startswith('no'):
keyword = keyword[2:]
value = 'False'
else:
value = 'True'
else:
# The assert should pass. Otherwise either contains_equals or
# is_bool_syntax would have been True.
assert index + 1 < len(args)
value = args[index + 1]
got_argument = True
# In order for us to consume the argument as a keyword arg, we either:
# Need to be explicitly expecting the keyword, or we need to be
# accepting **kwargs.
skip_argument = not contains_equals and not is_bool_syntax
if got_argument:
kwargs[keyword] = value
else:
remaining_kwargs.append(argument)
if skip_argument:
remaining_kwargs.append(args[index + 1])
else: # not _IsFlag(argument)
remaining_args.append(argument)
return kwargs, remaining_kwargs, remaining_args
def _IsFlag(argument):
"""Determines if the argument is a flag argument.
If it starts with a hyphen and isn't a negative number, it's a flag.
Args:
argument: A command line argument that may or may not be a flag.
Returns:
A boolean indicating whether the argument is a flag.
"""
return _IsSingleCharFlag(argument) or _IsMultiCharFlag(argument)
def _IsSingleCharFlag(argument):
"""Determines if the argument is a single char flag (e.g. '-a')."""
return re.match('^-[a-zA-Z]$', argument) or re.match('^-[a-zA-Z]=', argument)
def _IsMultiCharFlag(argument):
"""Determines if the argument is a multi char flag (e.g. '--alpha')."""
return argument.startswith('--') or re.match('^-[a-zA-Z]', argument)
def _ParseValue(value, index, arg, metadata):
"""Parses value, a string, into the appropriate type.
The function used to parse value is determined by the remaining arguments.
Args:
value: The string value to be parsed, typically a command line argument.
index: The index of the value in the function's argspec.
arg: The name of the argument the value is being parsed for.
metadata: Metadata about the function, typically from Fire decorators.
Returns:
value, parsed into the appropriate type for calling a function.
"""
parse_fn = parser.DefaultParseValue
# We check to see if any parse function from the fn metadata applies here.
parse_fns = metadata.get(decorators.FIRE_PARSE_FNS)
if parse_fns:
default = parse_fns['default']
positional = parse_fns['positional']
named = parse_fns['named']
if index is not None and 0 <= index < len(positional):
parse_fn = positional[index]
elif arg in named:
parse_fn = named[arg]
elif default is not None:
parse_fn = default
return parse_fn(value)
python-fire-0.2.1/fire/core_test.py 0000664 0000000 0000000 00000020261 13520106167 0017246 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for the core module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import core
from fire import test_components as tc
from fire import testutils
from fire import trace
import mock
class CoreTest(testutils.BaseTestCase):
def testOneLineResult(self):
self.assertEqual(core._OneLineResult(1), '1') # pylint: disable=protected-access
self.assertEqual(core._OneLineResult('hello'), 'hello') # pylint: disable=protected-access
self.assertEqual(core._OneLineResult({}), '{}') # pylint: disable=protected-access
self.assertEqual(core._OneLineResult({'x': 'y'}), '{"x": "y"}') # pylint: disable=protected-access
def testOneLineResultCircularRef(self):
circular_reference = tc.CircularReference()
self.assertEqual(core._OneLineResult(circular_reference.create()), # pylint: disable=protected-access
"{'y': {...}}")
@mock.patch('fire.interact.Embed')
def testInteractiveMode(self, mock_embed):
core.Fire(tc.TypedProperties, command=['alpha'])
self.assertFalse(mock_embed.called)
core.Fire(tc.TypedProperties, command=['alpha', '--', '-i'])
self.assertTrue(mock_embed.called)
@mock.patch('fire.interact.Embed')
def testInteractiveModeFullArgument(self, mock_embed):
core.Fire(tc.TypedProperties, command=['alpha', '--', '--interactive'])
self.assertTrue(mock_embed.called)
@mock.patch('fire.interact.Embed')
def testInteractiveModeVariables(self, mock_embed):
core.Fire(tc.WithDefaults, command=['double', '2', '--', '-i'])
self.assertTrue(mock_embed.called)
(variables, verbose), unused_kwargs = mock_embed.call_args
self.assertFalse(verbose)
self.assertEqual(variables['result'], 4)
self.assertIsInstance(variables['self'], tc.WithDefaults)
self.assertIsInstance(variables['trace'], trace.FireTrace)
@mock.patch('fire.interact.Embed')
def testInteractiveModeVariablesWithName(self, mock_embed):
core.Fire(tc.WithDefaults,
command=['double', '2', '--', '-i', '-v'], name='D')
self.assertTrue(mock_embed.called)
(variables, verbose), unused_kwargs = mock_embed.call_args
self.assertTrue(verbose)
self.assertEqual(variables['result'], 4)
self.assertIsInstance(variables['self'], tc.WithDefaults)
self.assertEqual(variables['D'], tc.WithDefaults)
self.assertIsInstance(variables['trace'], trace.FireTrace)
# TODO(dbieber): Use parameterized tests to break up repetitive tests.
def testHelpWithClass(self):
with self.assertRaisesFireExit(0, 'SYNOPSIS.*ARG1'):
core.Fire(tc.InstanceVars, command=['--', '--help'])
with self.assertRaisesFireExit(0, 'INFO:.*SYNOPSIS.*ARG1'):
core.Fire(tc.InstanceVars, command=['--help'])
with self.assertRaisesFireExit(0, 'INFO:.*SYNOPSIS.*ARG1'):
core.Fire(tc.InstanceVars, command=['-h'])
def testHelpWithMember(self):
with self.assertRaisesFireExit(0, 'SYNOPSIS.*capitalize'):
core.Fire(tc.TypedProperties, command=['gamma', '--', '--help'])
with self.assertRaisesFireExit(0, 'INFO:.*SYNOPSIS.*capitalize'):
core.Fire(tc.TypedProperties, command=['gamma', '--help'])
with self.assertRaisesFireExit(0, 'INFO:.*SYNOPSIS.*capitalize'):
core.Fire(tc.TypedProperties, command=['gamma', '-h'])
with self.assertRaisesFireExit(0, 'INFO:.*SYNOPSIS.*delta'):
core.Fire(tc.TypedProperties, command=['delta', '--help'])
with self.assertRaisesFireExit(0, 'INFO:.*SYNOPSIS.*echo'):
core.Fire(tc.TypedProperties, command=['echo', '--help'])
def testHelpOnErrorInConstructor(self):
with self.assertRaisesFireExit(0, 'SYNOPSIS.*VALUE'):
core.Fire(tc.ErrorInConstructor, command=['--', '--help'])
with self.assertRaisesFireExit(0, 'INFO:.*SYNOPSIS.*VALUE'):
core.Fire(tc.ErrorInConstructor, command=['--help'])
def testHelpWithNamespaceCollision(self):
# Tests cases when calling the help shortcut should not show help.
with self.assertOutputMatches(stdout='DESCRIPTION.*', stderr=None):
core.Fire(tc.WithHelpArg, command=['--help', 'False'])
with self.assertOutputMatches(stdout='help in a dict', stderr=None):
core.Fire(tc.WithHelpArg, command=['dictionary', '__help'])
with self.assertOutputMatches(stdout='{}', stderr=None):
core.Fire(tc.WithHelpArg, command=['dictionary', '--help'])
with self.assertOutputMatches(stdout='False', stderr=None):
core.Fire(tc.function_with_help, command=['False'])
def testInvalidParameterRaisesFireExit(self):
with self.assertRaisesFireExit(2, 'runmisspelled'):
core.Fire(tc.Kwargs, command=['props', '--a=1', '--b=2', 'runmisspelled'])
def testErrorRaising(self):
# Errors in user code should not be caught; they should surface as normal.
# This will lead to exit status code 1 for the client program.
with self.assertRaises(ValueError):
core.Fire(tc.ErrorRaiser, command=['fail'])
def testFireError(self):
error = core.FireError('Example error')
self.assertIsNotNone(error)
def testFireErrorMultipleValues(self):
error = core.FireError('Example error', 'value')
self.assertIsNotNone(error)
def testPrintEmptyDict(self):
with self.assertOutputMatches(stdout='{}', stderr=None):
core.Fire(tc.EmptyDictOutput, command=['totally_empty'])
with self.assertOutputMatches(stdout='{}', stderr=None):
core.Fire(tc.EmptyDictOutput, command=['nothing_printable'])
def testPrintOrderedDict(self):
with self.assertOutputMatches(stdout=r'A:\s+A\s+2:\s+2\s+', stderr=None):
core.Fire(tc.OrderedDictionary, command=['non_empty'])
with self.assertOutputMatches(stdout='{}'):
core.Fire(tc.OrderedDictionary, command=['empty'])
def testPrintNamedTupleField(self):
with self.assertOutputMatches(stdout='11', stderr=None):
core.Fire(tc.NamedTuple, command=['point', 'x'])
def testPrintNamedTupleFieldNameEqualsValue(self):
with self.assertOutputMatches(stdout='x', stderr=None):
core.Fire(tc.NamedTuple, command=['matching_names', 'x'])
def testPrintNamedTupleIndex(self):
with self.assertOutputMatches(stdout='22', stderr=None):
core.Fire(tc.NamedTuple, command=['point', '1'])
def testPrintSet(self):
with self.assertOutputMatches(stdout='.*three.*', stderr=None):
core.Fire(tc.simple_set(), command=[])
def testPrintFrozenSet(self):
with self.assertOutputMatches(stdout='.*three.*', stderr=None):
core.Fire(tc.simple_frozenset(), command=[])
def testPrintNamedTupleNegativeIndex(self):
with self.assertOutputMatches(stdout='11', stderr=None):
core.Fire(tc.NamedTuple, command=['point', '-2'])
def testCallable(self):
with self.assertOutputMatches(stdout=r'foo:\s+foo\s+', stderr=None):
core.Fire(tc.CallableWithKeywordArgument(), command=['--foo=foo'])
with self.assertOutputMatches(stdout=r'foo\s+', stderr=None):
core.Fire(tc.CallableWithKeywordArgument(), command=['print_msg', 'foo'])
with self.assertOutputMatches(stdout=r'', stderr=None):
core.Fire(tc.CallableWithKeywordArgument(), command=[])
def testCallableWithPositionalArgs(self):
with self.assertRaisesFireExit(2, ''):
# This does not give 7 since positional args are disallowed for callable
# objects.
core.Fire(tc.CallableWithPositionalArgs(), command=['3', '4'])
def testStaticMethod(self):
self.assertEqual(
core.Fire(tc.HasStaticAndClassMethods,
command=['static_fn', 'alpha']),
'alpha',
)
def testClassMethod(self):
self.assertEqual(
core.Fire(tc.HasStaticAndClassMethods,
command=['class_fn', '6']),
7,
)
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/custom_descriptions.py 0000664 0000000 0000000 00000005105 13520106167 0021357 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Custom descriptions and summaries for the builtin types.
The docstrings for objects of primitive types reflect the type of the object,
rather than the object itself. For example, the docstring for any dict is this:
> print({'key': 'value'}.__doc__)
dict() -> new empty dictionary
dict(mapping) -> new dictionary initialized from a mapping object's
(key, value) pairs
dict(iterable) -> new dictionary initialized as if via:
d = {}
for k, v in iterable:
d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs
in the keyword argument list. For example: dict(one=1, two=2)
As you can see, this docstring is more pertinant to the function `dict` and
would be suitable as the result of `dict.__doc__`, but is wholely unsuitable
as a description for the dict `{'key': 'value'}`.
This modules aims to resolve that problem, providing custom summaries and
descriptions for primitive typed values.
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import six
def NeedsCustomDescription(component):
"""Whether the component should use a custom description and summary.
Components of primitive type, such as ints, floats, dicts, lists, and others
have messy builtin docstrings. These are inappropriate for display as
descriptions and summaries in a CLI. This function determines whether the
provided component has one of these docstrings.
Note that an object such as `int` has the same docstring as an int like `3`.
The docstring is OK for `int`, but is inappropriate as a docstring for `3`.
Args:
component: The component of interest.
Returns:
Whether the component should use a custom description and summary.
"""
type_ = type(component)
if (type_ in six.string_types
or type_ in six.integer_types
or type_ is six.text_type
or type_ is six.binary_type
or type_ in (float, complex, bool)
or type_ in (dict, tuple, list, set, frozenset)
):
return True
return False
python-fire-0.2.1/fire/decorators.py 0000664 0000000 0000000 00000006216 13520106167 0017430 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""These decorators provide function metadata to Python Fire.
SetParseFn and SetParseFns allow you to set the functions Fire uses for parsing
command line arguments to client code.
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import inspect
FIRE_METADATA = 'FIRE_METADATA'
FIRE_PARSE_FNS = 'FIRE_PARSE_FNS'
ACCEPTS_POSITIONAL_ARGS = 'ACCEPTS_POSITIONAL_ARGS'
def SetParseFn(fn, *arguments):
"""Sets the fn for Fire to use to parse args when calling the decorated fn.
Args:
fn: The function to be used for parsing arguments.
*arguments: The arguments for which to use the parse fn. If none are listed,
then this will set the default parse function.
Returns:
The decorated function, which now has metadata telling Fire how to perform.
"""
def _Decorator(func):
parse_fns = GetParseFns(func)
if not arguments:
parse_fns['default'] = fn
else:
for argument in arguments:
parse_fns['named'][argument] = fn
_SetMetadata(func, FIRE_PARSE_FNS, parse_fns)
return func
return _Decorator
def SetParseFns(*positional, **named):
"""Set the fns for Fire to use to parse args when calling the decorated fn.
Returns a decorator, which when applied to a function adds metadata to the
function telling Fire how to turn string command line arguments into proper
Python arguments with which to call the function.
A parse function should accept a single string argument and return a value to
be used in its place when calling the decorated function.
Args:
*positional: The functions to be used for parsing positional arguments.
**named: The functions to be used for parsing named arguments.
Returns:
The decorated function, which now has metadata telling Fire how to perform.
"""
def _Decorator(fn):
parse_fns = GetParseFns(fn)
parse_fns['positional'] = positional
parse_fns['named'].update(named)
_SetMetadata(fn, FIRE_PARSE_FNS, parse_fns)
return fn
return _Decorator
def _SetMetadata(fn, attribute, value):
metadata = GetMetadata(fn)
metadata[attribute] = value
setattr(fn, FIRE_METADATA, metadata)
def GetMetadata(fn):
# Class __init__ functions and object __call__ functions require flag style
# arguments. Other methods and functions may accept positional args.
default = {
ACCEPTS_POSITIONAL_ARGS: inspect.isroutine(fn),
}
return getattr(fn, FIRE_METADATA, default)
def GetParseFns(fn):
metadata = GetMetadata(fn)
default = dict(default=None, positional=[], named={})
return metadata.get(FIRE_PARSE_FNS, default)
python-fire-0.2.1/fire/decorators_test.py 0000664 0000000 0000000 00000013154 13520106167 0020466 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for the decorators module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import core
from fire import decorators
from fire import testutils
class NoDefaults(object):
"""A class for testing decorated functions without default values."""
@decorators.SetParseFns(count=int)
def double(self, count):
return 2 * count
@decorators.SetParseFns(count=float)
def triple(self, count):
return 3 * count
@decorators.SetParseFns(int)
def quadruple(self, count):
return 4 * count
@decorators.SetParseFns(int)
def double(count):
return 2 * count
class WithDefaults(object):
@decorators.SetParseFns(float)
def example1(self, arg1=10):
return arg1, type(arg1)
@decorators.SetParseFns(arg1=float)
def example2(self, arg1=10):
return arg1, type(arg1)
class MixedArguments(object):
@decorators.SetParseFns(float, arg2=str)
def example3(self, arg1, arg2):
return arg1, arg2
class PartialParseFn(object):
@decorators.SetParseFns(arg1=str)
def example4(self, arg1, arg2):
return arg1, arg2
@decorators.SetParseFns(arg2=str)
def example5(self, arg1, arg2):
return arg1, arg2
class WithKwargs(object):
@decorators.SetParseFns(mode=str, count=int)
def example6(self, **kwargs):
return (
kwargs.get('mode', 'default'),
kwargs.get('count', 0),
)
class WithVarArgs(object):
@decorators.SetParseFn(str)
def example7(self, arg1, arg2=None, *varargs, **kwargs): # pylint: disable=keyword-arg-before-vararg
return arg1, arg2, varargs, kwargs
class FireDecoratorsTest(testutils.BaseTestCase):
def testSetParseFnsNamedArgs(self):
self.assertEqual(core.Fire(NoDefaults, command=['double', '2']), 4)
self.assertEqual(core.Fire(NoDefaults, command=['triple', '4']), 12.0)
def testSetParseFnsPositionalArgs(self):
self.assertEqual(core.Fire(NoDefaults, command=['quadruple', '5']), 20)
def testSetParseFnsFnWithPositionalArgs(self):
self.assertEqual(core.Fire(double, command=['5']), 10)
def testSetParseFnsDefaultsFromPython(self):
# When called from Python, function should behave normally.
self.assertTupleEqual(WithDefaults().example1(), (10, int))
self.assertEqual(WithDefaults().example1(5), (5, int))
self.assertEqual(WithDefaults().example1(12.0), (12, float))
def testSetParseFnsDefaultsFromFire(self):
# Fire should use the decorator to know how to parse string arguments.
self.assertEqual(core.Fire(WithDefaults, command=['example1']), (10, int))
self.assertEqual(core.Fire(WithDefaults, command=['example1', '10']),
(10, float))
self.assertEqual(core.Fire(WithDefaults, command=['example1', '13']),
(13, float))
self.assertEqual(core.Fire(WithDefaults, command=['example1', '14.0']),
(14, float))
def testSetParseFnsNamedDefaultsFromPython(self):
# When called from Python, function should behave normally.
self.assertTupleEqual(WithDefaults().example2(), (10, int))
self.assertEqual(WithDefaults().example2(5), (5, int))
self.assertEqual(WithDefaults().example2(12.0), (12, float))
def testSetParseFnsNamedDefaultsFromFire(self):
# Fire should use the decorator to know how to parse string arguments.
self.assertEqual(core.Fire(WithDefaults, command=['example2']), (10, int))
self.assertEqual(core.Fire(WithDefaults, command=['example2', '10']),
(10, float))
self.assertEqual(core.Fire(WithDefaults, command=['example2', '13']),
(13, float))
self.assertEqual(core.Fire(WithDefaults, command=['example2', '14.0']),
(14, float))
def testSetParseFnsPositionalAndNamed(self):
self.assertEqual(core.Fire(MixedArguments, ['example3', '10', '10']),
(10, '10'))
def testSetParseFnsOnlySomeTypes(self):
self.assertEqual(
core.Fire(PartialParseFn, command=['example4', '10', '10']), ('10', 10))
self.assertEqual(
core.Fire(PartialParseFn, command=['example5', '10', '10']), (10, '10'))
def testSetParseFnsForKeywordArgs(self):
self.assertEqual(
core.Fire(WithKwargs, command=['example6']), ('default', 0))
self.assertEqual(
core.Fire(WithKwargs, command=['example6', '--herring', '"red"']),
('default', 0))
self.assertEqual(
core.Fire(WithKwargs, command=['example6', '--mode', 'train']),
('train', 0))
self.assertEqual(core.Fire(WithKwargs, command=['example6', '--mode', '3']),
('3', 0))
self.assertEqual(
core.Fire(WithKwargs,
command=['example6', '--mode', '-1', '--count', '10']),
('-1', 10))
self.assertEqual(
core.Fire(WithKwargs, command=['example6', '--count', '-2']),
('default', -2))
def testSetParseFn(self):
self.assertEqual(
core.Fire(WithVarArgs,
command=['example7', '1', '--arg2=2', '3', '4', '--kwarg=5']),
('1', '2', ('3', '4'), {'kwarg': '5'}))
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/docstrings.py 0000664 0000000 0000000 00000055343 13520106167 0017447 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Docstring parsing module for Python Fire.
The following features of docstrings are not supported.
TODO(dbieber): Support these features.
- numpy docstrings may begin with the function signature.
- whitespace may be important for proper structuring of a docstring
- I've seen `argname` (with single backticks) as a style of documenting
arguments. The `argname` appears on one line, and the description on the next.
- .. Sphinx directives such as .. note:: are not understood.
- After a section ends, future contents may be included in the section. E.g.
:returns: This is what is returned.
Example: An example goes here.
- @param is sometimes used. E.g.
@param argname (type) Description
@return (type) Description
- The true signature of a function is not used by the docstring parser. It could
be useful for determining whether something is a section header or an argument
for example.
- This example confuses types as part of the docstrings.
Parameters
argname : argtype
Arg description
- If there's no blank line after the summary, the description will be slurped
up into the summary.
- "Examples" should be its own section type. aka "Usage".
- "Notes" should be a section type.
- Some people put parenthesis around their types in RST format, e.g.
:param (type) paramname:
- :rtype: directive (return type)
- Also ":rtype str" with no closing ":" has come up.
- Return types are not supported.
- "# Returns" as a section title style
- ":raises ExceptionType: Description" ignores the ExceptionType currently.
- "Defaults to X" occurs sometimes.
- "True | False" indicates bool type.
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import collections
import re
import textwrap
import enum
class DocstringInfo(
collections.namedtuple(
'DocstringInfo',
('summary', 'description', 'args', 'returns', 'yields', 'raises'))):
pass
DocstringInfo.__new__.__defaults__ = (None,) * len(DocstringInfo._fields)
class ArgInfo(
collections.namedtuple(
'ArgInfo',
('name', 'type', 'description'))):
pass
ArgInfo.__new__.__defaults__ = (None,) * len(ArgInfo._fields)
class Namespace(dict):
"""A dict with attribute (dot-notation) access enabled."""
def __getattr__(self, key):
if key not in self:
self[key] = Namespace()
return self[key]
def __setattr__(self, key, value):
self[key] = value
def __delattr__(self, key):
if key in self:
del self[key]
class Sections(enum.Enum):
ARGS = 0
RETURNS = 1
YIELDS = 2
RAISES = 3
TYPE = 4
class Formats(enum.Enum):
GOOGLE = 0
NUMPY = 1
RST = 2
SECTION_TITLES = {
Sections.ARGS: ('argument', 'arg', 'parameter', 'param'),
Sections.RETURNS: ('return',),
Sections.YIELDS: ('yield',),
Sections.RAISES: ('raise', 'except', 'exception', 'throw', 'error', 'warn'),
Sections.TYPE: ('type',), # rst-only
}
def parse(docstring):
"""Returns DocstringInfo about the given docstring.
This parser aims to parse Google, numpy, and rst formatted docstrings. These
are the three most common docstring styles at the time of this writing.
This parser aims to be permissive, working even when the docstring deviates
from the strict recommendations of these styles.
This parser does not aim to fully extract all structured information from a
docstring, since there are simply too many ways to structure information in a
docstring. Sometimes content will remain as unstructured text and simply gets
included in the description.
The Google docstring style guide is available at:
https://github.com/google/styleguide/blob/gh-pages/pyguide.md
The numpy docstring style guide is available at:
https://numpydoc.readthedocs.io/en/latest/format.html
Information about the rST docstring format is available at:
https://www.python.org/dev/peps/pep-0287/
The full set of directives such as param and type for rST docstrings are at:
http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html
Note: This function does not claim to handle all docstrings well. A list of
limitations is available at the top of the file. It does aim to run without
crashing in O(n) time on all strings on length n. If you find a string that
causes this to crash or run unacceptably slowly, please consider submitting
a pull request.
Args:
docstring: The docstring to parse.
Returns:
A DocstringInfo containing information about the docstring.
"""
if docstring is None:
return DocstringInfo()
lines = docstring.strip().split('\n')
lines_len = len(lines)
state = Namespace() # TODO(dbieber): Switch to an explicit class.
# Variables in state include:
state.section.title = None
state.section.indentation = None
state.section.line1_indentation = None
state.section.format = None
state.summary.permitted = True
state.summary.lines = []
state.description.lines = []
state.args = []
state.current_arg = None
state.returns.lines = []
state.yields.lines = []
state.raises.lines = []
for index, line in enumerate(lines):
has_next = index + 1 < lines_len
next_line = lines[index + 1] if has_next else None
line_info = _create_line_info(line, next_line)
_consume_line(line_info, state)
summary = ' '.join(state.summary.lines) if state.summary.lines else None
state.description.lines = _strip_blank_lines(state.description.lines)
description = textwrap.dedent('\n'.join(state.description.lines))
if not description:
description = None
returns = _join_lines(state.returns.lines)
yields = _join_lines(state.yields.lines)
raises = _join_lines(state.raises.lines)
args = [ArgInfo(
name=arg.name, type=_cast_to_known_type(_join_lines(arg.type.lines)),
description=_join_lines(arg.description.lines)) for arg in state.args]
return DocstringInfo(
summary=summary,
description=description,
args=args or None,
returns=returns,
raises=raises,
yields=yields,
)
def _strip_blank_lines(lines):
"""Removes lines containing only blank characters before and after the text.
Args:
lines: A list of lines.
Returns:
A list of lines without trailing or leading blank lines.
"""
# Find the first non-blank line.
start = 0
while lines and _is_blank(lines[start]):
start += 1
lines = lines[start:]
# Remove trailing blank lines.
while lines and _is_blank(lines[-1]):
lines.pop()
return lines
def _is_blank(line):
return not line or line.isspace()
def _join_lines(lines):
"""Joins lines with the appropriate connective whitespace.
This puts a single space between consecutive lines, unless there's a blank
line, in which case a full blank line is included.
Args:
lines: A list of lines to join.
Returns:
A string, the lines joined together.
"""
# TODO(dbieber): Add parameters for variations in whitespace handling.
if not lines:
return None
started = False
group_texts = [] # Full text of each section.
group_lines = [] # Lines within the current section.
for line in lines:
stripped_line = line.strip()
if stripped_line:
started = True
group_lines.append(stripped_line)
else:
if started:
group_text = ' '.join(group_lines)
group_texts.append(group_text)
group_lines = []
if group_lines: # Process the final group.
group_text = ' '.join(group_lines)
group_texts.append(group_text)
return '\n\n'.join(group_texts)
def _get_or_create_arg_by_name(state, name):
"""Gets or creates a new Arg.
These Arg objects (Namespaces) are turned into the ArgInfo namedtuples
returned by parse. Each Arg object is used to collect the name, type, and
description of a single argument to the docstring's function.
Args:
state: The state of the parser.
name: The name of the arg to create.
Returns:
The new Arg.
"""
for arg in state.args:
if arg.name == name:
return arg
arg = Namespace() # TODO(dbieber): Switch to an explicit class.
arg.name = name
arg.type.lines = []
arg.description.lines = []
state.args.append(arg)
return arg
def _is_arg_name(name):
"""Returns whether name is a valid arg name.
This is used to prevent multiple words (plaintext) from being misinterpreted
as an argument name. So if ":" appears in the middle of a line in a docstring,
we don't accidentally interpret the first half of that line as a single arg
name.
Args:
name: The name of the potential arg.
Returns:
True if name looks like an arg name, False otherwise.
"""
name = name.strip()
return (name
and ' ' not in name
and ':' not in name)
def _as_arg_name_and_type(text):
"""Returns text as a name and type, if text looks like an arg name and type.
Example:
_as_arg_name_and_type("foo (int)") == "foo", "int"
Args:
text: The text, which may or may not be an arg name and type.
Returns:
The arg name and type, if text looks like an arg name and type.
None otherwise.
"""
tokens = text.split()
if len(tokens) < 2:
return None
if _is_arg_name(tokens[0]):
type_token = ' '.join(tokens[1:])
type_token = type_token.lstrip('{([').rstrip('])}')
return tokens[0], type_token
else:
return None
def _as_arg_names(names_str):
"""Converts names_str to a list of arg names.
Example:
_as_arg_names("a, b, c") == ["a", "b", "c"]
Args:
names_str: A string with multiple space or comma separated arg names.
Returns:
A list of arg names, or None if names_str doesn't look like a list of arg
names.
"""
names = re.split(',| ', names_str)
names = [name.strip() for name in names if name.strip()]
for name in names:
if not _is_arg_name(name):
return None
if not names:
return None
return names
def _cast_to_known_type(name):
"""Canonicalizes a string representing a type if possible.
# TODO(dbieber): Support additional canonicalization, such as string/str, and
# boolean/bool.
Example:
_cast_to_known_type("str.") == "str"
Args:
name: A string representing a type, or None.
Returns:
A canonicalized version of the type string.
"""
if name is None:
return None
return name.rstrip('.')
def _consume_google_args_line(line_info, state):
"""Consume a single line from a Google args section."""
split_line = line_info.remaining.split(':', 1)
if len(split_line) > 1:
first, second = split_line # first is either the "arg" or "arg (type)"
if _is_arg_name(first.strip()):
arg = _get_or_create_arg_by_name(state, first.strip())
arg.description.lines.append(second.strip())
state.current_arg = arg
else:
arg_name_and_type = _as_arg_name_and_type(first)
if arg_name_and_type:
arg_name, type_str = arg_name_and_type
arg = _get_or_create_arg_by_name(state, arg_name)
arg.type.lines.append(type_str)
arg.description.lines.append(second.strip())
else:
if state.current_arg:
state.current_arg.description.lines.append(split_line[0])
else:
if state.current_arg:
state.current_arg.description.lines.append(split_line[0])
def _consume_line(line_info, state):
"""Consumes one line of text, updating the state accordingly.
When _consume_line is called, part of the line may already have been processed
for header information.
Args:
line_info: Information about the current and next line of the docstring.
state: The state of the docstring parser.
"""
_update_section_state(line_info, state)
if state.section.title is None:
if state.summary.permitted:
if line_info.remaining:
state.summary.lines.append(line_info.remaining)
elif state.summary.lines:
state.summary.permitted = False
else:
# We're past the end of the summary.
# Additions now contribute to the description.
state.description.lines.append(line_info.remaining_raw)
else:
state.summary.permitted = False
if state.section.new and state.section.format == Formats.RST:
# The current line starts with an RST directive, e.g. ":param arg:".
directive = _get_directive(line_info)
directive_tokens = directive.split() # pytype: disable=attribute-error
if state.section.title == Sections.ARGS:
name = directive_tokens[-1]
arg = _get_or_create_arg_by_name(state, name)
if len(directive_tokens) == 3:
# A param directive of the form ":param type arg:".
arg.type.lines.append(directive_tokens[1])
state.current_arg = arg
elif state.section.title == Sections.TYPE:
name = directive_tokens[-1]
arg = _get_or_create_arg_by_name(state, name)
state.current_arg = arg
if (state.section.format == Formats.NUMPY and
_line_is_hyphens(line_info.remaining)):
# Skip this all-hyphens line, which is part of the numpy section header.
return
if state.section.title == Sections.ARGS:
if state.section.format == Formats.GOOGLE:
_consume_google_args_line(line_info, state)
elif state.section.format == Formats.RST:
state.current_arg.description.lines.append(line_info.remaining.strip())
elif state.section.format == Formats.NUMPY:
line_stripped = line_info.remaining.strip()
if _is_arg_name(line_stripped):
# Token on its own line can either be the last word of the description
# of the previous arg, or a new arg. TODO: Whitespace can distinguish.
arg = _get_or_create_arg_by_name(state, line_stripped)
state.current_arg = arg
elif ':' in line_stripped:
possible_args, type_data = line_stripped.split(':', 1)
arg_names = _as_arg_names(possible_args) # re.split(' |,', s)
if arg_names:
for arg_name in arg_names:
arg = _get_or_create_arg_by_name(state, arg_name)
arg.type.lines.append(type_data)
state.current_arg = arg # TODO(dbieber): Multiple current args.
else: # Just an ordinary line.
if state.current_arg:
state.current_arg.description.lines.append(
line_info.remaining.strip())
else:
# TODO(dbieber): If not a blank line, add it to the description.
pass
else: # Just an ordinary line.
if state.current_arg:
state.current_arg.description.lines.append(
line_info.remaining.strip())
else:
# TODO(dbieber): If not a blank line, add it to the description.
pass
elif state.section.title == Sections.RETURNS:
state.returns.lines.append(line_info.remaining.strip())
elif state.section.title == Sections.YIELDS:
state.yields.lines.append(line_info.remaining.strip())
elif state.section.title == Sections.RAISES:
state.raises.lines.append(line_info.remaining.strip())
elif state.section.title == Sections.TYPE:
if state.section.format == Formats.RST:
assert state.current_arg is not None
state.current_arg.type.lines.append(line_info.remaining.strip())
else:
pass
def _create_line_info(line, next_line):
"""Returns information about the current and next line of the docstring."""
line_info = Namespace() # TODO(dbieber): Switch to an explicit class.
line_info.line = line
line_info.stripped = line.strip()
line_info.remaining_raw = line_info.line
line_info.remaining = line_info.stripped
line_info.indentation = len(line) - len(line.lstrip())
# TODO(dbieber): If next_line is blank, use the next non-blank line.
line_info.next.line = next_line
next_line_exists = next_line is not None
line_info.next.stripped = next_line.strip() if next_line_exists else None
line_info.next.indentation = (
len(next_line) - len(next_line.lstrip()) if next_line_exists else None)
# Note: This counts all whitespace equally.
return line_info
def _update_section_state(line_info, state):
"""Uses line_info to determine the current section of the docstring.
Updates state and line_info.remaining.
Args:
line_info: Information about the current line.
state: The state of the parser.
"""
section_updated = False
google_section_permitted = _google_section_permitted(line_info, state)
google_section = google_section_permitted and _google_section(line_info)
if google_section:
state.section.format = Formats.GOOGLE
state.section.title = google_section
line_info.remaining = _get_after_google_header(line_info)
line_info.remaining_raw = line_info.remaining
section_updated = True
rst_section = _rst_section(line_info)
if rst_section:
state.section.format = Formats.RST
state.section.title = rst_section
line_info.remaining = _get_after_directive(line_info)
line_info.remaining_raw = line_info.remaining
section_updated = True
numpy_section = _numpy_section(line_info)
if numpy_section:
state.section.format = Formats.NUMPY
state.section.title = numpy_section
line_info.remaining = ''
line_info.remaining_raw = line_info.remaining
section_updated = True
if section_updated:
state.section.new = True
state.section.indentation = line_info.indentation
state.section.line1_indentation = line_info.next.indentation
else:
state.section.new = False
def _google_section_permitted(line_info, state):
"""Returns whether a new google section is permitted to start here.
Q: Why might a new Google section not be allowed?
A: If we're in the middle of a Google "Args" section, then lines that start
"param:" will usually be a new arg, rather than a new section.
We use whitespace to determine when the Args section has actually ended.
A Google section ends when either:
- A new google section begins at either
- indentation less than indentation of line 1 of the previous section
- or <= indentation of the previous section
- Or the docstring terminates.
Args:
line_info: Information about the current line.
state: The state of the parser.
Returns:
True or False, indicating whether a new Google section is permitted at the
current line.
"""
if state.section.indentation is None: # We're not in a section yet.
return True
return (line_info.indentation <= state.section.indentation
or line_info.indentation < state.section.line1_indentation)
def _matches_section_title(title, section_title):
"""Returns whether title is a match for a specific section_title.
Example:
_matches_section_title('Yields', 'yield') == True
Args:
title: The title to check for matching.
section_title: A specific known section title to check against.
"""
title = title.lower()
section_title = section_title.lower()
return section_title in (title, title[:-1]) # Supports plurals / some typos.
def _matches_section(title, section):
"""Returns whether title is a match any known title for a specific section.
Example:
_matches_section_title('Yields', Sections.YIELDS) == True
_matches_section_title('param', Sections.Args) == True
Args:
title: The title to check for matching.
section: A specific section to check all possible titles for.
Returns:
True or False, indicating whether title is a match for the specified
section.
"""
for section_title in SECTION_TITLES[section]:
if _matches_section_title(title, section_title):
return True
return False
def _section_from_possible_title(possible_title):
"""Returns a section matched by the possible title, or None if none match.
Args:
possible_title: A string that may be the title of a new section.
Returns:
A Section type if one matches, or None if no section type matches.
"""
for section in SECTION_TITLES:
if _matches_section(possible_title, section):
return section
return None
def _google_section(line_info):
"""Checks whether the current line is the start of a new Google-style section.
This docstring is a Google-style docstring. Google-style sections look like
this:
Section Name:
section body goes here
Args:
line_info: Information about the current line.
Returns:
A Section type if one matches, or None if no section type matches.
"""
colon_index = line_info.remaining.find(':')
possible_title = line_info.remaining[:colon_index]
return _section_from_possible_title(possible_title)
def _get_after_google_header(line_info):
"""Gets the remainder of the line, after a Google header."""
colon_index = line_info.remaining.find(':')
return line_info.remaining[colon_index + 1:]
def _get_directive(line_info):
"""Gets a directive from the start of the line.
If the line is ":param str foo: Description of foo", then
_get_directive(line_info) returns "param str foo".
Args:
line_info: Information about the current line.
Returns:
The contents of a directive, or None if the line doesn't start with a
directive.
"""
if line_info.stripped.startswith(':'):
return line_info.stripped.split(':', 2)[1]
else:
return None
def _get_after_directive(line_info):
"""Gets the remainder of the line, after a directive."""
sections = line_info.stripped.split(':', 2)
if len(sections) > 2:
return sections[-1]
else:
return ''
def _rst_section(line_info):
"""Checks whether the current line is the start of a new RST-style section.
RST uses directives to specify information. An RST directive, which we refer
to as a section here, are surrounded with colons. For example, :param name:.
Args:
line_info: Information about the current line.
Returns:
A Section type if one matches, or None if no section type matches.
"""
directive = _get_directive(line_info)
if directive:
possible_title = directive.split()[0]
return _section_from_possible_title(possible_title)
else:
return None
def _line_is_hyphens(line):
"""Returns whether the line is entirely hyphens (and not blank)."""
return line and not line.strip('-')
def _numpy_section(line_info):
"""Checks whether the current line is the start of a new numpy-style section.
Numpy style sections are followed by a full line of hyphens, for example:
Section Name
------------
Section body goes here.
Args:
line_info: Information about the current line.
Returns:
A Section type if one matches, or None if no section type matches.
"""
next_line_is_hyphens = _line_is_hyphens(line_info.next.stripped)
if next_line_is_hyphens:
possible_title = line_info.remaining
return _section_from_possible_title(possible_title)
else:
return None
python-fire-0.2.1/fire/docstrings_fuzz_test.py 0000664 0000000 0000000 00000002272 13520106167 0021555 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Fuzz tests for the docstring parser module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import docstrings
from fire import testutils
from hypothesis import example
from hypothesis import given
from hypothesis import settings
from hypothesis import strategies as st
class DocstringsFuzzTest(testutils.BaseTestCase):
@settings(max_examples=1000, deadline=1000)
@given(st.text(min_size=1))
@example('This is a one-line docstring.')
def test_fuzz_parse(self, value):
docstrings.parse(value)
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/docstrings_test.py 0000664 0000000 0000000 00000021117 13520106167 0020476 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for fire docstrings module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import docstrings
from fire import testutils
DocstringInfo = docstrings.DocstringInfo # pylint: disable=invalid-name
ArgInfo = docstrings.ArgInfo # pylint: disable=invalid-name
class DocstringsTest(testutils.BaseTestCase):
def test_one_line_simple(self):
docstring = """A simple one line docstring."""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='A simple one line docstring.',
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_one_line_simple_whitespace(self):
docstring = """
A simple one line docstring.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='A simple one line docstring.',
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_one_line_too_long(self):
# pylint: disable=line-too-long
docstring = """A one line docstring thats both a little too verbose and a little too long so it keeps going well beyond a reasonable length for a one-liner.
"""
# pylint: enable=line-too-long
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='A one line docstring thats both a little too verbose and '
'a little too long so it keeps going well beyond a reasonable length '
'for a one-liner.',
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_one_line_runs_over(self):
# pylint: disable=line-too-long
docstring = """A one line docstring thats both a little too verbose and a little too long
so it runs onto a second line.
"""
# pylint: enable=line-too-long
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='A one line docstring thats both a little too verbose and '
'a little too long so it runs onto a second line.',
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_one_line_runs_over_whitespace(self):
docstring = """
A one line docstring thats both a little too verbose and a little too long
so it runs onto a second line.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='A one line docstring thats both a little too verbose and '
'a little too long so it runs onto a second line.',
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_google_format_args_only(self):
docstring = """One line description.
Args:
arg1: arg1_description
arg2: arg2_description
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='One line description.',
args=[
ArgInfo(name='arg1', description='arg1_description'),
ArgInfo(name='arg2', description='arg2_description'),
]
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_google_format_arg_named_args(self):
docstring = """
Args:
args: arg_description
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
args=[
ArgInfo(name='args', description='arg_description'),
]
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_google_format_typed_args_and_returns(self):
docstring = """Docstring summary.
This is a longer description of the docstring. It spans multiple lines, as
is allowed.
Args:
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
bool: The return value. True for success, False otherwise.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='Docstring summary.',
description='This is a longer description of the docstring. It spans '
'multiple lines, as\nis allowed.',
args=[
ArgInfo(name='param1', type='int',
description='The first parameter.'),
ArgInfo(name='param2', type='str',
description='The second parameter.'),
],
returns='bool: The return value. True for success, False otherwise.'
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_rst_format_typed_args_and_returns(self):
docstring = """Docstring summary.
This is a longer description of the docstring. It spans across multiple
lines.
:param arg1: Description of arg1.
:type arg1: str.
:param arg2: Description of arg2.
:type arg2: bool.
:returns: int -- description of the return value.
:raises: AttributeError, KeyError
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='Docstring summary.',
description='This is a longer description of the docstring. It spans '
'across multiple\nlines.',
args=[
ArgInfo(name='arg1', type='str',
description='Description of arg1.'),
ArgInfo(name='arg2', type='bool',
description='Description of arg2.'),
],
returns='int -- description of the return value.',
raises='AttributeError, KeyError',
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_numpy_format_typed_args_and_returns(self):
docstring = """Docstring summary.
This is a longer description of the docstring. It spans across multiple
lines.
Parameters
----------
param1 : int
The first parameter.
param2 : str
The second parameter.
Returns
-------
bool
True if successful, False otherwise.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='Docstring summary.',
description='This is a longer description of the docstring. It spans '
'across multiple\nlines.',
args=[
ArgInfo(name='param1', type='int',
description='The first parameter.'),
ArgInfo(name='param2', type='str',
description='The second parameter.'),
],
# TODO(dbieber): Support return type.
returns='bool True if successful, False otherwise.',
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_multisection_docstring(self):
docstring = """Docstring summary.
This is the first section of a docstring description.
This is the second section of a docstring description. This docstring
description has just two sections.
"""
docstring_info = docstrings.parse(docstring)
expected_docstring_info = DocstringInfo(
summary='Docstring summary.',
description='This is the first section of a docstring description.'
'\n\n'
'This is the second section of a docstring description. This docstring'
'\n'
'description has just two sections.',
)
self.assertEqual(expected_docstring_info, docstring_info)
def test_google_section_with_blank_first_line(self):
docstring = """Inspired by requests HTTPAdapter docstring.
:param x: Simple param.
Usage:
>>> import requests
"""
docstring_info = docstrings.parse(docstring)
self.assertEqual('Inspired by requests HTTPAdapter docstring.',
docstring_info.summary)
def test_ill_formed_docstring(self):
docstring = """Docstring summary.
args: raises ::
:
pathological docstrings should not fail, and ideally should behave
reasonably.
"""
docstrings.parse(docstring)
def test_strip_blank_lines(self):
lines = [' ', ' foo ', ' ']
expected_output = [' foo ']
self.assertEqual(expected_output, docstrings._strip_blank_lines(lines)) # pylint: disable=protected-access
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/fire_import_test.py 0000664 0000000 0000000 00000002105 13520106167 0020632 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests importing the fire module."""
import sys
import fire
from fire import testutils
import mock
class FireImportTest(testutils.BaseTestCase):
"""Tests importing Fire."""
def testFire(self):
with mock.patch.object(sys, 'argv', ['commandname']):
fire.Fire()
def testFireMethods(self):
self.assertIsNotNone(fire.Fire)
def testNoPrivateMethods(self):
self.assertTrue(hasattr(fire, 'Fire'))
self.assertFalse(hasattr(fire, '_Fire'))
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/fire_test.py 0000664 0000000 0000000 00000070026 13520106167 0017247 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for the fire module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import os
import sys
import unittest
import fire
from fire import test_components as tc
from fire import testutils
import mock
import six
class FireTest(testutils.BaseTestCase):
def testFire(self):
with mock.patch.object(sys, 'argv', ['progname']):
fire.Fire(tc.Empty)
fire.Fire(tc.OldStyleEmpty)
fire.Fire(tc.WithInit)
# Test both passing command as a sequence and as a string.
self.assertEqual(fire.Fire(tc.NoDefaults, command='triple 4'), 12)
self.assertEqual(fire.Fire(tc.WithDefaults, command=('double', '2')), 4)
self.assertEqual(fire.Fire(tc.WithDefaults, command=['triple', '4']), 12)
self.assertEqual(fire.Fire(tc.OldStyleWithDefaults,
command=['double', '2']), 4)
self.assertEqual(fire.Fire(tc.OldStyleWithDefaults,
command=['triple', '4']), 12)
def testFirePositionalCommand(self):
# Test passing command as a positional argument.
self.assertEqual(fire.Fire(tc.NoDefaults, 'double 2'), 4)
self.assertEqual(fire.Fire(tc.NoDefaults, ['double', '2']), 4)
def testFireInvalidCommandArg(self):
with self.assertRaises(ValueError):
# This is not a valid command.
fire.Fire(tc.WithDefaults, command=10)
def testFireDefaultName(self):
with mock.patch.object(sys, 'argv',
[os.path.join('python-fire', 'fire',
'base_filename.py')]):
with self.assertOutputMatches(stdout='SYNOPSIS.*base_filename.py',
stderr=None):
fire.Fire(tc.Empty)
def testFireNoArgs(self):
self.assertEqual(fire.Fire(tc.MixedDefaults, command=['ten']), 10)
def testFireExceptions(self):
# Exceptions of Fire are printed to stderr and a FireExit is raised.
with self.assertRaisesFireExit(2):
fire.Fire(tc.Empty, command=['nomethod']) # Member doesn't exist.
with self.assertRaisesFireExit(2):
fire.Fire(tc.NoDefaults, command=['double']) # Missing argument.
with self.assertRaisesFireExit(2):
fire.Fire(tc.TypedProperties, command=['delta', 'x']) # Missing key.
# Exceptions of the target components are still raised.
with self.assertRaises(ZeroDivisionError):
fire.Fire(tc.NumberDefaults, command=['reciprocal', '0.0'])
def testFireNamedArgs(self):
self.assertEqual(fire.Fire(tc.WithDefaults,
command=['double', '--count', '5']), 10)
self.assertEqual(fire.Fire(tc.WithDefaults,
command=['triple', '--count', '5']), 15)
self.assertEqual(
fire.Fire(tc.OldStyleWithDefaults, command=['double', '--count', '5']),
10)
self.assertEqual(
fire.Fire(tc.OldStyleWithDefaults, command=['triple', '--count', '5']),
15)
def testFireNamedArgsSingleHyphen(self):
self.assertEqual(fire.Fire(tc.WithDefaults,
command=['double', '-count', '5']), 10)
self.assertEqual(fire.Fire(tc.WithDefaults,
command=['triple', '-count', '5']), 15)
self.assertEqual(
fire.Fire(tc.OldStyleWithDefaults, command=['double', '-count', '5']),
10)
self.assertEqual(
fire.Fire(tc.OldStyleWithDefaults, command=['triple', '-count', '5']),
15)
def testFireNamedArgsWithEquals(self):
self.assertEqual(fire.Fire(tc.WithDefaults,
command=['double', '--count=5']), 10)
self.assertEqual(fire.Fire(tc.WithDefaults,
command=['triple', '--count=5']), 15)
def testFireNamedArgsWithEqualsSingleHyphen(self):
self.assertEqual(fire.Fire(tc.WithDefaults,
command=['double', '-count=5']), 10)
self.assertEqual(fire.Fire(tc.WithDefaults,
command=['triple', '-count=5']), 15)
def testFireAllNamedArgs(self):
self.assertEqual(fire.Fire(tc.MixedDefaults, command=['sum', '1', '2']), 5)
self.assertEqual(fire.Fire(tc.MixedDefaults,
command=['sum', '--alpha', '1', '2']), 5)
self.assertEqual(fire.Fire(tc.MixedDefaults,
command=['sum', '--beta', '1', '2']), 4)
self.assertEqual(fire.Fire(tc.MixedDefaults,
command=['sum', '1', '--alpha', '2']), 4)
self.assertEqual(fire.Fire(tc.MixedDefaults,
command=['sum', '1', '--beta', '2']), 5)
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['sum', '--alpha', '1', '--beta', '2']), 5)
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['sum', '--beta', '1', '--alpha', '2']), 4)
def testFireAllNamedArgsOneMissing(self):
self.assertEqual(fire.Fire(tc.MixedDefaults, command=['sum']), 0)
self.assertEqual(fire.Fire(tc.MixedDefaults, command=['sum', '1']), 1)
self.assertEqual(fire.Fire(tc.MixedDefaults,
command=['sum', '--alpha', '1']), 1)
self.assertEqual(fire.Fire(tc.MixedDefaults,
command=['sum', '--beta', '2']), 4)
def testFirePartialNamedArgs(self):
self.assertEqual(
fire.Fire(tc.MixedDefaults, command=['identity', '1', '2']), (1, 2))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '--alpha', '1', '2']), (1, 2))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '--beta', '1', '2']), (2, 1))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '1', '--alpha', '2']), (2, 1))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '1', '--beta', '2']), (1, 2))
self.assertEqual(
fire.Fire(
tc.MixedDefaults,
command=['identity', '--alpha', '1', '--beta', '2']), (1, 2))
self.assertEqual(
fire.Fire(
tc.MixedDefaults,
command=['identity', '--beta', '1', '--alpha', '2']), (2, 1))
def testFirePartialNamedArgsOneMissing(self):
# Errors are written to standard out and a FireExit is raised.
with self.assertRaisesFireExit(2):
fire.Fire(tc.MixedDefaults,
command=['identity']) # Identity needs an arg.
with self.assertRaisesFireExit(2):
# Identity needs a value for alpha.
fire.Fire(tc.MixedDefaults, command=['identity', '--beta', '2'])
self.assertEqual(
fire.Fire(tc.MixedDefaults, command=['identity', '1']), (1, '0'))
self.assertEqual(
fire.Fire(tc.MixedDefaults, command=['identity', '--alpha', '1']),
(1, '0'))
def testFireAnnotatedArgs(self):
self.assertEqual(fire.Fire(tc.Annotations, command=['double', '5']), 10)
self.assertEqual(fire.Fire(tc.Annotations, command=['triple', '5']), 15)
@unittest.skipIf(six.PY2, 'Keyword-only arguments not in Python 2.')
def testFireKeywordOnlyArgs(self):
with self.assertRaisesFireExit(2):
# Keyword arguments must be passed with flag syntax.
fire.Fire(tc.py3.KeywordOnly, command=['double', '5'])
self.assertEqual(
fire.Fire(tc.py3.KeywordOnly, command=['double', '--count', '5']), 10)
self.assertEqual(
fire.Fire(tc.py3.KeywordOnly, command=['triple', '--count', '5']), 15)
def testFireProperties(self):
self.assertEqual(fire.Fire(tc.TypedProperties, command=['alpha']), True)
self.assertEqual(fire.Fire(tc.TypedProperties, command=['beta']), (1, 2, 3))
def testFireRecursion(self):
self.assertEqual(
fire.Fire(tc.TypedProperties,
command=['charlie', 'double', 'hello']), 'hellohello')
self.assertEqual(fire.Fire(tc.TypedProperties,
command=['charlie', 'triple', 'w']), 'www')
def testFireVarArgs(self):
self.assertEqual(
fire.Fire(tc.VarArgs,
command=['cumsums', 'a', 'b', 'c', 'd']),
['a', 'ab', 'abc', 'abcd'])
self.assertEqual(
fire.Fire(tc.VarArgs, command=['cumsums', '1', '2', '3', '4']),
[1, 3, 6, 10])
def testFireVarArgsWithNamedArgs(self):
self.assertEqual(
fire.Fire(tc.VarArgs, command=['varchars', '1', '2', 'c', 'd']),
(1, 2, 'cd'))
self.assertEqual(
fire.Fire(tc.VarArgs, command=['varchars', '3', '4', 'c', 'd', 'e']),
(3, 4, 'cde'))
def testFireKeywordArgs(self):
self.assertEqual(
fire.Fire(
tc.Kwargs,
command=['props', '--name', 'David', '--age', '24']),
{'name': 'David', 'age': 24})
# Run this test both with a list command and a string command.
self.assertEqual(
fire.Fire(
tc.Kwargs,
command=['props', '--message',
'"This is a message it has -- in it"']), # Quotes stripped
{'message': 'This is a message it has -- in it'})
self.assertEqual(
fire.Fire(
tc.Kwargs,
command=['props', '--message',
'This is a message it has -- in it']),
{'message': 'This is a message it has -- in it'})
self.assertEqual(
fire.Fire(
tc.Kwargs,
command='props --message "This is a message it has -- in it"'),
{'message': 'This is a message it has -- in it'})
self.assertEqual(
fire.Fire(tc.Kwargs,
command=['upper', '--alpha', 'A', '--beta', 'B']),
'ALPHA BETA')
self.assertEqual(
fire.Fire(
tc.Kwargs,
command=['upper', '--alpha', 'A', '--beta', 'B', '-', 'lower']),
'alpha beta')
def testFireKeywordArgsWithMissingPositionalArgs(self):
self.assertEqual(
fire.Fire(tc.Kwargs, command=['run', 'Hello', 'World', '--cell', 'is']),
('Hello', 'World', {'cell': 'is'}))
self.assertEqual(
fire.Fire(tc.Kwargs, command=['run', 'Hello', '--cell', 'ok']),
('Hello', None, {'cell': 'ok'}))
def testFireObject(self):
self.assertEqual(
fire.Fire(tc.WithDefaults(), command=['double', '--count', '5']), 10)
self.assertEqual(
fire.Fire(tc.WithDefaults(), command=['triple', '--count', '5']), 15)
def testFireDict(self):
component = {
'double': lambda x=0: 2 * x,
'cheese': 'swiss',
}
self.assertEqual(fire.Fire(component, command=['double', '5']), 10)
self.assertEqual(fire.Fire(component, command=['cheese']), 'swiss')
def testFireObjectWithDict(self):
self.assertEqual(
fire.Fire(tc.TypedProperties, command=['delta', 'echo']), 'E')
self.assertEqual(
fire.Fire(tc.TypedProperties, command=['delta', 'echo', 'lower']), 'e')
self.assertIsInstance(
fire.Fire(tc.TypedProperties, command=['delta', 'nest']), dict)
self.assertEqual(
fire.Fire(tc.TypedProperties, command=['delta', 'nest', '0']), 'a')
def testFireSet(self):
component = tc.simple_set()
result = fire.Fire(component, command=[])
self.assertEqual(len(result), 3)
def testFireFrozenset(self):
component = tc.simple_frozenset()
result = fire.Fire(component, command=[])
self.assertEqual(len(result), 3)
def testFireList(self):
component = ['zero', 'one', 'two', 'three']
self.assertEqual(fire.Fire(component, command=['2']), 'two')
self.assertEqual(fire.Fire(component, command=['3']), 'three')
self.assertEqual(fire.Fire(component, command=['-1']), 'three')
def testFireObjectWithList(self):
self.assertEqual(fire.Fire(tc.TypedProperties, command=['echo', '0']),
'alex')
self.assertEqual(fire.Fire(tc.TypedProperties, command=['echo', '1']),
'bethany')
def testFireObjectWithTuple(self):
self.assertEqual(fire.Fire(tc.TypedProperties, command=['fox', '0']),
'carry')
self.assertEqual(fire.Fire(tc.TypedProperties, command=['fox', '1']),
'divide')
def testFireObjectWithListAsObject(self):
self.assertEqual(
fire.Fire(tc.TypedProperties, command=['echo', 'count', 'bethany']),
1)
def testFireObjectWithTupleAsObject(self):
self.assertEqual(
fire.Fire(tc.TypedProperties, command=['fox', 'count', 'divide']),
1)
def testFireNoComponent(self):
self.assertEqual(fire.Fire(command=['tc', 'WithDefaults', 'double', '10']),
20)
last_char = lambda text: text[-1] # pylint: disable=unused-variable
self.assertEqual(fire.Fire(command=['last_char', '"Hello"']), 'o')
self.assertEqual(fire.Fire(command=['last-char', '"World"']), 'd')
rset = lambda count=0: set(range(count)) # pylint: disable=unused-variable
self.assertEqual(fire.Fire(command=['rset', '5']), {0, 1, 2, 3, 4})
def testFireUnderscores(self):
self.assertEqual(
fire.Fire(tc.Underscores,
command=['underscore-example']), 'fish fingers')
self.assertEqual(
fire.Fire(tc.Underscores,
command=['underscore_example']), 'fish fingers')
def testFireUnderscoresInArg(self):
self.assertEqual(
fire.Fire(tc.Underscores,
command=['underscore-function', 'example']), 'example')
self.assertEqual(
fire.Fire(tc.Underscores,
command=['underscore_function', '--underscore-arg=score']),
'score')
self.assertEqual(
fire.Fire(tc.Underscores,
command=['underscore_function', '--underscore_arg=score']),
'score')
def testBoolParsing(self):
self.assertEqual(fire.Fire(tc.BoolConverter, command=['as-bool', 'True']),
True)
self.assertEqual(
fire.Fire(tc.BoolConverter, command=['as-bool', 'False']), False)
self.assertEqual(
fire.Fire(tc.BoolConverter, command=['as-bool', '--arg=True']), True)
self.assertEqual(
fire.Fire(tc.BoolConverter, command=['as-bool', '--arg=False']), False)
self.assertEqual(fire.Fire(tc.BoolConverter, command=['as-bool', '--arg']),
True)
self.assertEqual(
fire.Fire(tc.BoolConverter, command=['as-bool', '--noarg']), False)
def testBoolParsingContinued(self):
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', 'True', 'False']), (True, False))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '--alpha=False', '10']), (False, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '--alpha', '--beta', '10']), (True, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '--alpha', '--beta=10']), (True, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '--noalpha', '--beta']), (False, True))
self.assertEqual(
fire.Fire(tc.MixedDefaults, command=['identity', '10', '--beta']),
(10, True))
def testBoolParsingSingleHyphen(self):
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-alpha=False', '10']), (False, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-alpha', '-beta', '10']), (True, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-alpha', '-beta=10']), (True, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-noalpha', '-beta']), (False, True))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-alpha', '-10', '-beta']), (-10, True))
def testBoolParsingLessExpectedCases(self):
# Note: Does not return (True, 10).
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '--alpha', '10']), (10, '0'))
# To get (True, 10), use one of the following:
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '--alpha', '--beta=10']),
(True, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', 'True', '10']), (True, 10))
# Note: Does not return (True, '--test') or ('--test', 0).
with self.assertRaisesFireExit(2):
fire.Fire(tc.MixedDefaults, command=['identity', '--alpha', '--test'])
self.assertEqual(
fire.Fire(
tc.MixedDefaults,
command=['identity', '--alpha', 'True', '"--test"']),
(True, '--test'))
# To get ('--test', '0'), use one of the following:
self.assertEqual(fire.Fire(tc.MixedDefaults,
command=['identity', '--alpha=--test']),
('--test', '0'))
self.assertEqual(
fire.Fire(tc.MixedDefaults, command=r'identity --alpha \"--test\"'),
('--test', '0'))
def testSingleCharFlagParsing(self):
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a']), (True, '0'))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a', '--beta=10']), (True, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a', '-b']), (True, True))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a', '42', '-b']), (42, True))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a', '42', '-b', '10']), (42, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '--alpha', 'True', '-b', '10']),
(True, 10))
with self.assertRaisesFireExit(2):
# This test attempts to use an ambiguous shortcut flag on a function with
# a naming conflict for the shortcut, triggering a FireError.
fire.Fire(tc.SimilarArgNames, command=['identity', '-b'])
def testSingleCharFlagParsingEqualSign(self):
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a=True']), (True, '0'))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a=3', '--beta=10']), (3, 10))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a=False', '-b=15']), (False, 15))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a', '42', '-b=12']), (42, 12))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-a=42', '-b', '10']), (42, 10))
def testSingleCharFlagParsingExactMatch(self):
self.assertEqual(
fire.Fire(tc.SimilarArgNames,
command=['identity2', '-a']), (True, None))
self.assertEqual(
fire.Fire(tc.SimilarArgNames,
command=['identity2', '-a=10']), (10, None))
self.assertEqual(
fire.Fire(tc.SimilarArgNames,
command=['identity2', '--a']), (True, None))
self.assertEqual(
fire.Fire(tc.SimilarArgNames,
command=['identity2', '-alpha']), (None, True))
self.assertEqual(
fire.Fire(tc.SimilarArgNames,
command=['identity2', '-a', '-alpha']), (True, True))
def testSingleCharFlagParsingCapitalLetter(self):
self.assertEqual(
fire.Fire(tc.CapitalizedArgNames,
command=['sum', '-D', '5', '-G', '10']), 15)
def testBoolParsingWithNo(self):
# In these examples --nothing always refers to the nothing argument:
def fn1(thing, nothing):
return thing, nothing
self.assertEqual(fire.Fire(fn1, command=['--thing', '--nothing']),
(True, True))
self.assertEqual(fire.Fire(fn1, command=['--thing', '--nonothing']),
(True, False))
with self.assertRaisesFireExit(2):
# In this case nothing=False (since rightmost setting of a flag gets
# precedence), but it errors because thing has no value.
fire.Fire(fn1, command=['--nothing', '--nonothing'])
# In these examples, --nothing sets thing=False:
def fn2(thing, **kwargs):
return thing, kwargs
self.assertEqual(fire.Fire(fn2, command=['--thing']), (True, {}))
self.assertEqual(fire.Fire(fn2, command=['--nothing']), (False, {}))
with self.assertRaisesFireExit(2):
# In this case, nothing=True, but it errors because thing has no value.
fire.Fire(fn2, command=['--nothing=True'])
self.assertEqual(fire.Fire(fn2, command=['--nothing', '--nothing=True']),
(False, {'nothing': True}))
def fn3(arg, **kwargs):
return arg, kwargs
self.assertEqual(fire.Fire(fn3, command=['--arg=value', '--thing']),
('value', {'thing': True}))
self.assertEqual(fire.Fire(fn3, command=['--arg=value', '--nothing']),
('value', {'thing': False}))
self.assertEqual(fire.Fire(fn3, command=['--arg=value', '--nonothing']),
('value', {'nothing': False}))
def testTraceFlag(self):
with self.assertRaisesFireExit(0, 'Fire trace:\n'):
fire.Fire(tc.BoolConverter, command=['as-bool', 'True', '--', '--trace'])
with self.assertRaisesFireExit(0, 'Fire trace:\n'):
fire.Fire(tc.BoolConverter, command=['as-bool', 'True', '--', '-t'])
with self.assertRaisesFireExit(0, 'Fire trace:\n'):
fire.Fire(tc.BoolConverter, command=['--', '--trace'])
def testHelpFlag(self):
with self.assertRaisesFireExit(0):
fire.Fire(tc.BoolConverter, command=['as-bool', 'True', '--', '--help'])
with self.assertRaisesFireExit(0):
fire.Fire(tc.BoolConverter, command=['as-bool', 'True', '--', '-h'])
with self.assertRaisesFireExit(0):
fire.Fire(tc.BoolConverter, command=['--', '--help'])
def testHelpFlagAndTraceFlag(self):
with self.assertRaisesFireExit(0, 'Fire trace:\n.*SYNOPSIS'):
fire.Fire(tc.BoolConverter,
command=['as-bool', 'True', '--', '--help', '--trace'])
with self.assertRaisesFireExit(0, 'Fire trace:\n.*SYNOPSIS'):
fire.Fire(tc.BoolConverter, command=['as-bool', 'True', '--', '-h', '-t'])
with self.assertRaisesFireExit(0, 'Fire trace:\n.*SYNOPSIS'):
fire.Fire(tc.BoolConverter, command=['--', '-h', '--trace'])
def testTabCompletionNoName(self):
completion_script = fire.Fire(tc.NoDefaults, command=['--', '--completion'])
self.assertIn('double', completion_script)
self.assertIn('triple', completion_script)
def testTabCompletion(self):
completion_script = fire.Fire(
tc.NoDefaults, command=['--', '--completion'], name='c')
self.assertIn('double', completion_script)
self.assertIn('triple', completion_script)
def testTabCompletionWithDict(self):
actions = {'multiply': lambda a, b: a * b}
completion_script = fire.Fire(
actions, command=['--', '--completion'], name='actCLI')
self.assertIn('actCLI', completion_script)
self.assertIn('multiply', completion_script)
def testBasicSeparator(self):
# '-' is the default separator.
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '+', '_']), ('+', '_'))
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '_', '+', '-']), ('_', '+'))
# If we change the separator we can use '-' as an argument.
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['identity', '-', '_', '--', '--separator', '&']),
('-', '_'))
# The separator triggers a function call, but there aren't enough arguments.
with self.assertRaisesFireExit(2):
fire.Fire(tc.MixedDefaults, command=['identity', '-', '_', '+'])
def testNonComparable(self):
"""Fire should work with classes that disallow comparisons."""
# Make sure this test passes both with a string command or a list command.
self.assertIsInstance(
fire.Fire(tc.NonComparable, command=''), tc.NonComparable)
self.assertIsInstance(
fire.Fire(tc.NonComparable, command=[]), tc.NonComparable)
# The first separator instantiates the NonComparable object.
# The second separator causes Fire to check if the separator was necessary.
self.assertIsInstance(
fire.Fire(tc.NonComparable, command=['-', '-']), tc.NonComparable)
def testExtraSeparators(self):
self.assertEqual(
fire.Fire(
tc.ReturnsObj,
command=['get-obj', 'arg1', 'arg2', '-', '-', 'as-bool', 'True']),
True)
self.assertEqual(
fire.Fire(
tc.ReturnsObj,
command=['get-obj', 'arg1', 'arg2', '-', '-', '-', 'as-bool',
'True']),
True)
def testSeparatorForChaining(self):
# Without a separator all args are consumed by get_obj.
self.assertIsInstance(
fire.Fire(tc.ReturnsObj,
command=['get-obj', 'arg1', 'arg2', 'as-bool', 'True']),
tc.BoolConverter)
# With a separator only the preceding args are consumed by get_obj.
self.assertEqual(
fire.Fire(
tc.ReturnsObj,
command=['get-obj', 'arg1', 'arg2', '-', 'as-bool', 'True']), True)
self.assertEqual(
fire.Fire(tc.ReturnsObj,
command=['get-obj', 'arg1', 'arg2', '&', 'as-bool', 'True',
'--', '--separator', '&']),
True)
self.assertEqual(
fire.Fire(tc.ReturnsObj,
command=['get-obj', 'arg1', '$$', 'as-bool', 'True', '--',
'--separator', '$$']),
True)
def testNegativeNumbers(self):
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['sum', '--alpha', '-3', '--beta', '-4']), -11)
def testFloatForExpectedInt(self):
self.assertEqual(
fire.Fire(tc.MixedDefaults,
command=['sum', '--alpha', '2.2', '--beta', '3.0']), 8.2)
self.assertEqual(
fire.Fire(
tc.NumberDefaults,
command=['integer_reciprocal', '--divisor', '5.0']), 0.2)
self.assertEqual(
fire.Fire(tc.NumberDefaults, command=['integer_reciprocal', '4.0']),
0.25)
def testClassInstantiation(self):
self.assertIsInstance(fire.Fire(tc.InstanceVars,
command=['--arg1=a1', '--arg2=a2']),
tc.InstanceVars)
with self.assertRaisesFireExit(2):
# Cannot instantiate a class with positional args.
fire.Fire(tc.InstanceVars, command=['a1', 'a2'])
def testTraceErrors(self):
# Class needs additional value but runs out of args.
with self.assertRaisesFireExit(2):
fire.Fire(tc.InstanceVars, command=['a1'])
with self.assertRaisesFireExit(2):
fire.Fire(tc.InstanceVars, command=['--arg1=a1'])
# Routine needs additional value but runs out of args.
with self.assertRaisesFireExit(2):
fire.Fire(tc.InstanceVars, command=['a1', 'a2', '-', 'run', 'b1'])
with self.assertRaisesFireExit(2):
fire.Fire(tc.InstanceVars,
command=['--arg1=a1', '--arg2=a2', '-', 'run b1'])
# Extra args cannot be consumed.
with self.assertRaisesFireExit(2):
fire.Fire(tc.InstanceVars,
command=['a1', 'a2', '-', 'run', 'b1', 'b2', 'b3'])
with self.assertRaisesFireExit(2):
fire.Fire(
tc.InstanceVars,
command=['--arg1=a1', '--arg2=a2', '-', 'run', 'b1', 'b2', 'b3'])
# Cannot find member to access.
with self.assertRaisesFireExit(2):
fire.Fire(tc.InstanceVars, command=['a1', 'a2', '-', 'jog'])
with self.assertRaisesFireExit(2):
fire.Fire(tc.InstanceVars, command=['--arg1=a1', '--arg2=a2', '-', 'jog'])
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/formatting.py 0000664 0000000 0000000 00000003527 13520106167 0017437 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Formatting utilities for use in creating help text."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import termcolor
def Indent(text, spaces=2):
lines = text.split('\n')
return '\n'.join(
' ' * spaces + line if line else line
for line in lines)
def Bold(text):
return termcolor.colored(text, attrs=['bold'])
def Underline(text):
return termcolor.colored(text, attrs=['underline'])
def BoldUnderline(text):
return Bold(Underline(text))
def WrappedJoin(items, separator=' | ', width=80):
"""Joins the items by the separator, wrapping lines at the given width."""
lines = []
current_line = ''
for index, item in enumerate(items):
is_final_item = index == len(items) - 1
if is_final_item:
if len(current_line) + len(item) <= width:
current_line += item
else:
lines.append(current_line.rstrip())
current_line = item
else:
if len(current_line) + len(item) + len(separator) <= width:
current_line += item + separator
else:
lines.append(current_line.rstrip())
current_line = item + separator
lines.append(current_line)
return lines
def Error(text):
return termcolor.colored(text, color='red', attrs=['bold'])
python-fire-0.2.1/fire/formatting_test.py 0000664 0000000 0000000 00000003320 13520106167 0020465 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for formatting.py."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import formatting
from fire import testutils
class FormattingTest(testutils.BaseTestCase):
def test_bold(self):
text = formatting.Bold('hello')
self.assertEqual('\x1b[1mhello\x1b[0m', text)
def test_underline(self):
text = formatting.Underline('hello')
self.assertEqual('\x1b[4mhello\x1b[0m', text)
def test_indent(self):
text = formatting.Indent('hello', spaces=2)
self.assertEqual(' hello', text)
def test_indent_multiple_lines(self):
text = formatting.Indent('hello\nworld', spaces=2)
self.assertEqual(' hello\n world', text)
def test_wrap_one_item(self):
lines = formatting.WrappedJoin(['rice'])
self.assertEqual(['rice'], lines)
def test_wrap_multiple_items(self):
lines = formatting.WrappedJoin(['rice', 'beans', 'chicken', 'cheese'],
width=15)
self.assertEqual(['rice | beans |',
'chicken |',
'cheese'], lines)
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/helptext.py 0000664 0000000 0000000 00000051053 13520106167 0017117 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Utilities for producing help strings for use in Fire CLIs.
Can produce help strings suitable for display in Fire CLIs for any type of
Python object, module, class, or function.
There are two types of informative strings: Usage and Help screens.
Usage screens are shown when the user accesses a group or accesses a command
without calling it. A Usage screen shows information about how to use that group
or command. Usage screens are typically short and show the minimal information
necessary for the user to determine how to proceed.
Help screens are shown when the user requests help with the help flag (--help).
Help screens are shown in a less-style console view, and contain detailed help
information.
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import completion
from fire import custom_descriptions
from fire import decorators
from fire import formatting
from fire import inspectutils
from fire import value_types
LINE_LENGTH = 80
def HelpText(component, trace=None, verbose=False):
"""Gets the help string for the current component, suitalbe for a help screen.
Args:
component: The component to construct the help string for.
trace: The Fire trace of the command so far. The command executed so far
can be extracted from this trace.
verbose: Whether to include private members in the help screen.
Returns:
The full help screen as a string.
"""
# Preprocessing needed to create the sections:
info = inspectutils.Info(component)
actions_grouped_by_kind = _GetActionsGroupedByKind(component, verbose=verbose)
spec = inspectutils.GetFullArgSpec(component)
metadata = decorators.GetMetadata(component)
# Sections:
name_section = _NameSection(component, info, trace=trace, verbose=verbose)
synopsis_section = _SynopsisSection(
component, actions_grouped_by_kind, spec, metadata, trace=trace)
description_section = _DescriptionSection(component, info)
# TODO(dbieber): Add returns and raises sections for functions.
if callable(component):
args_and_flags_sections, notes_sections = _ArgsAndFlagsSections(
info, spec, metadata)
else:
args_and_flags_sections = []
notes_sections = []
usage_details_sections = _UsageDetailsSections(component,
actions_grouped_by_kind)
sections = (
[name_section, synopsis_section, description_section]
+ args_and_flags_sections
+ usage_details_sections
+ notes_sections
)
return '\n\n'.join(
_CreateOutputSection(*section)
for section in sections if section is not None
)
def _NameSection(component, info, trace=None, verbose=False):
"""The "Name" section of the help string."""
# Only include separators in the name in verbose mode.
current_command = _GetCurrentCommand(trace, include_separators=verbose)
summary = _GetSummary(info)
# If the docstring is one of the messy builtin docstrings, don't show summary.
# TODO(dbieber): In follow up commits we can add in replacement summaries.
if custom_descriptions.NeedsCustomDescription(component):
summary = None
if summary:
text = current_command + ' - ' + summary
else:
text = current_command
return ('NAME', text)
def _SynopsisSection(component, actions_grouped_by_kind, spec, metadata,
trace=None):
"""The "Synopsis" section of the help string."""
current_command = _GetCurrentCommand(trace=trace, include_separators=True)
possible_actions = _GetPossibleActions(actions_grouped_by_kind)
continuations = []
if possible_actions:
continuations.append(_GetPossibleActionsString(possible_actions))
if callable(component):
callable_continuation = _GetArgsAndFlagsString(spec, metadata)
if callable_continuation:
continuations.append(callable_continuation)
elif trace:
# This continuation might be blank if no args are needed.
# In this case, show a separator.
continuations.append(trace.separator)
continuation = ' | '.join(continuations)
synopsis_template = '{current_command} {continuation}'
text = synopsis_template.format(
current_command=current_command,
continuation=continuation)
return ('SYNOPSIS', text)
def _DescriptionSection(component, info):
"""The "Description" sections of the help string.
Args:
component: The component to produce the description section for.
info: The info dict for the component of interest.
Returns:
Returns the description if available. If not, returns the summary.
If neither are available, returns None.
"""
# If the docstring is one of the messy builtin docstrings, set it to None.
# TODO(dbieber): In follow up commits we can add in replacement docstrings.
if custom_descriptions.NeedsCustomDescription(component):
return None
summary = _GetSummary(info)
description = _GetDescription(info)
text = description or summary or None
if text:
return ('DESCRIPTION', text)
else:
return None
def _ArgsAndFlagsSections(info, spec, metadata):
"""The "Args and Flags" sections of the help string."""
args_with_no_defaults = spec.args[:len(spec.args) - len(spec.defaults)]
args_with_defaults = spec.args[len(spec.args) - len(spec.defaults):]
# Check if positional args are allowed. If not, require flag syntax for args.
accepts_positional_args = metadata.get(decorators.ACCEPTS_POSITIONAL_ARGS)
args_and_flags_sections = []
notes_sections = []
docstring_info = info['docstring_info']
arg_items = [
_CreateArgItem(arg, docstring_info)
for arg in args_with_no_defaults
]
if spec.varargs:
arg_items.append(
_CreateArgItem(spec.varargs, docstring_info)
)
if arg_items:
title = 'POSITIONAL ARGUMENTS' if accepts_positional_args else 'ARGUMENTS'
arguments_section = (title, '\n'.join(arg_items).rstrip('\n'))
args_and_flags_sections.append(arguments_section)
if args_with_no_defaults and accepts_positional_args:
notes_sections.append(
('NOTES', 'You can also use flags syntax for POSITIONAL ARGUMENTS')
)
optional_flag_items = [
_CreateFlagItem(flag, docstring_info, required=False)
for flag in args_with_defaults
]
required_flag_items = [
_CreateFlagItem(flag, docstring_info, required=True)
for flag in spec.kwonlyargs
]
flag_items = optional_flag_items + required_flag_items
if spec.varkw:
description = _GetArgDescription(spec.varkw, docstring_info)
message = ('Additional flags are accepted.'
if flag_items else
'Flags are accepted.')
item = _CreateItem(message, description, indent=4)
flag_items.append(item)
if flag_items:
flags_section = ('FLAGS', '\n'.join(flag_items))
args_and_flags_sections.append(flags_section)
return args_and_flags_sections, notes_sections
def _UsageDetailsSections(component, actions_grouped_by_kind):
"""The usage details sections of the help string."""
groups, commands, values, indexes = actions_grouped_by_kind
sections = []
if groups.members:
sections.append(_MakeUsageDetailsSection(groups))
if commands.members:
sections.append(_MakeUsageDetailsSection(commands))
if values.members:
sections.append(_ValuesUsageDetailsSection(component, values))
if indexes.members:
sections.append(('INDEXES', _NewChoicesSection('INDEX', indexes.names)))
return sections
def _GetSummary(info):
docstring_info = info['docstring_info']
return docstring_info.summary if docstring_info.summary else None
def _GetDescription(info):
docstring_info = info['docstring_info']
return docstring_info.description if docstring_info.description else None
def _GetArgsAndFlagsString(spec, metadata):
"""The args and flags string for showing how to call a function.
If positional arguments are accepted, the args will be shown as positional.
E.g. "ARG1 ARG2 [--flag=FLAG]"
If positional arguments are disallowed, the args will be shown with flags
syntax.
E.g. "--arg1=ARG1 [--flag=FLAG]"
Args:
spec: The full arg spec for the component to construct the args and flags
string for.
metadata: Metadata for the component, including whether it accepts
positional arguments.
Returns:
The constructed args and flags string.
"""
args_with_no_defaults = spec.args[:len(spec.args) - len(spec.defaults)]
args_with_defaults = spec.args[len(spec.args) - len(spec.defaults):]
# Check if positional args are allowed. If not, require flag syntax for args.
accepts_positional_args = metadata.get(decorators.ACCEPTS_POSITIONAL_ARGS)
arg_and_flag_strings = []
if args_with_no_defaults:
if accepts_positional_args:
arg_strings = [formatting.Underline(arg.upper())
for arg in args_with_no_defaults]
else:
arg_strings = [
'--{arg}={arg_upper}'.format(
arg=arg, arg_upper=formatting.Underline(arg.upper()))
for arg in args_with_no_defaults]
arg_and_flag_strings.extend(arg_strings)
# If there are any arguments that are treated as flags:
if args_with_defaults or spec.kwonlyargs or spec.varkw:
arg_and_flag_strings.append('')
if spec.varargs:
varargs_string = '[{varargs}]...'.format(
varargs=formatting.Underline(spec.varargs.upper()))
arg_and_flag_strings.append(varargs_string)
return ' '.join(arg_and_flag_strings)
def _GetPossibleActions(actions_grouped_by_kind):
"""The list of possible action kinds."""
possible_actions = []
for action_group in actions_grouped_by_kind:
if action_group.members:
possible_actions.append(action_group.name)
return possible_actions
def _GetPossibleActionsString(possible_actions):
"""A help screen string listing the possible action kinds available."""
return ' | '.join(formatting.Underline(action.upper())
for action in possible_actions)
def _GetActionsGroupedByKind(component, verbose=False):
"""Gets lists of available actions, grouped by action kind."""
groups = ActionGroup(name='group', plural='groups')
commands = ActionGroup(name='command', plural='commands')
values = ActionGroup(name='value', plural='values')
indexes = ActionGroup(name='index', plural='indexes')
members = completion.VisibleMembers(component, verbose=verbose)
for member_name, member in members:
member_name = str(member_name)
if value_types.IsGroup(member):
groups.Add(name=member_name, member=member)
if value_types.IsCommand(member):
commands.Add(name=member_name, member=member)
if value_types.IsValue(member):
values.Add(name=member_name, member=member)
if isinstance(component, (list, tuple)) and component:
component_len = len(component)
if component_len < 10:
indexes.Add(name=', '.join(str(x) for x in range(component_len)))
else:
indexes.Add(name='0..{max}'.format(max=component_len-1))
return [groups, commands, values, indexes]
def _GetCurrentCommand(trace=None, include_separators=True):
"""Returns current command for the purpose of generating help text."""
if trace:
current_command = trace.GetCommand(include_separators=include_separators)
else:
current_command = ''
return current_command
def _CreateOutputSection(name, content):
return """{name}
{content}""".format(name=formatting.Bold(name),
content=formatting.Indent(content, 4))
def _CreateArgItem(arg, docstring_info):
"""Returns a string describing a positional argument.
Args:
arg: The name of the positional argument.
docstring_info: A docstrings.DocstringInfo namedtuple with information about
the containing function's docstring.
Returns:
A string to be used in constructing the help screen for the function.
"""
description = _GetArgDescription(arg, docstring_info)
arg = arg.upper()
return _CreateItem(formatting.BoldUnderline(arg), description, indent=4)
def _CreateFlagItem(flag, docstring_info, required=False):
"""Returns a string describing a flag using information from the docstring.
Args:
flag: The name of the flag.
docstring_info: A docstrings.DocstringInfo namedtuple with information about
the containing function's docstring.
required: Whether the flag is required. Keyword-only arguments (only in
Python 3) become required flags, whereas normal keyword arguments become
optional flags.
Returns:
A string to be used in constructing the help screen for the function.
"""
description = _GetArgDescription(flag, docstring_info)
flag_string_template = '--{flag_name}={flag_name_upper}'
flag = flag_string_template.format(
flag_name=flag,
flag_name_upper=formatting.Underline(flag.upper()))
if required:
flag += ' (required)'
return _CreateItem(flag, description, indent=4)
def _CreateItem(name, description, indent=2):
if not description:
return name
return """{name}
{description}""".format(name=name,
description=formatting.Indent(description, indent))
def _GetArgDescription(name, docstring_info):
if docstring_info.args:
for arg_in_docstring in docstring_info.args:
if arg_in_docstring.name in (name, '*' + name, '**' + name):
return arg_in_docstring.description
return None
def _MakeUsageDetailsSection(action_group):
"""Creates a usage details section for the provided action group."""
item_strings = []
for name, member in action_group.GetItems():
info = inspectutils.Info(member)
item = name
docstring_info = info.get('docstring_info')
if (docstring_info
and not custom_descriptions.NeedsCustomDescription(member)):
summary = docstring_info.summary
else:
summary = None
item = _CreateItem(name, summary)
item_strings.append(item)
return (action_group.plural.upper(),
_NewChoicesSection(action_group.name.upper(), item_strings))
def _ValuesUsageDetailsSection(component, values):
"""Creates a section tuple for the values section of the usage details."""
value_item_strings = []
for value_name, value in values.GetItems():
del value
init_info = inspectutils.Info(component.__class__.__init__)
value_item = None
if 'docstring_info' in init_info:
init_docstring_info = init_info['docstring_info']
if init_docstring_info.args:
for arg_info in init_docstring_info.args:
if arg_info.name == value_name:
value_item = _CreateItem(value_name, arg_info.description)
if value_item is None:
value_item = str(value_name)
value_item_strings.append(value_item)
return ('VALUES', _NewChoicesSection('VALUE', value_item_strings))
def _NewChoicesSection(name, choices):
return _CreateItem(
'{name} is one of the following:'.format(
name=formatting.Bold(formatting.Underline(name))),
'\n' + '\n\n'.join(choices),
indent=1)
def UsageText(component, trace=None, verbose=False):
"""Returns usage text for the given component.
Args:
component: The component to determine the usage text for.
trace: The Fire trace object containing all metadata of current execution.
verbose: Whether to display the usage text in verbose mode.
Returns:
String suitable for display in an error screen.
"""
output_template = """Usage: {continued_command}
{availability_lines}
For detailed information on this command, run:
{help_command}"""
# Get the command so far:
if trace:
command = trace.GetCommand()
needs_separating_hyphen_hyphen = trace.NeedsSeparatingHyphenHyphen()
else:
command = None
needs_separating_hyphen_hyphen = False
if not command:
command = ''
# Build the continuations for the command:
continued_command = command
spec = inspectutils.GetFullArgSpec(component)
metadata = decorators.GetMetadata(component)
# Usage for objects.
actions_grouped_by_kind = _GetActionsGroupedByKind(component, verbose=verbose)
possible_actions = _GetPossibleActions(actions_grouped_by_kind)
continuations = []
if possible_actions:
continuations.append(_GetPossibleActionsUsageString(possible_actions))
availability_lines = _UsageAvailabilityLines(actions_grouped_by_kind)
if callable(component):
callable_items = _GetCallableUsageItems(spec, metadata)
if callable_items:
continuations.append(' '.join(callable_items))
elif trace:
continuations.append(trace.separator)
availability_lines.extend(_GetCallableAvailabilityLines(spec))
if continuations:
continued_command += ' ' + ' | '.join(continuations)
help_command = (
command
+ (' -- ' if needs_separating_hyphen_hyphen else ' ')
+ '--help'
)
return output_template.format(
continued_command=continued_command,
availability_lines=''.join(availability_lines),
help_command=help_command)
def _GetPossibleActionsUsageString(possible_actions):
if possible_actions:
return '<{actions}>'.format(actions='|'.join(possible_actions))
return None
def _UsageAvailabilityLines(actions_grouped_by_kind):
availability_lines = []
for action_group in actions_grouped_by_kind:
if action_group.members:
availability_line = _CreateAvailabilityLine(
header='available {plural}:'.format(plural=action_group.plural),
items=action_group.names
)
availability_lines.append(availability_line)
return availability_lines
def _GetCallableUsageItems(spec, metadata):
"""A list of elements that comprise the usage summary for a callable."""
args_with_no_defaults = spec.args[:len(spec.args) - len(spec.defaults)]
args_with_defaults = spec.args[len(spec.args) - len(spec.defaults):]
# Check if positional args are allowed. If not, show flag syntax for args.
accepts_positional_args = metadata.get(decorators.ACCEPTS_POSITIONAL_ARGS)
if not accepts_positional_args:
items = ['--{arg}={upper}'.format(arg=arg, upper=arg.upper())
for arg in args_with_no_defaults]
else:
items = [arg.upper() for arg in args_with_no_defaults]
# If there are any arguments that are treated as flags:
if args_with_defaults or spec.kwonlyargs or spec.varkw:
items.append('')
if spec.varargs:
items.append('[{varargs}]...'.format(varargs=spec.varargs.upper()))
return items
def _GetCallableAvailabilityLines(spec):
"""The list of availability lines for a callable for use in a usage string."""
args_with_defaults = spec.args[len(spec.args) - len(spec.defaults):]
# TODO(dbieber): Handle args_with_no_defaults if not accepts_positional_args.
optional_flags = [('--' + flag) for flag in args_with_defaults]
required_flags = [('--' + flag) for flag in spec.kwonlyargs]
# Flags section:
availability_lines = []
if optional_flags:
availability_lines.append(
_CreateAvailabilityLine(header='optional flags:', items=optional_flags,
header_indent=2))
if required_flags:
availability_lines.append(
_CreateAvailabilityLine(header='required flags:', items=required_flags,
header_indent=2))
if spec.varkw:
additional_flags = ('additional flags are accepted'
if optional_flags or required_flags else
'flags are accepted')
availability_lines.append(
_CreateAvailabilityLine(header=additional_flags, items=[],
header_indent=2))
return availability_lines
def _CreateAvailabilityLine(header, items,
header_indent=2, items_indent=25,
line_length=LINE_LENGTH):
items_width = line_length - items_indent
items_text = '\n'.join(formatting.WrappedJoin(items, width=items_width))
indented_items_text = formatting.Indent(items_text, spaces=items_indent)
indented_header = formatting.Indent(header, spaces=header_indent)
return indented_header + indented_items_text[len(indented_header):] + '\n'
class ActionGroup(object):
"""A group of actions of the same kind."""
def __init__(self, name, plural):
self.name = name
self.plural = plural
self.names = []
self.members = []
def Add(self, name, member=None):
self.names.append(name)
self.members.append(member)
def GetItems(self):
return zip(self.names, self.members)
python-fire-0.2.1/fire/helptext_test.py 0000664 0000000 0000000 00000037070 13520106167 0020161 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for the helptext module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import os
import textwrap
from fire import formatting
from fire import helptext
from fire import test_components as tc
from fire import testutils
from fire import trace
class HelpTest(testutils.BaseTestCase):
def setUp(self):
super(HelpTest, self).setUp()
os.environ['ANSI_COLORS_DISABLED'] = '1'
def testHelpTextNoDefaults(self):
component = tc.NoDefaults
help_screen = helptext.HelpText(
component=component,
trace=trace.FireTrace(component, name='NoDefaults'))
self.assertIn('NAME\n NoDefaults', help_screen)
self.assertIn('SYNOPSIS\n NoDefaults', help_screen)
self.assertNotIn('DESCRIPTION', help_screen)
self.assertNotIn('NOTES', help_screen)
def testHelpTextNoDefaultsObject(self):
component = tc.NoDefaults()
help_screen = helptext.HelpText(
component=component,
trace=trace.FireTrace(component, name='NoDefaults'))
self.assertIn('NAME\n NoDefaults', help_screen)
self.assertIn('SYNOPSIS\n NoDefaults COMMAND', help_screen)
self.assertNotIn('DESCRIPTION', help_screen)
self.assertIn('COMMANDS\n COMMAND is one of the following:',
help_screen)
self.assertIn('double', help_screen)
self.assertIn('triple', help_screen)
self.assertNotIn('NOTES', help_screen)
def testHelpTextFunction(self):
component = tc.NoDefaults().double
help_screen = helptext.HelpText(
component=component,
trace=trace.FireTrace(component, name='double'))
self.assertIn('NAME\n double', help_screen)
self.assertIn('SYNOPSIS\n double COUNT', help_screen)
self.assertNotIn('DESCRIPTION', help_screen)
self.assertIn('POSITIONAL ARGUMENTS\n COUNT', help_screen)
self.assertIn(
'NOTES\n You can also use flags syntax for POSITIONAL ARGUMENTS',
help_screen)
def testHelpTextFunctionWithDefaults(self):
component = tc.WithDefaults().triple
help_screen = helptext.HelpText(
component=component,
trace=trace.FireTrace(component, name='triple'))
self.assertIn('NAME\n triple', help_screen)
self.assertIn('SYNOPSIS\n triple ', help_screen)
self.assertNotIn('DESCRIPTION', help_screen)
self.assertIn('FLAGS\n --count=COUNT', help_screen)
self.assertNotIn('NOTES', help_screen)
def testHelpTextFunctionWithBuiltin(self):
component = 'test'.upper
help_screen = helptext.HelpText(
component=component,
trace=trace.FireTrace(component, 'upper'))
self.assertIn('NAME\n upper', help_screen)
self.assertIn('SYNOPSIS\n upper', help_screen)
# We don't check description content here since the content is python
# version dependent.
self.assertIn('DESCRIPTION\n', help_screen)
self.assertNotIn('NOTES', help_screen)
def testHelpTextFunctionIntType(self):
component = int
help_screen = helptext.HelpText(
component=component, trace=trace.FireTrace(component, 'int'))
self.assertIn('NAME\n int', help_screen)
self.assertIn('SYNOPSIS\n int', help_screen)
# We don't check description content here since the content is python
# version dependent.
self.assertIn('DESCRIPTION\n', help_screen)
def testHelpTextEmptyList(self):
component = []
help_screen = helptext.HelpText(
component=component,
trace=trace.FireTrace(component, 'list'))
self.assertIn('NAME\n list', help_screen)
self.assertIn('SYNOPSIS\n list COMMAND', help_screen)
# The list docstring is messy, so it is not shown.
self.assertNotIn('DESCRIPTION', help_screen)
# We don't check the listed commands either since the list API could
# potentially change between Python versions.
self.assertIn('COMMANDS\n COMMAND is one of the following:\n',
help_screen)
def testHelpTextShortList(self):
component = [10]
help_screen = helptext.HelpText(
component=component,
trace=trace.FireTrace(component, 'list'))
self.assertIn('NAME\n list', help_screen)
self.assertIn('SYNOPSIS\n list COMMAND', help_screen)
# The list docstring is messy, so it is not shown.
self.assertNotIn('DESCRIPTION', help_screen)
# We don't check the listed commands comprehensively since the list API
# could potentially change between Python versions. Check a few
# functions(command) that we're confident likely remain available.
self.assertIn('COMMANDS\n COMMAND is one of the following:\n',
help_screen)
self.assertIn(' append\n', help_screen)
def testHelpTextInt(self):
component = 7
help_screen = helptext.HelpText(
component=component, trace=trace.FireTrace(component, '7'))
self.assertIn('NAME\n 7', help_screen)
self.assertIn('SYNOPSIS\n 7 COMMAND | VALUE', help_screen)
# The int docstring is messy, so it is not shown.
self.assertNotIn('DESCRIPTION', help_screen)
self.assertIn('COMMANDS\n COMMAND is one of the following:\n',
help_screen)
self.assertIn('VALUES\n VALUE is one of the following:\n', help_screen)
def testHelpTextNoInit(self):
component = tc.OldStyleEmpty
help_screen = helptext.HelpText(
component=component,
trace=trace.FireTrace(component, 'OldStyleEmpty'))
self.assertIn('NAME\n OldStyleEmpty', help_screen)
self.assertIn('SYNOPSIS\n OldStyleEmpty', help_screen)
def testHelpScreen(self):
component = tc.ClassWithDocstring()
t = trace.FireTrace(component, name='ClassWithDocstring')
help_output = helptext.HelpText(component, t)
expected_output = """
NAME
ClassWithDocstring - Test class for testing help text output.
SYNOPSIS
ClassWithDocstring COMMAND | VALUE
DESCRIPTION
This is some detail description of this test class.
COMMANDS
COMMAND is one of the following:
print_msg
Prints a message.
VALUES
VALUE is one of the following:
message
The default message to print."""
self.assertEqual(textwrap.dedent(expected_output).strip(),
help_output.strip())
def testHelpScreenForFunctionDocstringWithLineBreak(self):
component = tc.ClassWithMultilineDocstring.example_generator
t = trace.FireTrace(component, name='example_generator')
help_output = helptext.HelpText(component, t)
expected_output = """
NAME
example_generator - Generators have a ``Yields`` section instead of a ``Returns`` section.
SYNOPSIS
example_generator N
DESCRIPTION
Generators have a ``Yields`` section instead of a ``Returns`` section.
POSITIONAL ARGUMENTS
N
The upper limit of the range to generate, from 0 to `n` - 1.
NOTES
You can also use flags syntax for POSITIONAL ARGUMENTS"""
self.assertEqual(textwrap.dedent(expected_output).strip(),
help_output.strip())
def testHelpScreenForFunctionFunctionWithDefaultArgs(self):
component = tc.WithDefaults().double
t = trace.FireTrace(component, name='double')
help_output = helptext.HelpText(component, t)
expected_output = """
NAME
double - Returns the input multiplied by 2.
SYNOPSIS
double
DESCRIPTION
Returns the input multiplied by 2.
FLAGS
--count=COUNT
Input number that you want to double."""
self.assertEqual(textwrap.dedent(expected_output).strip(),
help_output.strip())
def testHelpTextUnderlineFlag(self):
component = tc.WithDefaults().triple
t = trace.FireTrace(component, name='triple')
help_screen = helptext.HelpText(component, t)
self.assertIn(formatting.Bold('NAME') + '\n triple', help_screen)
self.assertIn(
formatting.Bold('SYNOPSIS') + '\n triple ',
help_screen)
self.assertIn(
formatting.Bold('FLAGS') + '\n --' + formatting.Underline('count'),
help_screen)
def testHelpTextBoldCommandName(self):
component = tc.ClassWithDocstring()
t = trace.FireTrace(component, name='ClassWithDocstring')
help_screen = helptext.HelpText(component, t)
self.assertIn(
formatting.Bold('NAME') + '\n ClassWithDocstring', help_screen)
self.assertIn(formatting.Bold('COMMANDS') + '\n', help_screen)
self.assertIn(
formatting.BoldUnderline('COMMAND') + ' is one of the following:\n',
help_screen)
self.assertIn(formatting.Bold('print_msg') + '\n', help_screen)
def testHelpTextObjectWithGroupAndValues(self):
component = tc.TypedProperties()
t = trace.FireTrace(component, name='TypedProperties')
help_screen = helptext.HelpText(
component=component, trace=t, verbose=True)
print(help_screen)
self.assertIn('GROUPS', help_screen)
self.assertIn('GROUP is one of the following:', help_screen)
self.assertIn(
'charlie\n Class with functions that have default arguments.',
help_screen)
self.assertIn('VALUES', help_screen)
self.assertIn('VALUE is one of the following:', help_screen)
self.assertIn('alpha', help_screen)
def testHelpTextNameSectionCommandWithSeparator(self):
component = 9
t = trace.FireTrace(component, name='int', separator='-')
t.AddSeparator()
help_screen = helptext.HelpText(component=component, trace=t, verbose=False)
self.assertIn('int -', help_screen)
self.assertNotIn('int - -', help_screen)
def testHelpTextNameSectionCommandWithSeparatorVerbose(self):
component = tc.WithDefaults().double
t = trace.FireTrace(component, name='double', separator='-')
t.AddSeparator()
help_screen = helptext.HelpText(component=component, trace=t, verbose=True)
self.assertIn('double -', help_screen)
self.assertIn('double - -', help_screen)
class UsageTest(testutils.BaseTestCase):
def testUsageOutput(self):
component = tc.NoDefaults()
t = trace.FireTrace(component, name='NoDefaults')
usage_output = helptext.UsageText(component, trace=t, verbose=False)
expected_output = """
Usage: NoDefaults
available commands: double | triple
For detailed information on this command, run:
NoDefaults --help"""
self.assertEqual(
usage_output,
textwrap.dedent(expected_output).lstrip('\n'))
def testUsageOutputVerbose(self):
component = tc.NoDefaults()
t = trace.FireTrace(component, name='NoDefaults')
usage_output = helptext.UsageText(component, trace=t, verbose=True)
expected_output = """
Usage: NoDefaults
available commands: double | triple
For detailed information on this command, run:
NoDefaults --help"""
self.assertEqual(
usage_output,
textwrap.dedent(expected_output).lstrip('\n'))
def testUsageOutputMethod(self):
component = tc.NoDefaults().double
t = trace.FireTrace(component, name='NoDefaults')
t.AddAccessedProperty(component, 'double', ['double'], None, None)
usage_output = helptext.UsageText(component, trace=t, verbose=False)
expected_output = """
Usage: NoDefaults double COUNT
For detailed information on this command, run:
NoDefaults double --help"""
self.assertEqual(
usage_output,
textwrap.dedent(expected_output).lstrip('\n'))
def testUsageOutputFunctionWithHelp(self):
component = tc.function_with_help
t = trace.FireTrace(component, name='function_with_help')
usage_output = helptext.UsageText(component, trace=t, verbose=False)
expected_output = """
Usage: function_with_help
optional flags: --help
For detailed information on this command, run:
function_with_help -- --help"""
self.assertEqual(
usage_output,
textwrap.dedent(expected_output).lstrip('\n'))
def testUsageOutputFunctionWithDocstring(self):
component = tc.multiplier_with_docstring
t = trace.FireTrace(component, name='multiplier_with_docstring')
usage_output = helptext.UsageText(component, trace=t, verbose=False)
expected_output = """
Usage: multiplier_with_docstring NUM
optional flags: --rate
For detailed information on this command, run:
multiplier_with_docstring --help"""
self.assertEqual(
textwrap.dedent(expected_output).lstrip('\n'),
usage_output)
def testUsageOutputCallable(self):
# This is both a group and a command.
component = tc.CallableWithKeywordArgument()
t = trace.FireTrace(component, name='CallableWithKeywordArgument',
separator='@')
usage_output = helptext.UsageText(component, trace=t, verbose=False)
expected_output = """
Usage: CallableWithKeywordArgument |
available commands: print_msg
flags are accepted
For detailed information on this command, run:
CallableWithKeywordArgument -- --help"""
self.assertEqual(
textwrap.dedent(expected_output).lstrip('\n'),
usage_output)
def testUsageOutputConstructorWithParameter(self):
component = tc.InstanceVars
t = trace.FireTrace(component, name='InstanceVars')
usage_output = helptext.UsageText(component, trace=t, verbose=False)
expected_output = """
Usage: InstanceVars --arg1=ARG1 --arg2=ARG2
For detailed information on this command, run:
InstanceVars --help"""
self.assertEqual(
textwrap.dedent(expected_output).lstrip('\n'),
usage_output)
def testUsageOutputConstructorWithParameterVerbose(self):
component = tc.InstanceVars
t = trace.FireTrace(component, name='InstanceVars')
usage_output = helptext.UsageText(component, trace=t, verbose=True)
expected_output = """
Usage: InstanceVars | --arg1=ARG1 --arg2=ARG2
available commands: run
For detailed information on this command, run:
InstanceVars --help"""
self.assertEqual(
textwrap.dedent(expected_output).lstrip('\n'),
usage_output)
def testUsageOutputEmptyDict(self):
component = {}
t = trace.FireTrace(component, name='EmptyDict')
usage_output = helptext.UsageText(component, trace=t, verbose=True)
expected_output = """
Usage: EmptyDict
For detailed information on this command, run:
EmptyDict --help"""
self.assertEqual(
textwrap.dedent(expected_output).lstrip('\n'),
usage_output)
def testUsageOutputNone(self):
component = None
t = trace.FireTrace(component, name='None')
usage_output = helptext.UsageText(component, trace=t, verbose=True)
expected_output = """
Usage: None
For detailed information on this command, run:
None --help"""
self.assertEqual(
textwrap.dedent(expected_output).lstrip('\n'),
usage_output)
def testInitRequiresFlagSyntaxSubclassNamedTuple(self):
component = tc.SubPoint
t = trace.FireTrace(component, name='SubPoint')
usage_output = helptext.UsageText(component, trace=t, verbose=False)
expected_output = 'Usage: SubPoint --x=X --y=Y'
self.assertIn(expected_output, usage_output)
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/inspectutils.py 0000664 0000000 0000000 00000021704 13520106167 0020010 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Inspection utility functions for Python Fire."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import inspect
from fire import docstrings
import six
class FullArgSpec(object):
"""The arguments of a function, as in Python 3's inspect.FullArgSpec."""
def __init__(self, args=None, varargs=None, varkw=None, defaults=None,
kwonlyargs=None, kwonlydefaults=None, annotations=None):
"""Constructs a FullArgSpec with each provided attribute, or the default.
Args:
args: A list of the argument names accepted by the function.
varargs: The name of the *varargs argument or None if there isn't one.
varkw: The name of the **kwargs argument or None if there isn't one.
defaults: A tuple of the defaults for the arguments that accept defaults.
kwonlyargs: A list of argument names that must be passed with a keyword.
kwonlydefaults: A dictionary of keyword only arguments and their defaults.
annotations: A dictionary of arguments and their annotated types.
"""
self.args = args or []
self.varargs = varargs
self.varkw = varkw
self.defaults = defaults or ()
self.kwonlyargs = kwonlyargs or []
self.kwonlydefaults = kwonlydefaults or {}
self.annotations = annotations or {}
def _GetArgSpecInfo(fn):
"""Gives information pertaining to computing the ArgSpec of fn.
Determines if the first arg is supplied automatically when fn is called.
This arg will be supplied automatically if fn is a bound method or a class
with an __init__ method.
Also returns the function who's ArgSpec should be used for determining the
calling parameters for fn. This may be different from fn itself if fn is a
class with an __init__ method.
Args:
fn: The function or class of interest.
Returns:
A tuple with the following two items:
fn: The function to use for determining the arg spec of this function.
skip_arg: Whether the first argument will be supplied automatically, and
hence should be skipped when supplying args from a Fire command.
"""
skip_arg = False
if inspect.isclass(fn):
# If the function is a class, we try to use it's init method.
skip_arg = True
if six.PY2 and hasattr(fn, '__init__'):
fn = fn.__init__
elif inspect.ismethod(fn):
# If the function is a bound method, we skip the `self` argument.
skip_arg = fn.__self__ is not None
elif inspect.isbuiltin(fn):
# If the function is a bound builtin, we skip the `self` argument.
skip_arg = fn.__self__ is not None
elif not inspect.isfunction(fn):
# The purpose of this else clause is to set skip_arg for callable objects.
skip_arg = True
return fn, skip_arg
def Py2GetArgSpec(fn):
"""A wrapper around getargspec that tries both fn and fn.__call__."""
try:
return inspect.getargspec(fn) # pylint: disable=deprecated-method
except TypeError:
if hasattr(fn, '__call__'):
return inspect.getargspec(fn.__call__) # pylint: disable=deprecated-method
raise
def GetFullArgSpec(fn):
"""Returns a FullArgSpec describing the given callable."""
original_fn = fn
fn, skip_arg = _GetArgSpecInfo(fn)
try:
if six.PY2:
args, varargs, varkw, defaults = Py2GetArgSpec(fn)
kwonlyargs = kwonlydefaults = None
annotations = getattr(fn, '__annotations__', None)
else:
(args, varargs, varkw, defaults,
kwonlyargs, kwonlydefaults, annotations) = inspect.getfullargspec(fn) # pylint: disable=deprecated-method,no-member
except TypeError:
# If we can't get the argspec, how do we know if the fn should take args?
# 1. If it's a builtin, it can take args.
# 2. If it's an implicit __init__ function (a 'slot wrapper'), that comes
# from a namedtuple, use _fields to determine the args.
# 3. If it's another slot wrapper (that comes from not subclassing object in
# Python 2), then there are no args.
# Are there other cases? We just don't know.
# Case 1: Builtins accept args.
if inspect.isbuiltin(fn):
# TODO(dbieber): Try parsing the docstring, if available.
# TODO(dbieber): Use known argspecs, like set.add and namedtuple.count.
return FullArgSpec(varargs='vars', varkw='kwargs')
# Case 2: namedtuples store their args in their _fields attribute.
# TODO(dbieber): Determine if there's a way to detect false positives.
# In Python 2, a class that does not subclass anything, does not define
# __init__, and has an attribute named _fields will cause Fire to think it
# expects args for its constructor when in fact it does not.
fields = getattr(original_fn, '_fields', None)
if fields is not None:
return FullArgSpec(args=list(fields))
# Case 3: Other known slot wrappers do not accept args.
return FullArgSpec()
if skip_arg and args:
args.pop(0) # Remove 'self' or 'cls' from the list of arguments.
return FullArgSpec(args, varargs, varkw, defaults,
kwonlyargs, kwonlydefaults, annotations)
def GetFileAndLine(component):
"""Returns the filename and line number of component.
Args:
component: A component to find the source information for, usually a class
or routine.
Returns:
filename: The name of the file where component is defined.
lineno: The line number where component is defined.
"""
if inspect.isbuiltin(component):
return None, None
try:
filename = inspect.getsourcefile(component)
except TypeError:
return None, None
try:
unused_code, lineindex = inspect.findsource(component)
lineno = lineindex + 1
except IOError:
lineno = None
return filename, lineno
def Info(component):
"""Returns a dict with information about the given component.
The dict will have at least some of the following fields.
type_name: The type of `component`.
string_form: A string representation of `component`.
file: The file in which `component` is defined.
line: The line number at which `component` is defined.
docstring: The docstring of `component`.
init_docstring: The init docstring of `component`.
class_docstring: The class docstring of `component`.
call_docstring: The call docstring of `component`.
length: The length of `component`.
Args:
component: The component to analyze.
Returns:
A dict with information about the component.
"""
try:
from IPython.core import oinspect # pylint: disable=g-import-not-at-top
inspector = oinspect.Inspector()
info = inspector.info(component)
# IPython's oinspect.Inspector.info may return ''
if info['docstring'] == '':
info['docstring'] = None
except ImportError:
info = _InfoBackup(component)
try:
unused_code, lineindex = inspect.findsource(component)
info['line'] = lineindex + 1
except (TypeError, IOError):
info['line'] = None
if 'docstring' in info:
info['docstring_info'] = docstrings.parse(info['docstring'])
return info
def _InfoBackup(component):
"""Returns a dict with information about the given component.
This function is to be called only in the case that IPython's
oinspect module is not available. The info dict it produces may
contain less information that contained in the info dict produced
by oinspect.
Args:
component: The component to analyze.
Returns:
A dict with information about the component.
"""
info = {}
info['type_name'] = type(component).__name__
info['string_form'] = str(component)
filename, lineno = GetFileAndLine(component)
info['file'] = filename
info['line'] = lineno
info['docstring'] = inspect.getdoc(component)
try:
info['length'] = str(len(component))
except (TypeError, AttributeError):
pass
return info
def IsNamedTuple(component):
"""Return true if the component is a namedtuple.
Unfortunately, Python offers no native way to check for a namedtuple type.
Instead, we need to use a simple hack which should suffice for our case.
namedtuples are internally implemented as tuples, therefore we need to:
1. Check if the component is an instance of tuple.
2. Check if the component has a _fields attribute which regular tuples do
not have.
Args:
component: The component to analyze.
Returns:
True if the component is a namedtuple or False otherwise.
"""
if not isinstance(component, tuple):
return False
has_fields = bool(getattr(component, '_fields', None))
return has_fields
python-fire-0.2.1/fire/inspectutils_test.py 0000664 0000000 0000000 00000012245 13520106167 0021047 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for the inspectutils module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import os
import unittest
from fire import inspectutils
from fire import test_components as tc
from fire import testutils
import six
class InspectUtilsTest(testutils.BaseTestCase):
def testGetFullArgSpec(self):
spec = inspectutils.GetFullArgSpec(tc.identity)
self.assertEqual(spec.args, ['arg1', 'arg2', 'arg3', 'arg4'])
self.assertEqual(spec.defaults, (10, 20))
self.assertEqual(spec.varargs, 'arg5')
self.assertEqual(spec.varkw, 'arg6')
self.assertEqual(spec.kwonlyargs, [])
self.assertEqual(spec.kwonlydefaults, {})
self.assertEqual(spec.annotations, {'arg2': int, 'arg4': int})
@unittest.skipIf(six.PY2, 'No keyword arguments in python 2')
def testGetFullArgSpecPy3(self):
spec = inspectutils.GetFullArgSpec(tc.py3.identity)
self.assertEqual(spec.args, ['arg1', 'arg2', 'arg3', 'arg4'])
self.assertEqual(spec.defaults, (10, 20))
self.assertEqual(spec.varargs, 'arg5')
self.assertEqual(spec.varkw, 'arg10')
self.assertEqual(spec.kwonlyargs, ['arg6', 'arg7', 'arg8', 'arg9'])
self.assertEqual(spec.kwonlydefaults, {'arg8': 30, 'arg9': 40})
self.assertEqual(spec.annotations,
{'arg2': int, 'arg4': int, 'arg7': int, 'arg9': int})
def testGetFullArgSpecFromBuiltin(self):
spec = inspectutils.GetFullArgSpec('test'.upper)
self.assertEqual(spec.args, [])
self.assertEqual(spec.defaults, ())
self.assertEqual(spec.kwonlyargs, [])
self.assertEqual(spec.kwonlydefaults, {})
self.assertEqual(spec.annotations, {})
def testGetFullArgSpecFromSlotWrapper(self):
spec = inspectutils.GetFullArgSpec(tc.NoDefaults)
self.assertEqual(spec.args, [])
self.assertEqual(spec.defaults, ())
self.assertEqual(spec.varargs, None)
self.assertEqual(spec.varkw, None)
self.assertEqual(spec.kwonlyargs, [])
self.assertEqual(spec.kwonlydefaults, {})
self.assertEqual(spec.annotations, {})
def testGetFullArgSpecFromNamedTuple(self):
spec = inspectutils.GetFullArgSpec(tc.NamedTuplePoint)
self.assertEqual(spec.args, ['x', 'y'])
self.assertEqual(spec.defaults, ())
self.assertEqual(spec.varargs, None)
self.assertEqual(spec.varkw, None)
self.assertEqual(spec.kwonlyargs, [])
self.assertEqual(spec.kwonlydefaults, {})
self.assertEqual(spec.annotations, {})
def testGetFullArgSpecFromNamedTupleSubclass(self):
spec = inspectutils.GetFullArgSpec(tc.SubPoint)
self.assertEqual(spec.args, ['x', 'y'])
self.assertEqual(spec.defaults, ())
self.assertEqual(spec.varargs, None)
self.assertEqual(spec.varkw, None)
self.assertEqual(spec.kwonlyargs, [])
self.assertEqual(spec.kwonlydefaults, {})
self.assertEqual(spec.annotations, {})
def testGetFullArgSpecFromClassNoInit(self):
spec = inspectutils.GetFullArgSpec(tc.OldStyleEmpty)
self.assertEqual(spec.args, [])
self.assertEqual(spec.defaults, ())
self.assertEqual(spec.varargs, None)
self.assertEqual(spec.varkw, None)
self.assertEqual(spec.kwonlyargs, [])
self.assertEqual(spec.kwonlydefaults, {})
self.assertEqual(spec.annotations, {})
def testGetFullArgSpecFromMethod(self):
spec = inspectutils.GetFullArgSpec(tc.NoDefaults().double)
self.assertEqual(spec.args, ['count'])
self.assertEqual(spec.defaults, ())
self.assertEqual(spec.varargs, None)
self.assertEqual(spec.varkw, None)
self.assertEqual(spec.kwonlyargs, [])
self.assertEqual(spec.kwonlydefaults, {})
self.assertEqual(spec.annotations, {})
def testInfoOne(self):
info = inspectutils.Info(1)
self.assertEqual(info.get('type_name'), 'int')
self.assertEqual(info.get('file'), None)
self.assertEqual(info.get('line'), None)
self.assertEqual(info.get('string_form'), '1')
def testInfoClass(self):
info = inspectutils.Info(tc.NoDefaults)
self.assertEqual(info.get('type_name'), 'type')
self.assertIn(os.path.join('fire', 'test_components.py'), info.get('file'))
self.assertGreater(info.get('line'), 0)
def testInfoClassNoInit(self):
info = inspectutils.Info(tc.OldStyleEmpty)
if six.PY2:
self.assertEqual(info.get('type_name'), 'classobj')
else:
self.assertEqual(info.get('type_name'), 'type')
self.assertIn(os.path.join('fire', 'test_components.py'), info.get('file'))
self.assertGreater(info.get('line'), 0)
def testInfoNoDocstring(self):
info = inspectutils.Info(tc.NoDefaults)
self.assertEqual(info['docstring'], None, 'Docstring should be None')
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/interact.py 0000664 0000000 0000000 00000006045 13520106167 0017074 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""This module enables interactive mode in Python Fire.
It uses IPython as an optional dependency. When IPython is installed, the
interactive flag will use IPython's REPL. When IPython is not installed, the
interactive flag will start a Python REPL with the builtin `code` module's
InteractiveConsole class.
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import inspect
def Embed(variables, verbose=False):
"""Drops into a Python REPL with variables available as local variables.
Args:
variables: A dict of variables to make available. Keys are variable names.
Values are variable values.
verbose: Whether to include 'hidden' members, those keys starting with _.
"""
print(_AvailableString(variables, verbose))
try:
_EmbedIPython(variables)
except ImportError:
_EmbedCode(variables)
def _AvailableString(variables, verbose=False):
"""Returns a string describing what objects are available in the Python REPL.
Args:
variables: A dict of the object to be available in the REPL.
verbose: Whether to include 'hidden' members, those keys starting with _.
Returns:
A string fit for printing at the start of the REPL, indicating what objects
are available for the user to use.
"""
modules = []
other = []
for name, value in variables.items():
if not verbose and name.startswith('_'):
continue
if '-' in name or '/' in name:
continue
if inspect.ismodule(value):
modules.append(name)
else:
other.append(name)
lists = [
('Modules', modules),
('Objects', other)]
liststrs = []
for name, varlist in lists:
if varlist:
liststrs.append(
'{name}: {items}'.format(name=name, items=', '.join(sorted(varlist))))
return (
'Fire is starting a Python REPL with the following objects:\n'
'{liststrs}\n'
).format(liststrs='\n'.join(liststrs))
def _EmbedIPython(variables, argv=None):
"""Drops into an IPython REPL with variables available for use.
Args:
variables: A dict of variables to make available. Keys are variable names.
Values are variable values.
argv: The argv to use for starting ipython. Defaults to an empty list.
"""
import IPython # pylint: disable=g-import-not-at-top
argv = argv or []
IPython.start_ipython(argv=argv, user_ns=variables)
def _EmbedCode(variables):
import code # pylint: disable=g-import-not-at-top
code.InteractiveConsole(variables).interact()
python-fire-0.2.1/fire/interact_test.py 0000664 0000000 0000000 00000002774 13520106167 0020140 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for the interact module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import interact
from fire import testutils
import mock
try:
import IPython # pylint: disable=unused-import, g-import-not-at-top
INTERACT_METHOD = 'IPython.start_ipython'
except ImportError:
INTERACT_METHOD = 'code.InteractiveConsole'
class InteractTest(testutils.BaseTestCase):
@mock.patch(INTERACT_METHOD)
def testInteract(self, mock_interact_method):
self.assertFalse(mock_interact_method.called)
interact.Embed({})
self.assertTrue(mock_interact_method.called)
@mock.patch(INTERACT_METHOD)
def testInteractVariables(self, mock_interact_method):
self.assertFalse(mock_interact_method.called)
interact.Embed({
'count': 10,
'mock': mock,
})
self.assertTrue(mock_interact_method.called)
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/parser.py 0000664 0000000 0000000 00000011061 13520106167 0016551 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Provides parsing functionality used by Python Fire."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import argparse
import ast
def CreateParser():
parser = argparse.ArgumentParser(add_help=False)
parser.add_argument('--verbose', '-v', action='store_true')
parser.add_argument('--interactive', '-i', action='store_true')
parser.add_argument('--separator', default='-')
parser.add_argument('--completion', nargs='?', const='bash', type=str)
parser.add_argument('--help', '-h', action='store_true')
parser.add_argument('--trace', '-t', action='store_true')
# TODO(dbieber): Consider allowing name to be passed as an argument.
return parser
def SeparateFlagArgs(args):
"""Splits a list of args into those for Flags and those for Fire.
If an isolated '--' arg is not present in the arg list, then all of the args
are for Fire. If there is an isolated '--', then the args after the final '--'
are flag args, and the rest of the args are fire args.
Args:
args: The list of arguments received by the Fire command.
Returns:
A tuple with the Fire args (a list), followed by the Flag args (a list).
"""
if '--' in args:
separator_index = len(args) - 1 - args[::-1].index('--') # index of last --
flag_args = args[separator_index + 1:]
args = args[:separator_index]
return args, flag_args
return args, []
def DefaultParseValue(value):
"""The default argument parsing function used by Fire CLIs.
If the value is made of only Python literals and containers, then the value
is parsed as it's Python value. Otherwise, provided the value contains no
quote, escape, or parenthetical characters, the value is treated as a string.
Args:
value: A string from the command line to be parsed for use in a Fire CLI.
Returns:
The parsed value, of the type determined most appropriate.
"""
# Note: _LiteralEval will treat '#' as the start of a comment.
try:
return _LiteralEval(value)
except (SyntaxError, ValueError):
# If _LiteralEval can't parse the value, treat it as a string.
return value
def _LiteralEval(value):
"""Parse value as a Python literal, or container of containers and literals.
First the AST of the value is updated so that bare-words are turned into
strings. Then the resulting AST is evaluated as a literal or container of
only containers and literals.
This allows for the YAML-like syntax {a: b} to represent the dict {'a': 'b'}
Args:
value: A string to be parsed as a literal or container of containers and
literals.
Returns:
The Python value representing the value arg.
Raises:
ValueError: If the value is not an expression with only containers and
literals.
SyntaxError: If the value string has a syntax error.
"""
root = ast.parse(value, mode='eval')
if isinstance(root.body, ast.BinOp): # pytype: disable=attribute-error
raise ValueError(value)
for node in ast.walk(root):
for field, child in ast.iter_fields(node):
if isinstance(child, list):
for index, subchild in enumerate(child):
if isinstance(subchild, ast.Name):
child[index] = _Replacement(subchild)
elif isinstance(child, ast.Name):
replacement = _Replacement(child)
node.__setattr__(field, replacement)
# ast.literal_eval supports the following types:
# strings, bytes, numbers, tuples, lists, dicts, sets, booleans, and None
# (bytes and set literals only starting with Python 3.2)
return ast.literal_eval(root)
def _Replacement(node):
"""Returns a node to use in place of the supplied node in the AST.
Args:
node: A node of type Name. Could be a variable, or builtin constant.
Returns:
A node to use in place of the supplied Node. Either the same node, or a
String node whose value matches the Name node's id.
"""
value = node.id
# These are the only builtin constants supported by literal_eval.
if value in ('True', 'False', 'None'):
return node
return ast.Str(value)
python-fire-0.2.1/fire/parser_fuzz_test.py 0000664 0000000 0000000 00000006174 13520106167 0020677 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Fuzz tests for the parser module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import parser
from fire import testutils
from hypothesis import example
from hypothesis import given
from hypothesis import settings
from hypothesis import strategies as st
import Levenshtein
import six
class ParserFuzzTest(testutils.BaseTestCase):
@settings(max_examples=10000)
@given(st.text(min_size=1))
@example('True')
@example(r'"test\t\t\a\\a"')
@example(r' "test\t\t\a\\a" ')
@example('"(1, 2)"')
@example('(1, 2)')
@example('(1, 2)')
@example('(1, 2) ')
@example('a,b,c,d')
@example('(a,b,c,d)')
@example('[a,b,c,d]')
@example('{a,b,c,d}')
@example('test:(a,b,c,d)')
@example('{test:(a,b,c,d)}')
@example('{test:a,b,c,d}')
@example('{test:a,b:(c,d)}') # Note: Edit distance may be high for dicts.
@example('0,')
@example('#')
@example('A#00000') # Note: '#'' is treated as a comment.
@example('\x80') # Note: Causes UnicodeDecodeError.
@example(100 * '[' + '0') # Note: Causes MemoryError.
@example('\r\r\r\r1\r\r')
def testDefaultParseValueFuzz(self, value):
try:
result = parser.DefaultParseValue(value)
except TypeError:
# It's OK to get a TypeError if the string has the null character.
if u'\x00' in value:
return
raise
except MemoryError:
if len(value) > 100:
# This is not what we're testing.
return
raise
try:
uvalue = six.text_type(value)
uresult = six.text_type(result)
except UnicodeDecodeError:
# This is not what we're testing.
return
# Check that the parsed value doesn't differ too much from the input.
distance = Levenshtein.distance(uresult, uvalue)
max_distance = (
2 + # Quotes or parenthesis can be implicit.
sum(c.isspace() for c in value) +
value.count('"') + value.count("'") +
3 * (value.count(',') + 1) + # 'a,' can expand to "'a', "
3 * (value.count(':')) + # 'a:' can expand to "'a': "
2 * value.count('\\'))
if '#' in value:
max_distance += len(value) - value.index('#')
if not isinstance(result, six.string_types):
max_distance += value.count('0') # Leading 0s are stripped.
# Note: We don't check distance for dicts since item order can be changed.
if '{' not in value:
self.assertLessEqual(distance, max_distance,
(distance, max_distance, uvalue, uresult))
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/parser_test.py 0000664 0000000 0000000 00000014512 13520106167 0017614 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for the parser module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import parser
from fire import testutils
class ParserTest(testutils.BaseTestCase):
def testCreateParser(self):
self.assertIsNotNone(parser.CreateParser())
def testSeparateFlagArgs(self):
self.assertEqual(parser.SeparateFlagArgs([]), ([], []))
self.assertEqual(parser.SeparateFlagArgs(['a', 'b']), (['a', 'b'], []))
self.assertEqual(parser.SeparateFlagArgs(['a', 'b', '--']),
(['a', 'b'], []))
self.assertEqual(parser.SeparateFlagArgs(['a', 'b', '--', 'c']),
(['a', 'b'], ['c']))
self.assertEqual(parser.SeparateFlagArgs(['--']),
([], []))
self.assertEqual(parser.SeparateFlagArgs(['--', 'c', 'd']),
([], ['c', 'd']))
self.assertEqual(parser.SeparateFlagArgs(['a', 'b', '--', 'c', 'd']),
(['a', 'b'], ['c', 'd']))
self.assertEqual(parser.SeparateFlagArgs(['a', 'b', '--', 'c', 'd', '--']),
(['a', 'b', '--', 'c', 'd'], []))
self.assertEqual(parser.SeparateFlagArgs(['a', 'b', '--', 'c', '--', 'd']),
(['a', 'b', '--', 'c'], ['d']))
def testDefaultParseValueStrings(self):
self.assertEqual(parser.DefaultParseValue('hello'), 'hello')
self.assertEqual(parser.DefaultParseValue('path/file.jpg'), 'path/file.jpg')
self.assertEqual(parser.DefaultParseValue('hello world'), 'hello world')
self.assertEqual(parser.DefaultParseValue('--flag'), '--flag')
def testDefaultParseValueQuotedStrings(self):
self.assertEqual(parser.DefaultParseValue("'hello'"), 'hello')
self.assertEqual(parser.DefaultParseValue("'hello world'"), 'hello world')
self.assertEqual(parser.DefaultParseValue("'--flag'"), '--flag')
self.assertEqual(parser.DefaultParseValue('"hello"'), 'hello')
self.assertEqual(parser.DefaultParseValue('"hello world"'), 'hello world')
self.assertEqual(parser.DefaultParseValue('"--flag"'), '--flag')
def testDefaultParseValueSpecialStrings(self):
self.assertEqual(parser.DefaultParseValue('-'), '-')
self.assertEqual(parser.DefaultParseValue('--'), '--')
self.assertEqual(parser.DefaultParseValue('---'), '---')
self.assertEqual(parser.DefaultParseValue('----'), '----')
self.assertEqual(parser.DefaultParseValue('None'), None)
self.assertEqual(parser.DefaultParseValue("'None'"), 'None')
def testDefaultParseValueNumbers(self):
self.assertEqual(parser.DefaultParseValue('23'), 23)
self.assertEqual(parser.DefaultParseValue('-23'), -23)
self.assertEqual(parser.DefaultParseValue('23.0'), 23.0)
self.assertIsInstance(parser.DefaultParseValue('23'), int)
self.assertIsInstance(parser.DefaultParseValue('23.0'), float)
self.assertEqual(parser.DefaultParseValue('23.5'), 23.5)
self.assertEqual(parser.DefaultParseValue('-23.5'), -23.5)
def testDefaultParseValueStringNumbers(self):
self.assertEqual(parser.DefaultParseValue("'23'"), '23')
self.assertEqual(parser.DefaultParseValue("'23.0'"), '23.0')
self.assertEqual(parser.DefaultParseValue("'23.5'"), '23.5')
self.assertEqual(parser.DefaultParseValue('"23"'), '23')
self.assertEqual(parser.DefaultParseValue('"23.0"'), '23.0')
self.assertEqual(parser.DefaultParseValue('"23.5"'), '23.5')
def testDefaultParseValueQuotedStringNumbers(self):
self.assertEqual(parser.DefaultParseValue('"\'123\'"'), "'123'")
def testDefaultParseValueOtherNumbers(self):
self.assertEqual(parser.DefaultParseValue('1e5'), 100000.0)
def testDefaultParseValueLists(self):
self.assertEqual(parser.DefaultParseValue('[1, 2, 3]'), [1, 2, 3])
self.assertEqual(parser.DefaultParseValue('[1, "2", 3]'), [1, '2', 3])
self.assertEqual(parser.DefaultParseValue('[1, \'"2"\', 3]'), [1, '"2"', 3])
self.assertEqual(parser.DefaultParseValue(
'[1, "hello", 3]'), [1, 'hello', 3])
def testDefaultParseValueBareWordsLists(self):
self.assertEqual(parser.DefaultParseValue('[one, 2, "3"]'), ['one', 2, '3'])
def testDefaultParseValueDict(self):
self.assertEqual(
parser.DefaultParseValue('{"abc": 5, "123": 1}'), {'abc': 5, '123': 1})
def testDefaultParseValueNone(self):
self.assertEqual(parser.DefaultParseValue('None'), None)
def testDefaultParseValueBool(self):
self.assertEqual(parser.DefaultParseValue('True'), True)
self.assertEqual(parser.DefaultParseValue('False'), False)
def testDefaultParseValueBareWordsTuple(self):
self.assertEqual(parser.DefaultParseValue('(one, 2, "3")'), ('one', 2, '3'))
self.assertEqual(parser.DefaultParseValue('one, "2", 3'), ('one', '2', 3))
def testDefaultParseValueNestedContainers(self):
self.assertEqual(
parser.DefaultParseValue('[(A, 2, "3"), 5, {alph: 10.2, beta: "cat"}]'),
[('A', 2, '3'), 5, {'alph': 10.2, 'beta': 'cat'}])
def testDefaultParseValueComments(self):
self.assertEqual(parser.DefaultParseValue('"0#comments"'), '0#comments')
# Comments are stripped. This behavior may change in the future.
self.assertEqual(parser.DefaultParseValue('0#comments'), 0)
def testDefaultParseValueBadLiteral(self):
# If it can't be parsed, we treat it as a string. This behavior may change.
self.assertEqual(
parser.DefaultParseValue('[(A, 2, "3"), 5'), '[(A, 2, "3"), 5')
self.assertEqual(parser.DefaultParseValue('x=10'), 'x=10')
def testDefaultParseValueSyntaxError(self):
# If it can't be parsed, we treat it as a string.
self.assertEqual(parser.DefaultParseValue('"'), '"')
def testDefaultParseValueIgnoreBinOp(self):
self.assertEqual(parser.DefaultParseValue('2017-10-10'), '2017-10-10')
self.assertEqual(parser.DefaultParseValue('1+1'), '1+1')
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/test_components.py 0000664 0000000 0000000 00000024466 13520106167 0020516 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""This module has components that are used for testing Python Fire."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import collections
import enum
import six
if six.PY3:
from fire import test_components_py3 as py3 # pylint: disable=unused-import,no-name-in-module,g-import-not-at-top
def identity(arg1, arg2, arg3=10, arg4=20, *arg5, **arg6): # pylint: disable=keyword-arg-before-vararg
return arg1, arg2, arg3, arg4, arg5, arg6
identity.__annotations__ = {'arg2': int, 'arg4': int}
def multiplier_with_docstring(num, rate=2):
"""Multiplies num by rate.
Args:
num (int): the num you want to multiply
rate (int): the rate for multiplication
Returns:
Multiplication of num by rate
"""
return num * rate
def function_with_help(help=True): # pylint: disable=redefined-builtin
return help
class Empty(object):
pass
class OldStyleEmpty: # pylint: disable=old-style-class,no-init
pass
class WithInit(object):
def __init__(self):
pass
class ErrorInConstructor(object):
def __init__(self, value='value'):
self.value = value
raise ValueError('Error in constructor')
class WithHelpArg(object):
"""Test class for testing when class has a help= arg."""
def __init__(self, help=True): # pylint: disable=redefined-builtin
self.has_help = help
self.dictionary = {'__help': 'help in a dict'}
class NoDefaults(object):
def double(self, count):
return 2 * count
def triple(self, count):
return 3 * count
class WithDefaults(object):
"""Class with functions that have default arguments."""
def double(self, count=0):
"""Returns the input multiplied by 2.
Args:
count: Input number that you want to double.
Returns:
A number that is the double of count.s
"""
return 2 * count
def triple(self, count=0):
return 3 * count
class OldStyleWithDefaults: # pylint: disable=old-style-class,no-init
def double(self, count=0):
return 2 * count
def triple(self, count=0):
return 3 * count
class MixedDefaults(object):
def ten(self):
return 10
def sum(self, alpha=0, beta=0):
return alpha + 2 * beta
def identity(self, alpha, beta='0'):
return alpha, beta
class SimilarArgNames(object):
def identity(self, bool_one=False, bool_two=False):
return bool_one, bool_two
def identity2(self, a=None, alpha=None):
return a, alpha
class CapitalizedArgNames(object):
def sum(self, Delta=1.0, Gamma=2.0): # pylint: disable=invalid-name
return Delta + Gamma
class Annotations(object):
def double(self, count=0):
return 2 * count
def triple(self, count=0):
return 3 * count
double.__annotations__ = {'count': float}
triple.__annotations__ = {'count': float}
class TypedProperties(object):
"""Test class for testing Python Fire with properties of various types."""
def __init__(self):
self.alpha = True
self.beta = (1, 2, 3)
self.charlie = WithDefaults()
self.delta = {
'echo': 'E',
'nest': {
0: 'a',
1: 'b',
},
}
self.echo = ['alex', 'bethany']
self.fox = ('carry', 'divide')
self.gamma = 'myexcitingstring'
class VarArgs(object):
"""Test class for testing Python Fire with a property with varargs."""
def cumsums(self, *items):
total = None
sums = []
for item in items:
if total is None:
total = item
else:
total += item
sums.append(total)
return sums
def varchars(self, alpha=0, beta=0, *chars): # pylint: disable=keyword-arg-before-vararg
return alpha, beta, ''.join(chars)
class Underscores(object):
def __init__(self):
self.underscore_example = 'fish fingers'
def underscore_function(self, underscore_arg):
return underscore_arg
class BoolConverter(object):
def as_bool(self, arg=False):
return bool(arg)
class ReturnsObj(object):
def get_obj(self, *items):
del items # Unused
return BoolConverter()
class NumberDefaults(object):
def reciprocal(self, divisor=10.0):
return 1.0 / divisor
def integer_reciprocal(self, divisor=10):
return 1.0 / divisor
class InstanceVars(object):
def __init__(self, arg1, arg2):
self.arg1 = arg1
self.arg2 = arg2
def run(self, arg1, arg2):
return (self.arg1, self.arg2, arg1, arg2)
class Kwargs(object):
def props(self, **kwargs):
return kwargs
def upper(self, **kwargs):
return ' '.join(sorted(kwargs.keys())).upper()
def run(self, positional, named=None, **kwargs):
return (positional, named, kwargs)
class ErrorRaiser(object):
def fail(self):
raise ValueError('This error is part of a test.')
class NonComparable(object):
def __eq__(self, other):
raise ValueError('Instances of this class cannot be compared.')
def __ne__(self, other):
raise ValueError('Instances of this class cannot be compared.')
class EmptyDictOutput(object):
def totally_empty(self):
return {}
def nothing_printable(self):
return {'__do_not_print_me': 1}
class CircularReference(object):
def create(self):
x = {}
x['y'] = x
return x
class OrderedDictionary(object):
def empty(self):
return collections.OrderedDict()
def non_empty(self):
ordered_dict = collections.OrderedDict()
ordered_dict['A'] = 'A'
ordered_dict[2] = 2
return ordered_dict
class NamedTuple(object):
"""Functions returning named tuples used for testing."""
def point(self):
"""Point example straight from Python docs."""
# pylint: disable=invalid-name
Point = collections.namedtuple('Point', ['x', 'y'])
return Point(11, y=22)
def matching_names(self):
"""Field name equals value."""
# pylint: disable=invalid-name
Point = collections.namedtuple('Point', ['x', 'y'])
return Point(x='x', y='y')
class CallableWithPositionalArgs(object):
"""Test class for supporting callable."""
TEST = 1
def __call__(self, x, y):
return x + y
def fn(self, x):
return x + 1
NamedTuplePoint = collections.namedtuple('NamedTuplePoint', ['x', 'y'])
class SubPoint(NamedTuplePoint):
"""Used for verifying subclasses of namedtuples behave as intended."""
def coordinate_sum(self):
return self.x + self.y
class CallableWithKeywordArgument(object):
"""Test class for supporting callable."""
def __call__(self, **kwargs):
for key, value in kwargs.items():
print('%s: %s' % (key, value))
def print_msg(self, msg):
print(msg)
CALLABLE_WITH_KEYWORD_ARGUMENT = CallableWithKeywordArgument()
class ClassWithDocstring(object):
"""Test class for testing help text output.
This is some detail description of this test class.
"""
def __init__(self, message='Hello!'):
"""Constructor of the test class.
Constructs a new ClassWithDocstring object.
Args:
message: The default message to print.
"""
self.message = message
def print_msg(self, msg=None):
"""Prints a message."""
if msg is None:
msg = self.message
print(msg)
class ClassWithMultilineDocstring(object):
"""Test class for testing help text output with multiline docstring.
This is a test class that has a long docstring description that spans across
multiple lines for testing line breaking in help text.
"""
@staticmethod
def example_generator(n):
"""Generators have a ``Yields`` section instead of a ``Returns`` section.
Args:
n (int): The upper limit of the range to generate, from 0 to `n` - 1.
Yields:
int: The next number in the range of 0 to `n` - 1.
Examples:
Examples should be written in doctest format, and should illustrate how
to use the function.
>>> print([i for i in example_generator(4)])
[0, 1, 2, 3]
"""
for i in range(n):
yield i
def simple_set():
return {1, 2, 'three'}
def simple_frozenset():
return frozenset({1, 2, 'three'})
class Subdict(dict):
"""A subclass of dict, for testing purposes."""
# An example subdict.
SUBDICT = Subdict({1: 2, 'red': 'blue'})
class Color(enum.Enum):
RED = 1
GREEN = 2
BLUE = 3
class HasStaticAndClassMethods(object):
"""A class with a static method and a class method."""
CLASS_STATE = 1
def __init__(self, instance_state):
self.instance_state = instance_state
@staticmethod
def static_fn(args):
return args
@classmethod
def class_fn(cls, args):
return args + cls.CLASS_STATE
def function_with_varargs(arg1, arg2, arg3=1, *varargs): # pylint: disable=keyword-arg-before-vararg
"""Function with varargs.
Args:
arg1: Position arg docstring.
arg2: Position arg docstring.
arg3: Flags docstring.
*varargs: Accepts unlimited positional args.
Returns:
The unlimited positional args.
"""
del arg1, arg2, arg3 # Unused.
return varargs
def function_with_keyword_arguments(arg1, arg2=3, **kwargs):
del arg2 # Unused.
return arg1, kwargs
def fn_with_code_in_docstring():
"""This has code in the docstring.
Example:
x = fn_with_code_in_docstring()
indentation_matters = True
Returns:
True.
"""
return True
class BinaryCanvas(object):
"""A canvas with which to make binary art, one bit at a time."""
def __init__(self, size=10):
self.pixels = [[0] * size for _ in range(size)]
self._size = size
self._row = 0 # The row of the cursor.
self._col = 0 # The column of the cursor.
def __str__(self):
return '\n'.join(
' '.join(str(pixel) for pixel in row) for row in self.pixels)
def show(self):
print(self)
return self
def move(self, row, col):
self._row = row % self._size
self._col = col % self._size
return self
def on(self):
return self.set(1)
def off(self):
return self.set(0)
def set(self, value):
self.pixels[self._row][self._col] = value
return self
python-fire-0.2.1/fire/test_components_bin.py 0000664 0000000 0000000 00000001625 13520106167 0021336 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Python Fire test components Fire CLI.
This file is useful for replicating test results manually.
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import fire
from fire import test_components
def main():
fire.Fire(test_components)
if __name__ == '__main__':
main()
python-fire-0.2.1/fire/test_components_py3.py 0000664 0000000 0000000 00000001717 13520106167 0021303 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""This module has components that use Python 3 specific syntax."""
def identity(arg1, arg2: int, arg3=10, arg4: int = 20, *arg5,
arg6, arg7: int, arg8=30, arg9: int = 40, **arg10):
return arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10
class KeywordOnly(object):
def double(self, *, count):
return count * 2
def triple(self, *, count):
return count * 3
python-fire-0.2.1/fire/test_components_test.py 0000664 0000000 0000000 00000002474 13520106167 0021550 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for the test_components module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import test_components as tc
from fire import testutils
class TestComponentsTest(testutils.BaseTestCase):
"""Tests to verify that the test components are importable and okay."""
def testTestComponents(self):
self.assertIsNotNone(tc.Empty)
self.assertIsNotNone(tc.OldStyleEmpty)
def testNonComparable(self):
with self.assertRaises(ValueError):
tc.NonComparable() != 2 # pylint: disable=expression-not-assigned
with self.assertRaises(ValueError):
tc.NonComparable() == 2 # pylint: disable=expression-not-assigned
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/testutils.py 0000664 0000000 0000000 00000006361 13520106167 0017324 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Utilities for Python Fire's tests."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import contextlib
import re
import sys
import unittest
from fire import core
from fire import trace
import mock
import six
class BaseTestCase(unittest.TestCase):
"""Shared test case for Python Fire tests."""
@contextlib.contextmanager
def assertOutputMatches(self, stdout='.*', stderr='.*', capture=True):
"""Asserts that the context generates stdout and stderr matching regexps.
Note: If wrapped code raises an exception, stdout and stderr will not be
checked.
Args:
stdout: (str) regexp to match against stdout (None will check no stdout)
stderr: (str) regexp to match against stderr (None will check no stderr)
capture: (bool, default True) do not bubble up stdout or stderr
Yields:
Yields to the wrapped context.
"""
stdout_fp = six.StringIO()
stderr_fp = six.StringIO()
try:
with mock.patch.object(sys, 'stdout', stdout_fp):
with mock.patch.object(sys, 'stderr', stderr_fp):
yield
finally:
if not capture:
sys.stdout.write(stdout_fp.getvalue())
sys.stderr.write(stderr_fp.getvalue())
for name, regexp, fp in [('stdout', stdout, stdout_fp),
('stderr', stderr, stderr_fp)]:
value = fp.getvalue()
if regexp is None:
if value:
raise AssertionError('%s: Expected no output. Got: %r' %
(name, value))
else:
if not re.search(regexp, value, re.DOTALL | re.MULTILINE):
raise AssertionError('%s: Expected %r to match %r' %
(name, value, regexp))
@contextlib.contextmanager
def assertRaisesFireExit(self, code, regexp='.*'):
"""Asserts that a FireExit error is raised in the context.
Allows tests to check that Fire's wrapper around SystemExit is raised
and that a regexp is matched in the output.
Args:
code: The status code that the FireExit should contain.
regexp: stdout must match this regex.
Yields:
Yields to the wrapped context.
"""
with self.assertOutputMatches(stderr=regexp):
with self.assertRaises(core.FireExit):
try:
yield
except core.FireExit as exc:
if exc.code != code:
raise AssertionError('Incorrect exit code: %r != %r' % (exc.code,
code))
self.assertIsInstance(exc.trace, trace.FireTrace)
raise
# pylint: disable=invalid-name
main = unittest.main
skip = unittest.skip
# pylint: enable=invalid-name
python-fire-0.2.1/fire/testutils_test.py 0000664 0000000 0000000 00000003542 13520106167 0020361 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Test the test utilities for Fire's tests."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import sys
from fire import testutils
import six
class TestTestUtils(testutils.BaseTestCase):
"""Let's get meta."""
def testNoCheckOnException(self):
with self.assertRaises(ValueError):
with self.assertOutputMatches(stdout='blah'):
raise ValueError()
def testCheckStdoutOrStderrNone(self):
with six.assertRaisesRegex(self, AssertionError, 'stdout:'):
with self.assertOutputMatches(stdout=None):
print('blah')
with six.assertRaisesRegex(self, AssertionError, 'stderr:'):
with self.assertOutputMatches(stderr=None):
print('blah', file=sys.stderr)
with six.assertRaisesRegex(self, AssertionError, 'stderr:'):
with self.assertOutputMatches(stdout='apple', stderr=None):
print('apple')
print('blah', file=sys.stderr)
def testCorrectOrderingOfAssertRaises(self):
# Check to make sure FireExit tests are correct.
with self.assertOutputMatches(stdout='Yep.*first.*second'):
with self.assertRaises(ValueError):
print('Yep, this is the first line.\nThis is the second.')
raise ValueError()
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/trace.py 0000664 0000000 0000000 00000024541 13520106167 0016362 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""This module has classes for tracing the execution of a Fire execution.
A FireTrace consists of a sequence of FireTraceElement objects. Each element
represents an action taken by Fire during a single Fire execution. An action may
be instantiating a class, calling a routine, or accessing a property.
Each action consumes args and results in a new component. The final component
is serialized to stdout by Fire as well as returned by the Fire method. If
a Fire usage error occurs, such as insufficient arguments being provided to call
a function, then that error will be captured in the trace and the final
component will be None.
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import pipes
from fire import inspectutils
INITIAL_COMPONENT = 'Initial component'
INSTANTIATED_CLASS = 'Instantiated class'
CALLED_ROUTINE = 'Called routine'
CALLED_CALLABLE = 'Called callable'
ACCESSED_PROPERTY = 'Accessed property'
COMPLETION_SCRIPT = 'Generated completion script'
INTERACTIVE_MODE = 'Entered interactive mode'
class FireTrace(object):
"""A FireTrace represents the steps taken during a single Fire execution.
A FireTrace consists of a sequence of FireTraceElement objects. Each element
represents an action taken by Fire during a single Fire execution. An action
may be instantiating a class, calling a routine, or accessing a property.
"""
def __init__(self, initial_component, name=None, separator='-', verbose=False,
show_help=False, show_trace=False):
initial_trace_element = FireTraceElement(
component=initial_component,
action=INITIAL_COMPONENT,
)
self.name = name
self.separator = separator
self.elements = [initial_trace_element]
self.verbose = verbose
self.show_help = show_help
self.show_trace = show_trace
def GetResult(self):
"""Returns the component from the last element of the trace."""
# pytype: disable=attribute-error
return self.GetLastHealthyElement().component
# pytype: enable=attribute-error
def GetLastHealthyElement(self):
"""Returns the last element of the trace that is not an error.
This element will contain the final component indicated by the trace.
Returns:
The last element of the trace that is not an error.
"""
for element in reversed(self.elements):
if not element.HasError():
return element
return None
def HasError(self):
"""Returns whether the Fire execution encountered a Fire usage error."""
return self.elements[-1].HasError()
def AddAccessedProperty(self, component, target, args, filename, lineno):
element = FireTraceElement(
component=component,
action=ACCESSED_PROPERTY,
target=target,
args=args,
filename=filename,
lineno=lineno,
)
self.elements.append(element)
def AddCalledComponent(self, component, target, args, filename, lineno,
capacity, action=CALLED_CALLABLE):
"""Adds an element to the trace indicating that a component was called.
Also applies to instantiating a class.
Args:
component: The result of calling the callable.
target: The name of the callable.
args: The args consumed in order to call this callable.
filename: The file in which the callable is defined, or None if N/A.
lineno: The line number on which the callable is defined, or None if N/A.
capacity: (bool) Whether the callable could have accepted additional args.
action: The value to include as the action in the FireTraceElement.
"""
element = FireTraceElement(
component=component,
action=action,
target=target,
args=args,
filename=filename,
lineno=lineno,
capacity=capacity,
)
self.elements.append(element)
def AddCompletionScript(self, script):
element = FireTraceElement(
component=script,
action=COMPLETION_SCRIPT,
)
self.elements.append(element)
def AddInteractiveMode(self):
element = FireTraceElement(action=INTERACTIVE_MODE)
self.elements.append(element)
def AddError(self, error, args):
element = FireTraceElement(error=error, args=args)
self.elements.append(element)
def AddSeparator(self):
"""Marks that the most recent element of the trace used a separator.
A separator is an argument you can pass to a Fire CLI to separate args left
of the separator from args right of the separator.
Here's an example to demonstrate the separator. Let's say you have a
function that takes a variable number of args, and you want to call that
function, and then upper case the result. Here's how to do it:
# in Python
def display(arg1, arg2='!'):
return arg1 + arg2
# from Bash (the default separator is the hyphen -)
display hello # hello!
display hello upper # helloupper
display hello - upper # HELLO!
Note how the separator caused the display function to be called with the
default value for arg2.
"""
self.elements[-1].AddSeparator()
def _Quote(self, arg):
if arg.startswith('--') and '=' in arg:
prefix, value = arg.split('=', 1)
return pipes.quote(prefix) + '=' + pipes.quote(value)
return pipes.quote(arg)
def GetCommand(self, include_separators=True):
"""Returns the command representing the trace up to this point.
Args:
include_separators: Whether or not to include separators in the command.
Returns:
A string representing a Fire CLI command that would produce this trace.
"""
args = []
if self.name:
args.append(self.name)
for element in self.elements:
if element.HasError():
continue
if element.args:
args.extend(element.args)
if element.HasSeparator() and include_separators:
args.append(self.separator)
if self.NeedsSeparator() and include_separators:
args.append(self.separator)
return ' '.join(self._Quote(arg) for arg in args)
def NeedsSeparator(self):
"""Returns whether a separator should be added to the command.
If the command is a function call, then adding an additional argument to the
command sometimes would add an extra arg to the function call, and sometimes
would add an arg acting on the result of the function call.
This function tells us whether we should add a separator to the command
before adding additional arguments in order to make sure the arg is applied
to the result of the function call, and not the function call itself.
Returns:
Whether a separator should be added to the command if order to keep the
component referred to by the command the same when adding additional args.
"""
element = self.GetLastHealthyElement()
return element.HasCapacity() and not element.HasSeparator()
def __str__(self):
lines = []
for index, element in enumerate(self.elements):
line = '{index}. {trace_string}'.format(
index=index + 1,
trace_string=element,
)
lines.append(line)
return '\n'.join(lines)
def NeedsSeparatingHyphenHyphen(self, flag='help'):
"""Returns whether a the trace need '--' before '--help'.
'--' is needed when the component takes keyword arguments, when the value of
flag matches one of the argument of the component, or the component takes in
keyword-only arguments(e.g. argument with default value).
Args:
flag: the flag available for the trace
Returns:
True for needed '--', False otherwise.
"""
element = self.GetLastHealthyElement()
component = element.component
spec = inspectutils.GetFullArgSpec(component)
return (spec.varkw is not None
or flag in spec.args
or flag in spec.kwonlyargs)
class FireTraceElement(object):
"""A FireTraceElement represents a single step taken by a Fire execution.
Examples of a FireTraceElement are the instantiation of a class or the
accessing of an object member.
"""
def __init__(self,
component=None,
action=None,
target=None,
args=None,
filename=None,
lineno=None,
error=None,
capacity=None):
"""Instantiates a FireTraceElement.
Args:
component: The result of this element of the trace.
action: The type of action (eg instantiating a class) taking place.
target: (string) The name of the component being acted upon.
args: The args consumed by the represented action.
filename: The file in which the action is defined, or None if N/A.
lineno: The line number on which the action is defined, or None if N/A.
error: The error represented by the action, or None if N/A.
capacity: (bool) Whether the action could have accepted additional args.
"""
self.component = component
self._action = action
self._target = target
self.args = args
self._filename = filename
self._lineno = lineno
self._error = error
self._separator = False
self._capacity = capacity
def HasError(self):
return self._error is not None
def HasCapacity(self):
return self._capacity
def HasSeparator(self):
return self._separator
def AddSeparator(self):
self._separator = True
def ErrorAsStr(self):
return ' '.join(str(arg) for arg in self._error.args)
def __str__(self):
if self.HasError():
return self.ErrorAsStr()
else:
# Format is: {action} "{target}" ({filename}:{lineno})
string = self._action
if self._target is not None:
string += ' "{target}"'.format(target=self._target)
if self._filename is not None:
path = self._filename
if self._lineno is not None:
path += ':{lineno}'.format(lineno=self._lineno)
string += ' ({path})'.format(path=path)
return string
python-fire-0.2.1/fire/trace_test.py 0000664 0000000 0000000 00000012146 13520106167 0017417 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Tests for the trace module."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
from fire import testutils
from fire import trace
class FireTraceTest(testutils.BaseTestCase):
def testFireTraceInitialization(self):
t = trace.FireTrace(10)
self.assertIsNotNone(t)
self.assertIsNotNone(t.elements)
def testFireTraceGetResult(self):
t = trace.FireTrace('start')
self.assertEqual(t.GetResult(), 'start')
t.AddAccessedProperty('t', 'final', None, 'example.py', 10)
self.assertEqual(t.GetResult(), 't')
def testFireTraceHasError(self):
t = trace.FireTrace('start')
self.assertFalse(t.HasError())
t.AddAccessedProperty('t', 'final', None, 'example.py', 10)
self.assertFalse(t.HasError())
t.AddError(ValueError('example error'), ['arg'])
self.assertTrue(t.HasError())
def testAddAccessedProperty(self):
t = trace.FireTrace('initial object')
args = ('example', 'args')
t.AddAccessedProperty('new component', 'prop', args, 'sample.py', 12)
self.assertEqual(
str(t),
'1. Initial component\n2. Accessed property "prop" (sample.py:12)')
def testAddCalledCallable(self):
t = trace.FireTrace('initial object')
args = ('example', 'args')
t.AddCalledComponent('result', 'cell', args, 'sample.py', 10, False,
action=trace.CALLED_CALLABLE)
self.assertEqual(
str(t),
'1. Initial component\n2. Called callable "cell" (sample.py:10)')
def testAddCalledRoutine(self):
t = trace.FireTrace('initial object')
args = ('example', 'args')
t.AddCalledComponent('result', 'run', args, 'sample.py', 12, False,
action=trace.CALLED_ROUTINE)
self.assertEqual(
str(t),
'1. Initial component\n2. Called routine "run" (sample.py:12)')
def testAddInstantiatedClass(self):
t = trace.FireTrace('initial object')
args = ('example', 'args')
t.AddCalledComponent(
'Classname', 'classname', args, 'sample.py', 12, False,
action=trace.INSTANTIATED_CLASS)
target = """1. Initial component
2. Instantiated class "classname" (sample.py:12)"""
self.assertEqual(str(t), target)
def testAddCompletionScript(self):
t = trace.FireTrace('initial object')
t.AddCompletionScript('This is the completion script string.')
self.assertEqual(
str(t),
'1. Initial component\n2. Generated completion script')
def testAddInteractiveMode(self):
t = trace.FireTrace('initial object')
t.AddInteractiveMode()
self.assertEqual(
str(t),
'1. Initial component\n2. Entered interactive mode')
def testGetCommand(self):
t = trace.FireTrace('initial object')
args = ('example', 'args')
t.AddCalledComponent('result', 'run', args, 'sample.py', 12, False,
action=trace.CALLED_ROUTINE)
self.assertEqual(t.GetCommand(), 'example args')
def testGetCommandWithQuotes(self):
t = trace.FireTrace('initial object')
args = ('example', 'spaced arg')
t.AddCalledComponent('result', 'run', args, 'sample.py', 12, False,
action=trace.CALLED_ROUTINE)
self.assertEqual(t.GetCommand(), "example 'spaced arg'")
def testGetCommandWithFlagQuotes(self):
t = trace.FireTrace('initial object')
args = ('--example=spaced arg',)
t.AddCalledComponent('result', 'run', args, 'sample.py', 12, False,
action=trace.CALLED_ROUTINE)
self.assertEqual(t.GetCommand(), "--example='spaced arg'")
class FireTraceElementTest(testutils.BaseTestCase):
def testFireTraceElementHasError(self):
el = trace.FireTraceElement()
self.assertFalse(el.HasError())
el = trace.FireTraceElement(error=ValueError('example error'))
self.assertTrue(el.HasError())
def testFireTraceElementAsStringNoMetadata(self):
el = trace.FireTraceElement(
component='Example',
action='Fake action',
)
self.assertEqual(str(el), 'Fake action')
def testFireTraceElementAsStringWithTarget(self):
el = trace.FireTraceElement(
component='Example',
action='Created toy',
target='Beaker',
)
self.assertEqual(str(el), 'Created toy "Beaker"')
def testFireTraceElementAsStringWithTargetAndLineNo(self):
el = trace.FireTraceElement(
component='Example',
action='Created toy',
target='Beaker',
filename='beaker.py',
lineno=10,
)
self.assertEqual(str(el), 'Created toy "Beaker" (beaker.py:10)')
if __name__ == '__main__':
testutils.main()
python-fire-0.2.1/fire/value_types.py 0000664 0000000 0000000 00000003336 13520106167 0017623 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""Types of values."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import inspect
import six
VALUE_TYPES = (bool, six.string_types, six.integer_types, float, complex,
type(Ellipsis), type(None), type(NotImplemented))
def IsGroup(component):
# TODO(dbieber): Check if there are any subcomponents.
return not IsCommand(component) and not IsValue(component)
def IsCommand(component):
return inspect.isroutine(component) or inspect.isclass(component)
def IsValue(component):
return isinstance(component, VALUE_TYPES)
def IsSimpleGroup(component):
"""If a group is simple enough, then we treat it as a value in PrintResult.
Only if a group contains all value types do we consider it simple enough to
print as a value.
Args:
component: The group to check for value-group status.
Returns:
A boolean indicating if the group should be treated as a value for printing
purposes.
"""
assert isinstance(component, dict)
for unused_key, value in component.items():
if not IsValue(value) and not isinstance(value, (list, dict)):
return False
return True
python-fire-0.2.1/mkdocs.yml 0000664 0000000 0000000 00000000465 13520106167 0015767 0 ustar 00root root 0000000 0000000 site_name: Python Fire
theme: readthedocs
markdown_extensions: [fenced_code]
pages:
- Overview: index.md
- Installation: installation.md
- Benefits: benefits.md
- The Python Fire Guide: guide.md
- Using a CLI: using-cli.md
- Troubleshooting: troubleshooting.md
- Reference: api.md
python-fire-0.2.1/pylintrc 0000664 0000000 0000000 00000015270 13520106167 0015553 0 ustar 00root root 0000000 0000000 [MASTER]
# Specify a configuration file.
#rcfile=
# Python code to execute, usually for sys.path manipulation such as
# pygtk.require().
#init-hook=
# Profiled execution.
profile=no
# Add to the black list. It should be a base name, not a
# path. You may set this option multiple times.
ignore=
# Pickle collected data for later comparisons.
persistent=yes
# List of plugins (as comma separated values of python modules names) to load,
# usually to register additional checkers.
load-plugins=
[MESSAGES CONTROL]
# Enable the message, report, category or checker with the given id(s). You can
# either give multiple identifier separated by comma (,) or put this option
# multiple time.
enable=indexing-exception,old-raise-syntax
# Disable the message, report, category or checker with the given id(s). You
# can either give multiple identifier separated by comma (,) or put this option
# multiple time.
disable=design,similarities,no-self-use,attribute-defined-outside-init,locally-disabled,star-args,pointless-except,bad-option-value,global-statement,fixme,suppressed-message,useless-suppression,locally-enabled,file-ignored,wrong-import-order,useless-object-inheritance,no-else-return
[REPORTS]
# Set the output format. Available formats are text, parseable, colorized, msvs
# (visual studio) and html
output-format=text
# Include message's id in output
include-ids=no
# Put messages in a separate file for each module / package specified on the
# command line instead of printing them on stdout. Reports (if any) will be
# written in a file name "pylint_global.[txt|html]".
files-output=no
# Tells whether to display a full report or only the messages
reports=yes
# Python expression which should return a note less than 10 (10 is the highest
# note). You have access to the variables errors warning, statement which
# respectively contain the number of errors / warnings messages and the total
# number of statements analyzed. This is used by the global evaluation report
# (R0004).
evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
# Add a comment according to your evaluation note. This is used by the global
# evaluation report (R0004).
comment=no
[VARIABLES]
# Tells whether we should check for unused import in __init__ files.
init-import=no
# A regular expression matching names used for dummy variables (i.e. not used).
dummy-variables-rgx=\*{0,2}(_$|unused_|dummy_)
# List of additional names supposed to be defined in builtins. Remember that
# you should avoid to define new builtins when possible.
additional-builtins=
[BASIC]
# List of builtins function names that should not be used, separated by a comma
bad-functions=map,filter,apply,input,reduce
# Regular expression which should only match correct module names
module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
# Regular expression which should only match correct module level names
const-rgx=(([A-Z_][A-Z0-9_]*)|(__.*__))$
# Regular expression which should only match correct class names
class-rgx=[A-Z_][a-zA-Z0-9]+$
# Regular expression which should only match correct function names
function-rgx=^(?:(?P_?[A-Z][a-zA-Z0-9]*)|(?P_?[a-z][a-z0-9_]*))$
# Regular expression which should only match correct method names
method-rgx=^(?:(?P__[a-z0-9_]+__|next)|(?P_{0,2}(?:test|assert)?[A-Z][a-zA-Z0-9]*)|(?:_{0,2}[a-z][a-z0-9_]*))$
# Regular expression which should only match correct instance attribute names
attr-rgx=^_{0,2}[a-z][a-z0-9_]*$
# Regular expression which should only match correct argument names
argument-rgx=^[a-z][a-z0-9_]*$
# Regular expression which should only match correct variable names
variable-rgx=^[a-z][a-z0-9_]*$
# Regular expression which should only match correct list comprehension /
# generator expression variable names
inlinevar-rgx=^[a-z][a-z0-9_]*$
# Good variable names which should always be accepted, separated by a comma
good-names=i,j,k,ex,main,Run,_
# Bad variable names which should always be refused, separated by a comma
bad-names=foo,bar,baz,toto,tutu,tata
# Regular expression which should only match functions or classes name which do
# not require a docstring
no-docstring-rgx=(__.*__|main|test.*|.*Test)
# Minimum length for a docstring
docstring-min-length=10
[MISCELLANEOUS]
# List of note tags to take in consideration, separated by a comma.
notes=FIXME,XXX,TODO
[FORMAT]
# Maximum number of characters on a single line.
max-line-length=80
# Maximum number of lines in a module
max-module-lines=99999
# String used as indentation unit. This is usually " " (4 spaces) or "\t" (1
# tab).
indent-string=' '
[SIMILARITIES]
# Minimum lines number of a similarity.
min-similarity-lines=4
# Ignore comments when computing similarities.
ignore-comments=yes
# Ignore docstrings when computing similarities.
ignore-docstrings=yes
[TYPECHECK]
# Tells whether missing members accessed in mixin class should be ignored. A
# mixin class is detected if its name ends with "mixin" (case insensitive).
ignore-mixin-members=yes
# List of classes names for which member attributes should not be checked
# (useful for classes with attributes dynamically set).
ignored-classes=
# List of members which are set dynamically and missed by pylint inference
# system, and so shouldn't trigger E0201 when accessed.
generated-members=
[DESIGN]
# Maximum number of arguments for function / method
max-args=5
# Argument names that match this expression will be ignored. Default to name
# with leading underscore
ignored-argument-names=_.*
# Maximum number of locals for function / method body
max-locals=15
# Maximum number of return / yield for function / method body
max-returns=6
# Maximum number of branch for function / method body
max-branchs=12
# Maximum number of statements in function / method body
max-statements=50
# Maximum number of parents for a class (see R0901).
max-parents=7
# Maximum number of attributes for a class (see R0902).
max-attributes=7
# Minimum number of public methods for a class (see R0903).
min-public-methods=2
# Maximum number of public methods for a class (see R0904).
max-public-methods=20
[IMPORTS]
# Deprecated modules which should not be used, separated by a comma
deprecated-modules=regsub,string,TERMIOS,Bastion,rexec
# Create a graph of every (i.e. internal and external) dependencies in the
# given file (report RP0402 must not be disabled)
import-graph=
# Create a graph of external dependencies in the given file (report RP0402 must
# not be disabled)
ext-import-graph=
# Create a graph of internal dependencies in the given file (report RP0402 must
# not be disabled)
int-import-graph=
[CLASSES]
# List of method names used to declare (i.e. assign) instance attributes.
defining-attr-methods=__init__,__new__,setUp
python-fire-0.2.1/requirements.txt 0000664 0000000 0000000 00000000002 13520106167 0017233 0 ustar 00root root 0000000 0000000 .
python-fire-0.2.1/setup.cfg 0000664 0000000 0000000 00000000330 13520106167 0015574 0 ustar 00root root 0000000 0000000 [metadata]
license-file = LICENSE
[wheel]
universal = 1
[aliases]
test = pytest
[tool:pytest]
addopts = --ignore=fire/test_components_py3.py --ignore=fire/parser_fuzz_test.py
[pytype]
inputs = .
output = .pytype
python-fire-0.2.1/setup.py 0000664 0000000 0000000 00000004674 13520106167 0015504 0 ustar 00root root 0000000 0000000 # Copyright (C) 2018 Google Inc.
#
# 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.
"""The setup.py file for Python Fire."""
from setuptools import setup
LONG_DESCRIPTION = """
Python Fire is a library for automatically generating command line interfaces
(CLIs) with a single line of code.
It will turn any Python module, class, object, function, etc. (any Python
component will work!) into a CLI. It's called Fire because when you call Fire(),
it fires off your command.
""".strip()
SHORT_DESCRIPTION = """
A library for automatically generating command line interfaces.""".strip()
DEPENDENCIES = [
'six',
'termcolor',
]
TEST_DEPENDENCIES = [
'hypothesis',
'mock',
'python-Levenshtein',
]
VERSION = '0.2.1'
URL = 'https://github.com/google/python-fire'
setup(
name='fire',
version=VERSION,
description=SHORT_DESCRIPTION,
long_description=LONG_DESCRIPTION,
url=URL,
author='David Bieber',
author_email='dbieber@google.com',
license='Apache Software License',
classifiers=[
'Development Status :: 4 - Beta',
'Intended Audience :: Developers',
'Topic :: Software Development :: Libraries :: Python Modules',
'License :: OSI Approved :: Apache Software License',
'Programming Language :: Python',
'Programming Language :: Python :: 2',
'Programming Language :: Python :: 2.7',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.4',
'Programming Language :: Python :: 3.5',
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.7',
'Operating System :: OS Independent',
'Operating System :: POSIX',
'Operating System :: MacOS',
'Operating System :: Unix',
],
keywords='command line interface cli python fire interactive bash tool',
packages=['fire', 'fire.console'],
install_requires=DEPENDENCIES,
tests_require=TEST_DEPENDENCIES,
)