_py module

The py program (part of the pyflyby project) is a command-line multitool for running python code, with heuristic intention guessing, automatic importing, and debugging support.

Invocation summary

py [--file]   filename.py arg1 arg2   Execute a file
py [--eval]  'function(arg1, arg2)'   Evaluate an expression/statement
py [--apply]  function arg1 arg2      Call function(arg1, arg2)
py [--module] modname arg1 arg2       Run a module

py  --map     function arg1 arg2      Call function(arg1); function(arg2)

py  -i       'function(arg1, arg2)'   Run file/code/etc, then run IPython
py  --debug  'function(arg1, arg2)'   Debug file/code/etc
py  --debug   PID                     Attach debugger to PID

py            function?               Get help for a function or module
py            function??              Get source of a function or module

py                                    Start IPython with autoimporter
py nb                                 Start IPython Notebook with autoimporter


py [--add-deprecated-builtins]        Inject "breakpoint", "debug_exception",
                                      "debug_statement", "waitpoint" into
                                      builtins. This is deprecated, and
                                      present for backward compatibilty
                                      but will be removed in the future.

Features

Heuristic action mode guessing: If none of –file, –eval, –apply, –module, or –map is specified, then guess what to do, choosing one of these actions:

Execute (run) a file

Evaluate concatenated arguments

Run a module

Call (apply) a function

Evaluate first argument

Automatic importing: All action modes (except run_module) automatically import as needed.

Heuristic argument evaluation: By default, py –eval, py –apply, and py –map guess whether the arguments should be interpreted as expressions or literal strings. A “–” by itself will designate subsequent args as strings. A “-” by itself will be replaced by the contents of stdin as a string.

Merged eval/exec: Code is eval()ed or exec()ed as appropriate.

Result printing: By default, results are pretty-printed if not None.

Heuristic flags: “print” can be used as a function or a statement.

Matplotlib/pylab integration: show() is called if appropriate to block on plots.

Enter debugger upon unhandled exception. (This functionality is enabled by default when stdout is a tty. Use –postmortem=no to never use the postmortem debugger. Use –postmortem=yes enable even if stdout is not a tty. If the postmortem debugger is enabled but /dev/tty is not available, then if an exception occurs, py will email instructions for attaching a debugger.)

Control-\ (SIGQUIT) enters debugger while running (and allows continuing).

New builtin functions such as “debugger()”.

Warning

py is intended as an interactive tool. When writing shell aliases for interactive use, the –safe option can be useful. When writing scripts, it’s better to avoid all heuristic guessing; use regular python -c …, or better yet, a full-fledged python program (and run tidy-imports).

Options

Global options valid before code argument:

  --args=string    Interpret all arguments as literal strings.
                   (The "--" argument also specifies remaining arguments to be
                   literal strings.)
  --args=eval      Evaluate all arguments as expressions.
  --args=auto      (Default) Heuristically guess whether to evaluate arguments
                   as literal strings or expressions.
  --output=silent  Don't print the result of evaluation.
  --output=str     Print str(result).
  --output=repr    Print repr(result).
  --output=pprint  Print pprint.pformat(result).
  --output=repr-if-not-none
                   Print repr(result), but only if result is not None.
  --output=pprint-if-not-none
                   Print pprint.pformat(result), but only if result is not None.
  --output=interactive
                   (Default) Print result.__interactive_display__() if defined,
                   else pprint if result is not None.
  --output=exit    Raise SystemExit(result).
  --safe           Equivalent to --args=strings and PYFLYBY_PATH=EMPTY.
  --quiet, --q     Log only error messages to stderr; omit info and warnings.
  --interactive, --i
                   Run an IPython shell after completion
  --debug, --d     Run the target code file etc under the debugger.  If a PID is
                   given, then instead attach a debugger to the target PID.
  --verbose        Turn on verbose messages from pyflyby.

Pseudo-actions valid before, after, or without code argument:

  --version        Print pyflyby version or version of a module.
  --help, --h, --? Print this help or help for a function or module.
  --source, --??   Print source code for a function or module.

Examples

Start IPython with pyflyby autoimporter enabled:

$ py

Start IPython/Jupyter Notebook with pyflyby autoimporter enabled:

$ py nb

Find the ASCII value of the letter “j” (apply builtin function):

$ py ord j
[PYFLYBY] ord('j')
106

Decode a base64-encoded string (apply autoimported function):

$ py b64decode aGVsbG8=
[PYFLYBY] from base64 import b64decode
[PYFLYBY] b64decode('aGVsbG8=', altchars=None)
b'hello'

Find the day of the week of some date (apply function in module):

$ py calendar.weekday 2014 7 18
[PYFLYBY] import calendar
[PYFLYBY] calendar.weekday(2014, 7, 18)
4

Using named arguments:

$ py calendar.weekday --day=16 --month=7 --year=2014
[PYFLYBY] import calendar
[PYFLYBY] calendar.weekday(2014, 7, 16)
2

Using short named arguments:

$ py calendar.weekday -m 7 -d 15 -y 2014
[PYFLYBY] import calendar
[PYFLYBY] calendar.weekday(2014, 7, 15)
1

Invert a matrix (evaluate expression, with autoimporting):

$ py 'matrix("1 3 3; 1 4 3; 1 3 4").I'
[PYFLYBY] from numpy import matrix
[PYFLYBY] matrix("1 3 3; 1 4 3; 1 3 4").I
matrix([[ 7., -3., -3.],
        [-1.,  1.,  0.],
        [-1.,  0.,  1.]])

Plot cosine (evaluate expression, with autoimporting):

$ py 'plot(cos(arange(30)))'
[PYFLYBY] from numpy import arange
[PYFLYBY] from numpy import cos
[PYFLYBY] from matplotlib.pyplot import plot
[PYFLYBY] plot(cos(arange(30)))
<plot>

Command-line calculator (multiple arguments):

$ py 3 / 4
0.75

Command-line calculator (single arguments):

$ py '(5+7j) \** 12'
(65602966976-150532462080j)

Rationalize a decimal (apply bound method):

$ py 2.5.as_integer_ratio
[PYFLYBY] 2.5.as_integer_ratio()
(5, 2)

Rationalize a decimal (apply unbound method):

$ py float.as_integer_ratio 2.5
[PYFLYBY] float.as_integer_ratio(2.5)
(5, 2)

Rationalize decimals (map/apply):

$ py --map float.as_integer_ratio 2.5 3.5
[PYFLYBY] float.as_integer_ratio(2.5)
(5, 2)
[PYFLYBY] float.as_integer_ratio(3.5)
(7, 2)

Square numbers (map lambda):

$ py --map 'lambda x: x \**2' 3 4 5
[PYFLYBY] (lambda x: x \**2)(3)
9
[PYFLYBY] (lambda x: x \**2)(4)
16
[PYFLYBY] (lambda x: x \**2)(5)
25

Find length of string (using “-” for stdin):

$ echo hello | py len -
[PYFLYBY] len('hello\\n')
6

Run stdin as code:

$ echo 'print(sys.argv[1:])' | py - hello world
[PYFLYBY] import sys
['hello', 'world']

Run libc functions:

$ py --quiet --output=none 'CDLL("libc.so.6").printf' %03d 7
007

Download web page:

$ py --print 'requests.get(sys.argv[1]).text' http://example.com

Get function help:

$ py b64decode?
[PYFLYBY] from base64 import b64decode
Python signature::

  >> b64decode(s, altchars=None, validate=False)

Command-line signature::

  $ py b64decode s [altchars [validate]]
  $ py b64decode --s=... [--altchars=...] [--validate=...]
...

Get module help:

$ py pandas?
[PYFLYBY] import pandas
Version:
  0.13.1
Filename:
  /usr/local/lib/python2.7/site-packages/pandas/__init__.pyc
Docstring:
  pandas - a powerful data analysis and manipulation library for Python
  ...

class pyflyby._py.LoggedList(items)

List that logs which members have not yet been accessed (nor removed).

_ACCESSED = <object object>

append(x)

count()

extend(new_items)

index(x, *start_stop)

insert(index, x)

pop(index)

remove(x)

reverse()

sort()

property unaccessed

exception pyflyby._py.NotAFunctionError

exception pyflyby._py.ParseError

pyflyby._py.SysArgvCtx(*args)

Context manager that:

Temporarily sets sys.argv = args.
At end of context, complains if any args were never accessed.

exception pyflyby._py.UnimportableNameError

class pyflyby._py.UserExpr(arg, namespace, arg_mode, source=None)

An expression from user input, and its evaluated value.

The expression can come from a string literal or other raw value, or a string that is evaluated as an expression, or heuristically chosen.

>>> ns = _Namespace()

Heuristic auto-evaluation:

>>> UserExpr('5+2', ns, "auto").value
7

>>> UserExpr('5j+2', ns, "auto").value
(2+5j)

>>> UserExpr('base64.b64decode("SGFsbG93ZWVu")', ns, "auto").value
[PYFLYBY] import base64
b'Halloween'

Returning an unparsable argument as a string:

>>> UserExpr('Victory Loop', ns, "auto").value
'Victory Loop'

Returning an undefined (and not auto-importable) argument as a string:

>>> UserExpr('Willowbrook29817621+5', ns, "auto").value
'Willowbrook29817621+5'

Explicit literal string:

>>> UserExpr("2+3", ns, "raw_value").value
'2+3'

>>> UserExpr("'2+3'", ns, "raw_value").value
"'2+3'"

Other raw values:

>>> UserExpr(sys.exit, ns, "raw_value").value
<built-in function exit>

_infer_and_evaluate()

Return type:: None

class pyflyby._py._Namespace

auto_eval(block, mode=None, info=False, auto_import=True, debug=False): Evaluate block with auto-importing.

auto_import(arg)

exception pyflyby._py._ParseInterruptedWantHelp

exception pyflyby._py._ParseInterruptedWantSource

class pyflyby._py._PyMain(args)

_enable_debug_tools(*, add_deprecated)

_parse_global_opts()

_pre_exit()

_pre_exit_interactive_shell()

_pre_exit_matplotlib_show(): If matplotlib.pyplot (pylab) is loaded, then call the show() function. This will cause the program to block until all figures are closed. Without this, a command like ‘py plot(…)’ would exit immediately.

_run_action()

_seems_like_runnable_module(arg)

apply(function, cmd_args)

create_ipython_app(): Create an IPython application and initialize it, but don’t start it.

eval(cmd, cmd_args)

exec_stdin(cmd_args)

execfile(filename_arg, cmd_args)

heuristic_cmd(cmd, cmd_args, function_name=None)

heuristic_run_module(module, args)

print_help(objname, verbosity=1)

print_version(arg)

run()

run_module(module, args)

start_ipython(args=[])

pyflyby._py._as_filename_if_seems_like_filename(arg)

If arg seems like a filename, then return it as one.

>>> bool(_as_filename_if_seems_like_filename("foo.py"))
True

>>> bool(_as_filename_if_seems_like_filename("%foo.py"))
False

>>> bool(_as_filename_if_seems_like_filename("foo(bar)"))
False

>>> bool(_as_filename_if_seems_like_filename("/foo/bar/baz.quux-660470"))
True

>>> bool(_as_filename_if_seems_like_filename("../foo/bar-24084866"))
True

Return type:: Filename

pyflyby._py._build_function_usage_string(function_name, obj, prefix)

pyflyby._py._format_call(function_name, argspec, args, kwargs)

pyflyby._py._format_call_spec(function_name, obj)

Return type:: str

pyflyby._py._get_argspec(arg)

Return type:: FullArgSpec

pyflyby._py._get_help(expr, verbosity=1)

Construct a help string.

Parameters:: expr (UserExpr) – Object to generate help for.
Return type:: str

pyflyby._py._handle_user_exception(exc_info=None): Handle an exception in user code.

pyflyby._py._has_python_shebang(filename)

Return whether the first line contains #!…python…

Used for confirming that an executable script found via which() is actually supposed to be a python script.

Note that this test is only needed for scripts found via which(), since otherwise the shebang is not necessary.

pyflyby._py._interpret_arg_mode(arg, default='auto')

>>> _interpret_arg_mode("Str")
'string'

pyflyby._py._interpret_output_mode(arg, default='interactive')

>>> _interpret_output_mode('Repr_If_Not_None')
'repr-if-not-none'

pyflyby._py._parse_auto_apply_args(argspec, commandline_args, namespace, arg_mode='auto')

Parse command-line arguments heuristically. Arguments that can be evaluated are evaluated; otherwise they are treated as strings.

Returns:: args, kwargs

pyflyby._py._requires_parens_as_function(function_name)

Returns whether the given string of a callable would require parentheses around it to call it.

>>> _requires_parens_as_function("foo.bar[4]")
False

>>> _requires_parens_as_function("foo+bar")
True

>>> _requires_parens_as_function("(foo+bar)()")
False

>>> _requires_parens_as_function("(foo+bar)")
False

>>> _requires_parens_as_function("(foo)+(bar)")
True

Return type:: bool

pyflyby._py.auto_apply(function, commandline_args, namespace, arg_mode=None, debug=False)

Call function on command-line arguments. Arguments can be positional or keyword arguments like “–foo=bar”. Arguments are by default heuristically evaluated.

Parameters:

function (UserExpr) – Function to apply.
commandline_args (list of str) – Arguments to function as strings.
arg_mode – How to interpret commandline_args. If "string", then treat them as literal strings. If "eval", then evaluate all arguments as expressions. If "auto" (the default), then heuristically decide whether to treat as expressions or strings.

pyflyby._py.print_result(result, output_mode)

pyflyby._py.py_main(args=None)