def __call__(self,name,win32=False):
from IPython.utils.path import get_py_filename
try:
return get_py_filename(name,win32=win32)
except IOError:
test_dir = os.path.dirname(self.test_filename)
new_path = os.path.join(test_dir,name)
return get_py_filename(new_path,win32=win32)
def __call__(self, name):
from IPython.utils.path import get_py_filename
try:
return get_py_filename(name)
except IOError:
test_dir = os.path.dirname(self.test_filename)
new_path = os.path.join(test_dir, name)
return get_py_filename(new_path)
def test_unicode_in_filename():
"""When a file doesn't exist, the exception raised should be safe to call
str() on - i.e. in Python 2 it must only have ASCII characters.
https://github.com/ipython/ipython/issues/875
"""
try:
# these calls should not throw unicode encode exceptions
path.get_py_filename(u'fooéè.py', force_win32=False)
except IOError as ex:
str(ex)
def test_unicode_in_filename():
"""When a file doesn't exist, the exception raised should be safe to call
str() on - i.e. in Python 2 it must only have ASCII characters.
https://github.com/ipython/ipython/issues/875
"""
try:
# these calls should not throw unicode encode exceptions
path.get_py_filename('fooéè.py', force_win32=False)
except IOError as ex:
str(ex)
def test_get_py_filename():
os.chdir(TMP_TEST_DIR)
with make_tempfile('foo.py'):
nt.assert_equal(path.get_py_filename('foo.py'), 'foo.py')
nt.assert_equal(path.get_py_filename('foo'), 'foo.py')
with make_tempfile('foo'):
nt.assert_equal(path.get_py_filename('foo'), 'foo')
nt.assert_raises(IOError, path.get_py_filename, 'foo.py')
nt.assert_raises(IOError, path.get_py_filename, 'foo')
nt.assert_raises(IOError, path.get_py_filename, 'foo.py')
true_fn = 'foo with spaces.py'
with make_tempfile(true_fn):
nt.assert_equal(path.get_py_filename('foo with spaces'), true_fn)
nt.assert_equal(path.get_py_filename('foo with spaces.py'), true_fn)
nt.assert_raises(IOError, path.get_py_filename, '"foo with spaces.py"')
nt.assert_raises(IOError, path.get_py_filename, "'foo with spaces.py'")
def test_get_py_filename():
os.chdir(TMP_TEST_DIR)
with make_tempfile('foo.py'):
nt.assert_equal(path.get_py_filename('foo.py'), 'foo.py')
nt.assert_equal(path.get_py_filename('foo'), 'foo.py')
with make_tempfile('foo'):
nt.assert_equal(path.get_py_filename('foo'), 'foo')
nt.assert_raises(IOError, path.get_py_filename, 'foo.py')
nt.assert_raises(IOError, path.get_py_filename, 'foo')
nt.assert_raises(IOError, path.get_py_filename, 'foo.py')
true_fn = 'foo with spaces.py'
with make_tempfile(true_fn):
nt.assert_equal(path.get_py_filename('foo with spaces'), true_fn)
nt.assert_equal(path.get_py_filename('foo with spaces.py'), true_fn)
nt.assert_raises(IOError, path.get_py_filename, '"foo with spaces.py"')
nt.assert_raises(IOError, path.get_py_filename, "'foo with spaces.py'")
def test_get_py_filename():
os.chdir(TMP_TEST_DIR)
with make_tempfile("foo.py"):
assert path.get_py_filename("foo.py") == "foo.py"
assert path.get_py_filename("foo") == "foo.py"
with make_tempfile("foo"):
assert path.get_py_filename("foo") == "foo"
pytest.raises(IOError, path.get_py_filename, "foo.py")
pytest.raises(IOError, path.get_py_filename, "foo")
pytest.raises(IOError, path.get_py_filename, "foo.py")
true_fn = "foo with spaces.py"
with make_tempfile(true_fn):
assert path.get_py_filename("foo with spaces") == true_fn
assert path.get_py_filename("foo with spaces.py") == true_fn
pytest.raises(IOError, path.get_py_filename, '"foo with spaces.py"')
pytest.raises(IOError, path.get_py_filename, "'foo with spaces.py'")
def test_get_py_filename():
os.chdir(TMP_TEST_DIR)
for win32 in (True, False):
with make_tempfile('foo.py'):
nt.assert_equal(
path.get_py_filename('foo.py', force_win32=win32), 'foo.py')
nt.assert_equal(
path.get_py_filename('foo', force_win32=win32), 'foo.py')
with make_tempfile('foo'):
nt.assert_equal(
path.get_py_filename('foo', force_win32=win32), 'foo')
nt.assert_raises(
IOError, path.get_py_filename, 'foo.py', force_win32=win32)
nt.assert_raises(
IOError, path.get_py_filename, 'foo', force_win32=win32)
nt.assert_raises(
IOError, path.get_py_filename, 'foo.py', force_win32=win32)
true_fn = 'foo with spaces.py'
with make_tempfile(true_fn):
nt.assert_equal(
path.get_py_filename('foo with spaces', force_win32=win32), true_fn)
nt.assert_equal(
path.get_py_filename('foo with spaces.py', force_win32=win32), true_fn)
if win32:
nt.assert_equal(
path.get_py_filename('"foo with spaces.py"', force_win32=True), true_fn)
nt.assert_equal(
path.get_py_filename("'foo with spaces.py'", force_win32=True), true_fn)
else:
nt.assert_raises(
IOError, path.get_py_filename, '"foo with spaces.py"', force_win32=False)
nt.assert_raises(
IOError, path.get_py_filename, "'foo with spaces.py'", force_win32=False)
def get_py_filename(self, name, force_win32=None):
path = self.Client_Path(name)
if self.active and path.is_absolute():
try:
path = path.relative_to(self.client_path)
except ValueError:
path = path.name
path = self.server_path / path
return ipypath.get_py_filename(str(path), force_win32=force_win32)
def make_filename(arg):
"Make a filename from the given args"
try:
filename = get_py_filename(arg)
except IOError:
if args.endswith('.py'):
filename = arg
else:
filename = None
return filename
def make_filename(arg):
"Make a filename from the given args"
try:
filename = get_py_filename(arg)
except IOError:
if args.endswith('.py'):
filename = arg
else:
filename = None
return filename
def make_filename(arg):
"Make a filename from the given args"
try:
filename = get_py_filename(arg)
except IOError:
# If it ends with .py but doesn't already exist, assume we want
# a new file.
if arg.endswith('.py'):
filename = arg
else:
filename = None
return filename
def make_filename(arg):
"Make a filename from the given args"
try:
filename = get_py_filename(arg)
except IOError:
# If it ends with .py but doesn't already exist, assume we want
# a new file.
if arg.endswith('.py'):
filename = arg
else:
filename = None
return filename
def test_get_py_filename():
os.chdir(TMP_TEST_DIR)
for win32 in (True, False):
with make_tempfile('foo.py'):
nt.assert_equal(path.get_py_filename('foo.py', force_win32=win32),
'foo.py')
nt.assert_equal(path.get_py_filename('foo', force_win32=win32),
'foo.py')
with make_tempfile('foo'):
nt.assert_equal(path.get_py_filename('foo', force_win32=win32),
'foo')
nt.assert_raises(IOError,
path.get_py_filename,
'foo.py',
force_win32=win32)
nt.assert_raises(IOError,
path.get_py_filename,
'foo',
force_win32=win32)
nt.assert_raises(IOError,
path.get_py_filename,
'foo.py',
force_win32=win32)
true_fn = 'foo with spaces.py'
with make_tempfile(true_fn):
nt.assert_equal(
path.get_py_filename('foo with spaces', force_win32=win32),
true_fn)
nt.assert_equal(
path.get_py_filename('foo with spaces.py', force_win32=win32),
true_fn)
if win32:
nt.assert_equal(
path.get_py_filename('"foo with spaces.py"',
force_win32=True), true_fn)
nt.assert_equal(
path.get_py_filename("'foo with spaces.py'",
force_win32=True), true_fn)
else:
nt.assert_raises(IOError,
path.get_py_filename,
'"foo with spaces.py"',
force_win32=False)
nt.assert_raises(IOError,
path.get_py_filename,
"'foo with spaces.py'",
force_win32=False)
def pycat(self, parameter_s=''):
"""Show a syntax-highlighted file through a pager.
This magic is similar to the cat utility, but it will assume the file
to be Python source and will show it with syntax highlighting. """
try:
filename = get_py_filename(parameter_s)
cont = file_read(filename)
except IOError:
try:
cont = eval(parameter_s, self.shell.user_ns)
except NameError:
cont = None
if cont is None:
print "Error: no such file or variable"
return
page.page(self.shell.pycolorize(cont))
def pfile(self, parameter_s=""):
"""Print (or run through pager) the file where an object is defined.
The file opens at the line where the object definition begins. IPython
will honor the environment variable PAGER if set, and otherwise will
do its best to print the file in a convenient form.
If the given argument is not an object currently defined, IPython will
try to interpret it as a filename (automatically adding a .py extension
if needed). You can thus use %pfile as a syntax highlighting code
viewer."""
# first interpret argument as an object name
out = self.shell._inspect("pfile", parameter_s)
# if not, try the input as a filename
if out == "not found":
try:
filename = get_py_filename(parameter_s)
except IOError as msg:
print msg
return
page.page(self.shell.inspector.format(open(filename).read()))
def pfile(self, parameter_s='', namespaces=None):
"""Print (or run through pager) the file where an object is defined.
The file opens at the line where the object definition begins. IPython
will honor the environment variable PAGER if set, and otherwise will
do its best to print the file in a convenient form.
If the given argument is not an object currently defined, IPython will
try to interpret it as a filename (automatically adding a .py extension
if needed). You can thus use %pfile as a syntax highlighting code
viewer."""
# first interpret argument as an object name
out = self.shell._inspect('pfile',parameter_s, namespaces)
# if not, try the input as a filename
if out == 'not found':
try:
filename = get_py_filename(parameter_s)
except IOError as msg:
print(msg)
return
page.page(self.shell.pycolorize(read_py_file(filename, skip_encoding_cookie=False)))
def pfile(self, parameter_s='', namespaces=None):
"""Print (or run through pager) the file where an object is defined.
The file opens at the line where the object definition begins. IPython
will honor the environment variable PAGER if set, and otherwise will
do its best to print the file in a convenient form.
If the given argument is not an object currently defined, IPython will
try to interpret it as a filename (automatically adding a .py extension
if needed). You can thus use %pfile as a syntax highlighting code
viewer."""
# first interpret argument as an object name
out = self.shell._inspect('pfile',parameter_s, namespaces)
# if not, try the input as a filename
if out == 'not found':
try:
filename = get_py_filename(parameter_s)
except IOError as msg:
print(msg)
return
page.page(self.shell.pycolorize(read_py_file(filename, skip_encoding_cookie=False)))
def prun(self, parameter_s='', cell=None, user_mode=True,
opts=None,arg_lst=None,prog_ns=None):
"""Run a statement through the python code profiler.
Usage, in line mode:
%prun [options] statement
Usage, in cell mode:
%%prun [options] [statement]
code...
code...
In cell mode, the additional code lines are appended to the (possibly
empty) statement in the first line. Cell mode allows you to easily
profile multiline blocks without having to put them in a separate
function.
The given statement (which doesn't require quote marks) is run via the
python profiler in a manner similar to the profile.run() function.
Namespaces are internally managed to work correctly; profile.run
cannot be used in IPython because it makes certain assumptions about
namespaces which do not hold under IPython.
Options:
-l <limit>: you can place restrictions on what or how much of the
profile gets printed. The limit value can be:
* A string: only information for function names containing this string
is printed.
* An integer: only these many lines are printed.
* A float (between 0 and 1): this fraction of the report is printed
(for example, use a limit of 0.4 to see the topmost 40% only).
You can combine several limits with repeated use of the option. For
example, '-l __init__ -l 5' will print only the topmost 5 lines of
information about class constructors.
-r: return the pstats.Stats object generated by the profiling. This
object has all the information about the profile in it, and you can
later use it for further analysis or in other functions.
-s <key>: sort profile by given key. You can provide more than one key
by using the option several times: '-s key1 -s key2 -s key3...'. The
default sorting key is 'time'.
The following is copied verbatim from the profile documentation
referenced below:
When more than one key is provided, additional keys are used as
secondary criteria when the there is equality in all keys selected
before them.
Abbreviations can be used for any key names, as long as the
abbreviation is unambiguous. The following are the keys currently
defined:
Valid Arg Meaning
"calls" call count
"cumulative" cumulative time
"file" file name
"module" file name
"pcalls" primitive call count
"line" line number
"name" function name
"nfl" name/file/line
"stdname" standard name
"time" internal time
Note that all sorts on statistics are in descending order (placing
most time consuming items first), where as name, file, and line number
searches are in ascending order (i.e., alphabetical). The subtle
distinction between "nfl" and "stdname" is that the standard name is a
sort of the name as printed, which means that the embedded line
numbers get compared in an odd way. For example, lines 3, 20, and 40
would (if the file names were the same) appear in the string order
"20" "3" and "40". In contrast, "nfl" does a numeric compare of the
line numbers. In fact, sort_stats("nfl") is the same as
sort_stats("name", "file", "line").
-T <filename>: save profile results as shown on screen to a text
file. The profile is still shown on screen.
-D <filename>: save (via dump_stats) profile statistics to given
filename. This data is in a format understood by the pstats module, and
is generated by a call to the dump_stats() method of profile
objects. The profile is still shown on screen.
-q: suppress output to the pager. Best used with -T and/or -D above.
If you want to run complete programs under the profiler's control, use
'%run -p [prof_opts] filename.py [args to program]' where prof_opts
contains profiler specific options as described here.
You can read the complete documentation for the profile module with::
In [1]: import profile; profile.help()
"""
opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
if user_mode: # regular user call
opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
list_all=True, posix=False)
namespace = self.shell.user_ns
if cell is not None:
arg_str += '\n' + cell
else: # called to run a program by %run -p
try:
filename = get_py_filename(arg_lst[0])
except IOError as e:
try:
msg = str(e)
except UnicodeError:
msg = e.message
error(msg)
return
arg_str = 'execfile(filename,prog_ns)'
namespace = {
'execfile': self.shell.safe_execfile,
'prog_ns': prog_ns,
'filename': filename
}
opts.merge(opts_def)
prof = profile.Profile()
try:
prof = prof.runctx(arg_str,namespace,namespace)
sys_exit = ''
except SystemExit:
sys_exit = """*** SystemExit exception caught in code being profiled."""
stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
lims = opts.l
if lims:
lims = [] # rebuild lims with ints/floats/strings
for lim in opts.l:
try:
lims.append(int(lim))
except ValueError:
try:
lims.append(float(lim))
except ValueError:
lims.append(lim)
# Trap output.
stdout_trap = StringIO()
stats_stream = stats.stream
try:
stats.stream = stdout_trap
stats.print_stats(*lims)
finally:
stats.stream = stats_stream
output = stdout_trap.getvalue()
output = output.rstrip()
if 'q' not in opts:
page.page(output)
print sys_exit,
dump_file = opts.D[0]
text_file = opts.T[0]
if dump_file:
dump_file = unquote_filename(dump_file)
prof.dump_stats(dump_file)
print '\n*** Profile stats marshalled to file',\
repr(dump_file)+'.',sys_exit
if text_file:
text_file = unquote_filename(text_file)
pfile = open(text_file,'w')
pfile.write(output)
pfile.close()
print '\n*** Profile printout saved to text file',\
repr(text_file)+'.',sys_exit
if 'r' in opts:
return stats
else:
return None
def test_unicode_in_filename():
try:
# these calls should not throw unicode encode exceptions
path.get_py_filename(u'fooéè.py', force_win32=False)
except IOError as ex:
str(ex)
def prun(self,
parameter_s='',
cell=None,
user_mode=True,
opts=None,
arg_lst=None,
prog_ns=None):
"""Run a statement through the python code profiler.
Usage, in line mode:
%prun [options] statement
Usage, in cell mode:
%%prun [options] [statement]
code...
code...
In cell mode, the additional code lines are appended to the (possibly
empty) statement in the first line. Cell mode allows you to easily
profile multiline blocks without having to put them in a separate
function.
The given statement (which doesn't require quote marks) is run via the
python profiler in a manner similar to the profile.run() function.
Namespaces are internally managed to work correctly; profile.run
cannot be used in IPython because it makes certain assumptions about
namespaces which do not hold under IPython.
Options:
-l <limit>: you can place restrictions on what or how much of the
profile gets printed. The limit value can be:
* A string: only information for function names containing this string
is printed.
* An integer: only these many lines are printed.
* A float (between 0 and 1): this fraction of the report is printed
(for example, use a limit of 0.4 to see the topmost 40% only).
You can combine several limits with repeated use of the option. For
example, '-l __init__ -l 5' will print only the topmost 5 lines of
information about class constructors.
-r: return the pstats.Stats object generated by the profiling. This
object has all the information about the profile in it, and you can
later use it for further analysis or in other functions.
-s <key>: sort profile by given key. You can provide more than one key
by using the option several times: '-s key1 -s key2 -s key3...'. The
default sorting key is 'time'.
The following is copied verbatim from the profile documentation
referenced below:
When more than one key is provided, additional keys are used as
secondary criteria when the there is equality in all keys selected
before them.
Abbreviations can be used for any key names, as long as the
abbreviation is unambiguous. The following are the keys currently
defined:
Valid Arg Meaning
"calls" call count
"cumulative" cumulative time
"file" file name
"module" file name
"pcalls" primitive call count
"line" line number
"name" function name
"nfl" name/file/line
"stdname" standard name
"time" internal time
Note that all sorts on statistics are in descending order (placing
most time consuming items first), where as name, file, and line number
searches are in ascending order (i.e., alphabetical). The subtle
distinction between "nfl" and "stdname" is that the standard name is a
sort of the name as printed, which means that the embedded line
numbers get compared in an odd way. For example, lines 3, 20, and 40
would (if the file names were the same) appear in the string order
"20" "3" and "40". In contrast, "nfl" does a numeric compare of the
line numbers. In fact, sort_stats("nfl") is the same as
sort_stats("name", "file", "line").
-T <filename>: save profile results as shown on screen to a text
file. The profile is still shown on screen.
-D <filename>: save (via dump_stats) profile statistics to given
filename. This data is in a format understood by the pstats module, and
is generated by a call to the dump_stats() method of profile
objects. The profile is still shown on screen.
-q: suppress output to the pager. Best used with -T and/or -D above.
If you want to run complete programs under the profiler's control, use
'%run -p [prof_opts] filename.py [args to program]' where prof_opts
contains profiler specific options as described here.
You can read the complete documentation for the profile module with::
In [1]: import profile; profile.help()
"""
opts_def = Struct(D=[''], l=[], s=['time'], T=[''])
if user_mode: # regular user call
opts, arg_str = self.parse_options(parameter_s,
'D:l:rs:T:q',
list_all=True,
posix=False)
namespace = self.shell.user_ns
if cell is not None:
arg_str += '\n' + cell
else: # called to run a program by %run -p
try:
filename = get_py_filename(arg_lst[0])
except IOError as e:
try:
msg = str(e)
except UnicodeError:
msg = e.message
error(msg)
return
arg_str = 'execfile(filename,prog_ns)'
namespace = {
'execfile': self.shell.safe_execfile,
'prog_ns': prog_ns,
'filename': filename
}
opts.merge(opts_def)
prof = profile.Profile()
try:
prof = prof.runctx(arg_str, namespace, namespace)
sys_exit = ''
except SystemExit:
sys_exit = """*** SystemExit exception caught in code being profiled."""
stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
lims = opts.l
if lims:
lims = [] # rebuild lims with ints/floats/strings
for lim in opts.l:
try:
lims.append(int(lim))
except ValueError:
try:
lims.append(float(lim))
except ValueError:
lims.append(lim)
# Trap output.
stdout_trap = StringIO()
stats_stream = stats.stream
try:
stats.stream = stdout_trap
stats.print_stats(*lims)
finally:
stats.stream = stats_stream
output = stdout_trap.getvalue()
output = output.rstrip()
if 'q' not in opts:
page.page(output)
print sys_exit,
dump_file = opts.D[0]
text_file = opts.T[0]
if dump_file:
dump_file = unquote_filename(dump_file)
prof.dump_stats(dump_file)
print '\n*** Profile stats marshalled to file',\
repr(dump_file)+'.',sys_exit
if text_file:
text_file = unquote_filename(text_file)
pfile = open(text_file, 'w')
pfile.write(output)
pfile.close()
print '\n*** Profile printout saved to text file',\
repr(text_file)+'.',sys_exit
if 'r' in opts:
return stats
else:
return None
def run(self, parameter_s='', runner=None,
file_finder=get_py_filename):
"""Run the named file inside IPython as a program.
Usage:
%run [-n -i -e -G]
[( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
( -m mod | file ) [args]
Parameters after the filename are passed as command-line arguments to
the program (put in sys.argv). Then, control returns to IPython's
prompt.
This is similar to running at a system prompt:\\
$ python file args\\
but with the advantage of giving you IPython's tracebacks, and of
loading all variables into your interactive namespace for further use
(unless -p is used, see below).
The file is executed in a namespace initially consisting only of
__name__=='__main__' and sys.argv constructed as indicated. It thus
sees its environment as if it were being run as a stand-alone program
(except for sharing global objects such as previously imported
modules). But after execution, the IPython interactive namespace gets
updated with all variables defined in the program (except for __name__
and sys.argv). This allows for very convenient loading of code for
interactive work, while giving each program a 'clean sheet' to run in.
Arguments are expanded using shell-like glob match. Patterns
'*', '?', '[seq]' and '[!seq]' can be used. Additionally,
tilde '~' will be expanded into user's home directory. Unlike
real shells, quotation does not suppress expansions. Use
*two* back slashes (e.g., '\\\\*') to suppress expansions.
To completely disable these expansions, you can use -G flag.
Options:
-n: __name__ is NOT set to '__main__', but to the running file's name
without extension (as python does under import). This allows running
scripts and reloading the definitions in them without calling code
protected by an ' if __name__ == "__main__" ' clause.
-i: run the file in IPython's namespace instead of an empty one. This
is useful if you are experimenting with code written in a text editor
which depends on variables defined interactively.
-e: ignore sys.exit() calls or SystemExit exceptions in the script
being run. This is particularly useful if IPython is being used to
run unittests, which always exit with a sys.exit() call. In such
cases you are interested in the output of the test results, not in
seeing a traceback of the unittest module.
-t: print timing information at the end of the run. IPython will give
you an estimated CPU time consumption for your script, which under
Unix uses the resource module to avoid the wraparound problems of
time.clock(). Under Unix, an estimate of time spent on system tasks
is also given (for Windows platforms this is reported as 0.0).
If -t is given, an additional -N<N> option can be given, where <N>
must be an integer indicating how many times you want the script to
run. The final timing report will include total and per run results.
For example (testing the script uniq_stable.py)::
In [1]: run -t uniq_stable
IPython CPU timings (estimated):\\
User : 0.19597 s.\\
System: 0.0 s.\\
In [2]: run -t -N5 uniq_stable
IPython CPU timings (estimated):\\
Total runs performed: 5\\
Times : Total Per run\\
User : 0.910862 s, 0.1821724 s.\\
System: 0.0 s, 0.0 s.
-d: run your program under the control of pdb, the Python debugger.
This allows you to execute your program step by step, watch variables,
etc. Internally, what IPython does is similar to calling:
pdb.run('execfile("YOURFILENAME")')
with a breakpoint set on line 1 of your file. You can change the line
number for this automatic breakpoint to be <N> by using the -bN option
(where N must be an integer). For example::
%run -d -b40 myscript
will set the first breakpoint at line 40 in myscript.py. Note that
the first breakpoint must be set on a line which actually does
something (not a comment or docstring) for it to stop execution.
Or you can specify a breakpoint in a different file::
%run -d -b myotherfile.py:20 myscript
When the pdb debugger starts, you will see a (Pdb) prompt. You must
first enter 'c' (without quotes) to start execution up to the first
breakpoint.
Entering 'help' gives information about the use of the debugger. You
can easily see pdb's full documentation with "import pdb;pdb.help()"
at a prompt.
-p: run program under the control of the Python profiler module (which
prints a detailed report of execution times, function calls, etc).
You can pass other options after -p which affect the behavior of the
profiler itself. See the docs for %prun for details.
In this mode, the program's variables do NOT propagate back to the
IPython interactive namespace (because they remain in the namespace
where the profiler executes them).
Internally this triggers a call to %prun, see its documentation for
details on the options available specifically for profiling.
There is one special usage for which the text above doesn't apply:
if the filename ends with .ipy, the file is run as ipython script,
just as if the commands were written on IPython prompt.
-m: specify module name to load instead of script path. Similar to
the -m option for the python interpreter. Use this option last if you
want to combine with other %run options. Unlike the python interpreter
only source modules are allowed no .pyc or .pyo files.
For example::
%run -m example
will run the example module.
-G: disable shell-like glob expansion of arguments.
"""
# get arguments and set sys.argv for program to be run.
opts, arg_lst = self.parse_options(parameter_s,
'nidtN:b:pD:l:rs:T:em:G',
mode='list', list_all=1)
if "m" in opts:
modulename = opts["m"][0]
modpath = find_mod(modulename)
if modpath is None:
warn('%r is not a valid modulename on sys.path'%modulename)
return
arg_lst = [modpath] + arg_lst
try:
filename = file_finder(arg_lst[0])
except IndexError:
warn('you must provide at least a filename.')
print '\n%run:\n', oinspect.getdoc(self.run)
return
except IOError as e:
try:
msg = str(e)
except UnicodeError:
msg = e.message
error(msg)
return
if filename.lower().endswith('.ipy'):
with preserve_keys(self.shell.user_ns, '__file__'):
self.shell.user_ns['__file__'] = filename
self.shell.safe_execfile_ipy(filename)
return
# Control the response to exit() calls made by the script being run
exit_ignore = 'e' in opts
# Make sure that the running script gets a proper sys.argv as if it
# were run from a system shell.
save_argv = sys.argv # save it for later restoring
if 'G' in opts:
args = arg_lst[1:]
else:
# tilde and glob expansion
args = shellglob(map(os.path.expanduser, arg_lst[1:]))
sys.argv = [filename] + args # put in the proper filename
# protect sys.argv from potential unicode strings on Python 2:
if not py3compat.PY3:
sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
if 'i' in opts:
# Run in user's interactive namespace
prog_ns = self.shell.user_ns
__name__save = self.shell.user_ns['__name__']
prog_ns['__name__'] = '__main__'
main_mod = self.shell.new_main_mod(prog_ns)
else:
# Run in a fresh, empty namespace
if 'n' in opts:
name = os.path.splitext(os.path.basename(filename))[0]
else:
name = '__main__'
main_mod = self.shell.new_main_mod()
prog_ns = main_mod.__dict__
prog_ns['__name__'] = name
# Since '%run foo' emulates 'python foo.py' at the cmd line, we must
# set the __file__ global in the script's namespace
prog_ns['__file__'] = filename
# pickle fix. See interactiveshell for an explanation. But we need to
# make sure that, if we overwrite __main__, we replace it at the end
main_mod_name = prog_ns['__name__']
if main_mod_name == '__main__':
restore_main = sys.modules['__main__']
else:
restore_main = False
# This needs to be undone at the end to prevent holding references to
# every single object ever created.
sys.modules[main_mod_name] = main_mod
if 'p' in opts or 'd' in opts:
if 'm' in opts:
code = 'run_module(modulename, prog_ns)'
code_ns = {
'run_module': self.shell.safe_run_module,
'prog_ns': prog_ns,
'modulename': modulename,
}
else:
code = 'execfile(filename, prog_ns)'
code_ns = {
'execfile': self.shell.safe_execfile,
'prog_ns': prog_ns,
'filename': get_py_filename(filename),
}
try:
stats = None
with self.shell.readline_no_record:
if 'p' in opts:
stats = self._run_with_profiler(code, opts, code_ns)
else:
if 'd' in opts:
self._run_with_debugger(
code, code_ns, opts.get('b', ['1'])[0], filename)
else:
if 'm' in opts:
def run():
self.shell.safe_run_module(modulename, prog_ns)
else:
if runner is None:
runner = self.default_runner
if runner is None:
runner = self.shell.safe_execfile
def run():
runner(filename, prog_ns, prog_ns,
exit_ignore=exit_ignore)
if 't' in opts:
# timed execution
try:
nruns = int(opts['N'][0])
if nruns < 1:
error('Number of runs must be >=1')
return
except (KeyError):
nruns = 1
self._run_with_timing(run, nruns)
else:
# regular execution
run()
if 'i' in opts:
self.shell.user_ns['__name__'] = __name__save
else:
# The shell MUST hold a reference to prog_ns so after %run
# exits, the python deletion mechanism doesn't zero it out
# (leaving dangling references).
self.shell.cache_main_mod(prog_ns, filename)
# update IPython interactive namespace
# Some forms of read errors on the file may mean the
# __name__ key was never set; using pop we don't have to
# worry about a possible KeyError.
prog_ns.pop('__name__', None)
with preserve_keys(self.shell.user_ns, '__file__'):
self.shell.user_ns.update(prog_ns)
finally:
# It's a bit of a mystery why, but __builtins__ can change from
# being a module to becoming a dict missing some key data after
# %run. As best I can see, this is NOT something IPython is doing
# at all, and similar problems have been reported before:
# http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
# Since this seems to be done by the interpreter itself, the best
# we can do is to at least restore __builtins__ for the user on
# exit.
self.shell.user_ns['__builtins__'] = builtin_mod
# Ensure key global structures are restored
sys.argv = save_argv
if restore_main:
sys.modules['__main__'] = restore_main
else:
# Remove from sys.modules the reference to main_mod we'd
# added. Otherwise it will trap references to objects
# contained therein.
del sys.modules[main_mod_name]
return stats
def run(self, parameter_s='', runner=None, file_finder=get_py_filename):
"""Run the named file inside IPython as a program.
Usage::
%run [-n -i -e -G]
[( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
( -m mod | file ) [args]
Parameters after the filename are passed as command-line arguments to
the program (put in sys.argv). Then, control returns to IPython's
prompt.
This is similar to running at a system prompt ``python file args``,
but with the advantage of giving you IPython's tracebacks, and of
loading all variables into your interactive namespace for further use
(unless -p is used, see below).
The file is executed in a namespace initially consisting only of
``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
sees its environment as if it were being run as a stand-alone program
(except for sharing global objects such as previously imported
modules). But after execution, the IPython interactive namespace gets
updated with all variables defined in the program (except for __name__
and sys.argv). This allows for very convenient loading of code for
interactive work, while giving each program a 'clean sheet' to run in.
Arguments are expanded using shell-like glob match. Patterns
'*', '?', '[seq]' and '[!seq]' can be used. Additionally,
tilde '~' will be expanded into user's home directory. Unlike
real shells, quotation does not suppress expansions. Use
*two* back slashes (e.g. ``\\\\*``) to suppress expansions.
To completely disable these expansions, you can use -G flag.
Options:
-n
__name__ is NOT set to '__main__', but to the running file's name
without extension (as python does under import). This allows running
scripts and reloading the definitions in them without calling code
protected by an ``if __name__ == "__main__"`` clause.
-i
run the file in IPython's namespace instead of an empty one. This
is useful if you are experimenting with code written in a text editor
which depends on variables defined interactively.
-e
ignore sys.exit() calls or SystemExit exceptions in the script
being run. This is particularly useful if IPython is being used to
run unittests, which always exit with a sys.exit() call. In such
cases you are interested in the output of the test results, not in
seeing a traceback of the unittest module.
-t
print timing information at the end of the run. IPython will give
you an estimated CPU time consumption for your script, which under
Unix uses the resource module to avoid the wraparound problems of
time.clock(). Under Unix, an estimate of time spent on system tasks
is also given (for Windows platforms this is reported as 0.0).
If -t is given, an additional ``-N<N>`` option can be given, where <N>
must be an integer indicating how many times you want the script to
run. The final timing report will include total and per run results.
For example (testing the script uniq_stable.py)::
In [1]: run -t uniq_stable
IPython CPU timings (estimated):
User : 0.19597 s.
System: 0.0 s.
In [2]: run -t -N5 uniq_stable
IPython CPU timings (estimated):
Total runs performed: 5
Times : Total Per run
User : 0.910862 s, 0.1821724 s.
System: 0.0 s, 0.0 s.
-d
run your program under the control of pdb, the Python debugger.
This allows you to execute your program step by step, watch variables,
etc. Internally, what IPython does is similar to calling::
pdb.run('execfile("YOURFILENAME")')
with a breakpoint set on line 1 of your file. You can change the line
number for this automatic breakpoint to be <N> by using the -bN option
(where N must be an integer). For example::
%run -d -b40 myscript
will set the first breakpoint at line 40 in myscript.py. Note that
the first breakpoint must be set on a line which actually does
something (not a comment or docstring) for it to stop execution.
Or you can specify a breakpoint in a different file::
%run -d -b myotherfile.py:20 myscript
When the pdb debugger starts, you will see a (Pdb) prompt. You must
first enter 'c' (without quotes) to start execution up to the first
breakpoint.
Entering 'help' gives information about the use of the debugger. You
can easily see pdb's full documentation with "import pdb;pdb.help()"
at a prompt.
-p
run program under the control of the Python profiler module (which
prints a detailed report of execution times, function calls, etc).
You can pass other options after -p which affect the behavior of the
profiler itself. See the docs for %prun for details.
In this mode, the program's variables do NOT propagate back to the
IPython interactive namespace (because they remain in the namespace
where the profiler executes them).
Internally this triggers a call to %prun, see its documentation for
details on the options available specifically for profiling.
There is one special usage for which the text above doesn't apply:
if the filename ends with .ipy, the file is run as ipython script,
just as if the commands were written on IPython prompt.
-m
specify module name to load instead of script path. Similar to
the -m option for the python interpreter. Use this option last if you
want to combine with other %run options. Unlike the python interpreter
only source modules are allowed no .pyc or .pyo files.
For example::
%run -m example
will run the example module.
-G
disable shell-like glob expansion of arguments.
"""
# get arguments and set sys.argv for program to be run.
opts, arg_lst = self.parse_options(parameter_s,
'nidtN:b:pD:l:rs:T:em:G',
mode='list',
list_all=1)
if "m" in opts:
modulename = opts["m"][0]
modpath = find_mod(modulename)
if modpath is None:
warn('%r is not a valid modulename on sys.path' % modulename)
return
arg_lst = [modpath] + arg_lst
try:
filename = file_finder(arg_lst[0])
except IndexError:
warn('you must provide at least a filename.')
print '\n%run:\n', oinspect.getdoc(self.run)
return
except IOError as e:
try:
msg = str(e)
except UnicodeError:
msg = e.message
error(msg)
return
if filename.lower().endswith('.ipy'):
with preserve_keys(self.shell.user_ns, '__file__'):
self.shell.user_ns['__file__'] = filename
self.shell.safe_execfile_ipy(filename)
return
# Control the response to exit() calls made by the script being run
exit_ignore = 'e' in opts
# Make sure that the running script gets a proper sys.argv as if it
# were run from a system shell.
save_argv = sys.argv # save it for later restoring
if 'G' in opts:
args = arg_lst[1:]
else:
# tilde and glob expansion
args = shellglob(map(os.path.expanduser, arg_lst[1:]))
sys.argv = [filename] + args # put in the proper filename
# protect sys.argv from potential unicode strings on Python 2:
if not py3compat.PY3:
sys.argv = [py3compat.cast_bytes(a) for a in sys.argv]
if 'i' in opts:
# Run in user's interactive namespace
prog_ns = self.shell.user_ns
__name__save = self.shell.user_ns['__name__']
prog_ns['__name__'] = '__main__'
main_mod = self.shell.user_module
# Since '%run foo' emulates 'python foo.py' at the cmd line, we must
# set the __file__ global in the script's namespace
# TK: Is this necessary in interactive mode?
prog_ns['__file__'] = filename
else:
# Run in a fresh, empty namespace
if 'n' in opts:
name = os.path.splitext(os.path.basename(filename))[0]
else:
name = '__main__'
# The shell MUST hold a reference to prog_ns so after %run
# exits, the python deletion mechanism doesn't zero it out
# (leaving dangling references). See interactiveshell for details
main_mod = self.shell.new_main_mod(filename, name)
prog_ns = main_mod.__dict__
# pickle fix. See interactiveshell for an explanation. But we need to
# make sure that, if we overwrite __main__, we replace it at the end
main_mod_name = prog_ns['__name__']
if main_mod_name == '__main__':
restore_main = sys.modules['__main__']
else:
restore_main = False
# This needs to be undone at the end to prevent holding references to
# every single object ever created.
sys.modules[main_mod_name] = main_mod
if 'p' in opts or 'd' in opts:
if 'm' in opts:
code = 'run_module(modulename, prog_ns)'
code_ns = {
'run_module': self.shell.safe_run_module,
'prog_ns': prog_ns,
'modulename': modulename,
}
else:
code = 'execfile(filename, prog_ns)'
code_ns = {
'execfile': self.shell.safe_execfile,
'prog_ns': prog_ns,
'filename': get_py_filename(filename),
}
try:
stats = None
with self.shell.readline_no_record:
if 'p' in opts:
stats = self._run_with_profiler(code, opts, code_ns)
else:
if 'd' in opts:
bp_file, bp_line = parse_breakpoint(
opts.get('b', ['1'])[0], filename)
self._run_with_debugger(code, code_ns, filename,
bp_line, bp_file)
else:
if 'm' in opts:
def run():
self.shell.safe_run_module(modulename, prog_ns)
else:
if runner is None:
runner = self.default_runner
if runner is None:
runner = self.shell.safe_execfile
def run():
runner(filename,
prog_ns,
prog_ns,
exit_ignore=exit_ignore)
if 't' in opts:
# timed execution
try:
nruns = int(opts['N'][0])
if nruns < 1:
error('Number of runs must be >=1')
return
except (KeyError):
nruns = 1
self._run_with_timing(run, nruns)
else:
# regular execution
run()
if 'i' in opts:
self.shell.user_ns['__name__'] = __name__save
else:
# update IPython interactive namespace
# Some forms of read errors on the file may mean the
# __name__ key was never set; using pop we don't have to
# worry about a possible KeyError.
prog_ns.pop('__name__', None)
with preserve_keys(self.shell.user_ns, '__file__'):
self.shell.user_ns.update(prog_ns)
finally:
# It's a bit of a mystery why, but __builtins__ can change from
# being a module to becoming a dict missing some key data after
# %run. As best I can see, this is NOT something IPython is doing
# at all, and similar problems have been reported before:
# http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
# Since this seems to be done by the interpreter itself, the best
# we can do is to at least restore __builtins__ for the user on
# exit.
self.shell.user_ns['__builtins__'] = builtin_mod
# Ensure key global structures are restored
sys.argv = save_argv
if restore_main:
sys.modules['__main__'] = restore_main
else:
# Remove from sys.modules the reference to main_mod we'd
# added. Otherwise it will trap references to objects
# contained therein.
del sys.modules[main_mod_name]
return stats