/pylons-rest-ENV/lib/python2.6/site-packages/IPython/Magic.py
Python | 3526 lines | 3469 code | 23 blank | 34 comment | 27 complexity | e32312778e89911061f36e91c67d3a6f MD5 | raw file
Possible License(s): 0BSD
Large files files are truncated, but you can click here to view the full file
- # -*- coding: utf-8 -*-
- """Magic functions for InteractiveShell.
- """
- #*****************************************************************************
- # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
- # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
- #
- # Distributed under the terms of the BSD License. The full license is in
- # the file COPYING, distributed as part of this software.
- #*****************************************************************************
- #****************************************************************************
- # Modules and globals
- # Python standard modules
- import __builtin__
- import bdb
- import inspect
- import os
- import pdb
- import pydoc
- import sys
- import re
- import tempfile
- import time
- import cPickle as pickle
- import textwrap
- from cStringIO import StringIO
- from getopt import getopt,GetoptError
- from pprint import pprint, pformat
- # cProfile was added in Python2.5
- try:
- import cProfile as profile
- import pstats
- except ImportError:
- # profile isn't bundled by default in Debian for license reasons
- try:
- import profile,pstats
- except ImportError:
- profile = pstats = None
- # Homebrewed
- import IPython
- from IPython import Debugger, OInspect, wildcard
- from IPython.FakeModule import FakeModule
- from IPython.Itpl import Itpl, itpl, printpl,itplns
- from IPython.PyColorize import Parser
- from IPython.ipstruct import Struct
- from IPython.macro import Macro
- from IPython.genutils import *
- from IPython import platutils
- import IPython.generics
- import IPython.ipapi
- from IPython.ipapi import UsageError
- from IPython.testing import decorators as testdec
- #***************************************************************************
- # Utility functions
- def on_off(tag):
- """Return an ON/OFF string for a 1/0 input. Simple utility function."""
- return ['OFF','ON'][tag]
- class Bunch: pass
- def compress_dhist(dh):
- head, tail = dh[:-10], dh[-10:]
- newhead = []
- done = set()
- for h in head:
- if h in done:
- continue
- newhead.append(h)
- done.add(h)
- return newhead + tail
-
- #***************************************************************************
- # Main class implementing Magic functionality
- class Magic:
- """Magic functions for InteractiveShell.
- Shell functions which can be reached as %function_name. All magic
- functions should accept a string, which they can parse for their own
- needs. This can make some functions easier to type, eg `%cd ../`
- vs. `%cd("../")`
- ALL definitions MUST begin with the prefix magic_. The user won't need it
- at the command line, but it is is needed in the definition. """
- # class globals
- auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
- 'Automagic is ON, % prefix NOT needed for magic functions.']
- #......................................................................
- # some utility functions
- def __init__(self,shell):
-
- self.options_table = {}
- if profile is None:
- self.magic_prun = self.profile_missing_notice
- self.shell = shell
- # namespace for holding state we may need
- self._magic_state = Bunch()
- def profile_missing_notice(self, *args, **kwargs):
- error("""\
- The profile module could not be found. It has been removed from the standard
- python packages because of its non-free license. To use profiling, install the
- python-profiler package from non-free.""")
- def default_option(self,fn,optstr):
- """Make an entry in the options_table for fn, with value optstr"""
- if fn not in self.lsmagic():
- error("%s is not a magic function" % fn)
- self.options_table[fn] = optstr
- def lsmagic(self):
- """Return a list of currently available magic functions.
- Gives a list of the bare names after mangling (['ls','cd', ...], not
- ['magic_ls','magic_cd',...]"""
- # FIXME. This needs a cleanup, in the way the magics list is built.
-
- # magics in class definition
- class_magic = lambda fn: fn.startswith('magic_') and \
- callable(Magic.__dict__[fn])
- # in instance namespace (run-time user additions)
- inst_magic = lambda fn: fn.startswith('magic_') and \
- callable(self.__dict__[fn])
- # and bound magics by user (so they can access self):
- inst_bound_magic = lambda fn: fn.startswith('magic_') and \
- callable(self.__class__.__dict__[fn])
- magics = filter(class_magic,Magic.__dict__.keys()) + \
- filter(inst_magic,self.__dict__.keys()) + \
- filter(inst_bound_magic,self.__class__.__dict__.keys())
- out = []
- for fn in set(magics):
- out.append(fn.replace('magic_','',1))
- out.sort()
- return out
-
- def extract_input_slices(self,slices,raw=False):
- """Return as a string a set of input history slices.
- Inputs:
- - slices: the set of slices is given as a list of strings (like
- ['1','4:8','9'], since this function is for use by magic functions
- which get their arguments as strings.
- Optional inputs:
- - raw(False): by default, the processed input is used. If this is
- true, the raw input history is used instead.
- Note that slices can be called with two notations:
- N:M -> standard python form, means including items N...(M-1).
- N-M -> include items N..M (closed endpoint)."""
- if raw:
- hist = self.shell.input_hist_raw
- else:
- hist = self.shell.input_hist
- cmds = []
- for chunk in slices:
- if ':' in chunk:
- ini,fin = map(int,chunk.split(':'))
- elif '-' in chunk:
- ini,fin = map(int,chunk.split('-'))
- fin += 1
- else:
- ini = int(chunk)
- fin = ini+1
- cmds.append(hist[ini:fin])
- return cmds
-
- def _ofind(self, oname, namespaces=None):
- """Find an object in the available namespaces.
- self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
- Has special code to detect magic functions.
- """
-
- oname = oname.strip()
- alias_ns = None
- if namespaces is None:
- # Namespaces to search in:
- # Put them in a list. The order is important so that we
- # find things in the same order that Python finds them.
- namespaces = [ ('Interactive', self.shell.user_ns),
- ('IPython internal', self.shell.internal_ns),
- ('Python builtin', __builtin__.__dict__),
- ('Alias', self.shell.alias_table),
- ]
- alias_ns = self.shell.alias_table
- # initialize results to 'null'
- found = 0; obj = None; ospace = None; ds = None;
- ismagic = 0; isalias = 0; parent = None
- # Look for the given name by splitting it in parts. If the head is
- # found, then we look for all the remaining parts as members, and only
- # declare success if we can find them all.
- oname_parts = oname.split('.')
- oname_head, oname_rest = oname_parts[0],oname_parts[1:]
- for nsname,ns in namespaces:
- try:
- obj = ns[oname_head]
- except KeyError:
- continue
- else:
- #print 'oname_rest:', oname_rest # dbg
- for part in oname_rest:
- try:
- parent = obj
- obj = getattr(obj,part)
- except:
- # Blanket except b/c some badly implemented objects
- # allow __getattr__ to raise exceptions other than
- # AttributeError, which then crashes IPython.
- break
- else:
- # If we finish the for loop (no break), we got all members
- found = 1
- ospace = nsname
- if ns == alias_ns:
- isalias = 1
- break # namespace loop
- # Try to see if it's magic
- if not found:
- if oname.startswith(self.shell.ESC_MAGIC):
- oname = oname[1:]
- obj = getattr(self,'magic_'+oname,None)
- if obj is not None:
- found = 1
- ospace = 'IPython internal'
- ismagic = 1
- # Last try: special-case some literals like '', [], {}, etc:
- if not found and oname_head in ["''",'""','[]','{}','()']:
- obj = eval(oname_head)
- found = 1
- ospace = 'Interactive'
-
- return {'found':found, 'obj':obj, 'namespace':ospace,
- 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
-
- def arg_err(self,func):
- """Print docstring if incorrect arguments were passed"""
- print 'Error in arguments:'
- print OInspect.getdoc(func)
- def format_latex(self,strng):
- """Format a string for latex inclusion."""
- # Characters that need to be escaped for latex:
- escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
- # Magic command names as headers:
- cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
- re.MULTILINE)
- # Magic commands
- cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
- re.MULTILINE)
- # Paragraph continue
- par_re = re.compile(r'\\$',re.MULTILINE)
- # The "\n" symbol
- newline_re = re.compile(r'\\n')
- # Now build the string for output:
- #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
- strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
- strng)
- strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
- strng = par_re.sub(r'\\\\',strng)
- strng = escape_re.sub(r'\\\1',strng)
- strng = newline_re.sub(r'\\textbackslash{}n',strng)
- return strng
- def format_screen(self,strng):
- """Format a string for screen printing.
- This removes some latex-type format codes."""
- # Paragraph continue
- par_re = re.compile(r'\\$',re.MULTILINE)
- strng = par_re.sub('',strng)
- return strng
- def parse_options(self,arg_str,opt_str,*long_opts,**kw):
- """Parse options passed to an argument string.
- The interface is similar to that of getopt(), but it returns back a
- Struct with the options as keys and the stripped argument string still
- as a string.
- arg_str is quoted as a true sys.argv vector by using shlex.split.
- This allows us to easily expand variables, glob files, quote
- arguments, etc.
- Options:
- -mode: default 'string'. If given as 'list', the argument string is
- returned as a list (split on whitespace) instead of a string.
- -list_all: put all option values in lists. Normally only options
- appearing more than once are put in a list.
- -posix (True): whether to split the input line in POSIX mode or not,
- as per the conventions outlined in the shlex module from the
- standard library."""
-
- # inject default options at the beginning of the input line
- caller = sys._getframe(1).f_code.co_name.replace('magic_','')
- arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
-
- mode = kw.get('mode','string')
- if mode not in ['string','list']:
- raise ValueError,'incorrect mode given: %s' % mode
- # Get options
- list_all = kw.get('list_all',0)
- posix = kw.get('posix',True)
- # Check if we have more than one argument to warrant extra processing:
- odict = {} # Dictionary with options
- args = arg_str.split()
- if len(args) >= 1:
- # If the list of inputs only has 0 or 1 thing in it, there's no
- # need to look for options
- argv = arg_split(arg_str,posix)
- # Do regular option processing
- try:
- opts,args = getopt(argv,opt_str,*long_opts)
- except GetoptError,e:
- raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
- " ".join(long_opts)))
- for o,a in opts:
- if o.startswith('--'):
- o = o[2:]
- else:
- o = o[1:]
- try:
- odict[o].append(a)
- except AttributeError:
- odict[o] = [odict[o],a]
- except KeyError:
- if list_all:
- odict[o] = [a]
- else:
- odict[o] = a
- # Prepare opts,args for return
- opts = Struct(odict)
- if mode == 'string':
- args = ' '.join(args)
- return opts,args
-
- #......................................................................
- # And now the actual magic functions
- # Functions for IPython shell work (vars,funcs, config, etc)
- def magic_lsmagic(self, parameter_s = ''):
- """List currently available magic functions."""
- mesc = self.shell.ESC_MAGIC
- print 'Available magic functions:\n'+mesc+\
- (' '+mesc).join(self.lsmagic())
- print '\n' + Magic.auto_status[self.shell.rc.automagic]
- return None
-
- def magic_magic(self, parameter_s = ''):
- """Print information about the magic function system.
-
- Supported formats: -latex, -brief, -rest
- """
- mode = ''
- try:
- if parameter_s.split()[0] == '-latex':
- mode = 'latex'
- if parameter_s.split()[0] == '-brief':
- mode = 'brief'
- if parameter_s.split()[0] == '-rest':
- mode = 'rest'
- rest_docs = []
- except:
- pass
- magic_docs = []
- for fname in self.lsmagic():
- mname = 'magic_' + fname
- for space in (Magic,self,self.__class__):
- try:
- fn = space.__dict__[mname]
- except KeyError:
- pass
- else:
- break
- if mode == 'brief':
- # only first line
- if fn.__doc__:
- fndoc = fn.__doc__.split('\n',1)[0]
- else:
- fndoc = 'No documentation'
- else:
- if fn.__doc__:
- fndoc = fn.__doc__.rstrip()
- else:
- fndoc = 'No documentation'
-
-
- if mode == 'rest':
- rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
- fname,fndoc))
-
- else:
- magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
- fname,fndoc))
-
- magic_docs = ''.join(magic_docs)
- if mode == 'rest':
- return "".join(rest_docs)
-
- if mode == 'latex':
- print self.format_latex(magic_docs)
- return
- else:
- magic_docs = self.format_screen(magic_docs)
- if mode == 'brief':
- return magic_docs
-
- outmsg = """
- IPython's 'magic' functions
- ===========================
- The magic function system provides a series of functions which allow you to
- control the behavior of IPython itself, plus a lot of system-type
- features. All these functions are prefixed with a % character, but parameters
- are given without parentheses or quotes.
- NOTE: If you have 'automagic' enabled (via the command line option or with the
- %automagic function), you don't need to type in the % explicitly. By default,
- IPython ships with automagic on, so you should only rarely need the % escape.
- Example: typing '%cd mydir' (without the quotes) changes you working directory
- to 'mydir', if it exists.
- You can define your own magic functions to extend the system. See the supplied
- ipythonrc and example-magic.py files for details (in your ipython
- configuration directory, typically $HOME/.ipython/).
- You can also define your own aliased names for magic functions. In your
- ipythonrc file, placing a line like:
- execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
- will define %pf as a new name for %profile.
- You can also call magics in code using the ipmagic() function, which IPython
- automatically adds to the builtin namespace. Type 'ipmagic?' for details.
- For a list of the available magic functions, use %lsmagic. For a description
- of any of them, type %magic_name?, e.g. '%cd?'.
- Currently the magic system has the following functions:\n"""
- mesc = self.shell.ESC_MAGIC
- outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
- "\n\n%s%s\n\n%s" % (outmsg,
- magic_docs,mesc,mesc,
- (' '+mesc).join(self.lsmagic()),
- Magic.auto_status[self.shell.rc.automagic] ) )
- page(outmsg,screen_lines=self.shell.rc.screen_length)
-
- def magic_autoindent(self, parameter_s = ''):
- """Toggle autoindent on/off (if available)."""
- self.shell.set_autoindent()
- print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
- def magic_automagic(self, parameter_s = ''):
- """Make magic functions callable without having to type the initial %.
- Without argumentsl toggles on/off (when off, you must call it as
- %automagic, of course). With arguments it sets the value, and you can
- use any of (case insensitive):
- - on,1,True: to activate
- - off,0,False: to deactivate.
- Note that magic functions have lowest priority, so if there's a
- variable whose name collides with that of a magic fn, automagic won't
- work for that function (you get the variable instead). However, if you
- delete the variable (del var), the previously shadowed magic function
- becomes visible to automagic again."""
- rc = self.shell.rc
- arg = parameter_s.lower()
- if parameter_s in ('on','1','true'):
- rc.automagic = True
- elif parameter_s in ('off','0','false'):
- rc.automagic = False
- else:
- rc.automagic = not rc.automagic
- print '\n' + Magic.auto_status[rc.automagic]
- @testdec.skip_doctest
- def magic_autocall(self, parameter_s = ''):
- """Make functions callable without having to type parentheses.
- Usage:
- %autocall [mode]
- The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
- value is toggled on and off (remembering the previous state).
- In more detail, these values mean:
- 0 -> fully disabled
- 1 -> active, but do not apply if there are no arguments on the line.
- In this mode, you get:
- In [1]: callable
- Out[1]: <built-in function callable>
- In [2]: callable 'hello'
- ------> callable('hello')
- Out[2]: False
- 2 -> Active always. Even if no arguments are present, the callable
- object is called:
- In [2]: float
- ------> float()
- Out[2]: 0.0
- Note that even with autocall off, you can still use '/' at the start of
- a line to treat the first argument on the command line as a function
- and add parentheses to it:
- In [8]: /str 43
- ------> str(43)
- Out[8]: '43'
- # all-random (note for auto-testing)
- """
- rc = self.shell.rc
- if parameter_s:
- arg = int(parameter_s)
- else:
- arg = 'toggle'
- if not arg in (0,1,2,'toggle'):
- error('Valid modes: (0->Off, 1->Smart, 2->Full')
- return
- if arg in (0,1,2):
- rc.autocall = arg
- else: # toggle
- if rc.autocall:
- self._magic_state.autocall_save = rc.autocall
- rc.autocall = 0
- else:
- try:
- rc.autocall = self._magic_state.autocall_save
- except AttributeError:
- rc.autocall = self._magic_state.autocall_save = 1
- print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
- def magic_system_verbose(self, parameter_s = ''):
- """Set verbose printing of system calls.
- If called without an argument, act as a toggle"""
- if parameter_s:
- val = bool(eval(parameter_s))
- else:
- val = None
-
- self.shell.rc_set_toggle('system_verbose',val)
- print "System verbose printing is:",\
- ['OFF','ON'][self.shell.rc.system_verbose]
- def magic_page(self, parameter_s=''):
- """Pretty print the object and display it through a pager.
-
- %page [options] OBJECT
- If no object is given, use _ (last output).
-
- Options:
- -r: page str(object), don't pretty-print it."""
- # After a function contributed by Olivier Aubert, slightly modified.
- # Process options/args
- opts,args = self.parse_options(parameter_s,'r')
- raw = 'r' in opts
- oname = args and args or '_'
- info = self._ofind(oname)
- if info['found']:
- txt = (raw and str or pformat)( info['obj'] )
- page(txt)
- else:
- print 'Object `%s` not found' % oname
- def magic_profile(self, parameter_s=''):
- """Print your currently active IPyhton profile."""
- if self.shell.rc.profile:
- printpl('Current IPython profile: $self.shell.rc.profile.')
- else:
- print 'No profile active.'
- def magic_pinfo(self, parameter_s='', namespaces=None):
- """Provide detailed information about an object.
-
- '%pinfo object' is just a synonym for object? or ?object."""
-
- #print 'pinfo par: <%s>' % parameter_s # dbg
-
-
- # detail_level: 0 -> obj? , 1 -> obj??
- detail_level = 0
- # We need to detect if we got called as 'pinfo pinfo foo', which can
- # happen if the user types 'pinfo foo?' at the cmd line.
- pinfo,qmark1,oname,qmark2 = \
- re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
- if pinfo or qmark1 or qmark2:
- detail_level = 1
- if "*" in oname:
- self.magic_psearch(oname)
- else:
- self._inspect('pinfo', oname, detail_level=detail_level,
- namespaces=namespaces)
- def magic_pdef(self, parameter_s='', namespaces=None):
- """Print the definition header for any callable object.
- If the object is a class, print the constructor information."""
- self._inspect('pdef',parameter_s, namespaces)
- def magic_pdoc(self, parameter_s='', namespaces=None):
- """Print the docstring for an object.
- If the given object is a class, it will print both the class and the
- constructor docstrings."""
- self._inspect('pdoc',parameter_s, namespaces)
- def magic_psource(self, parameter_s='', namespaces=None):
- """Print (or run through pager) the source code for an object."""
- self._inspect('psource',parameter_s, namespaces)
- def magic_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._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,msg:
- print msg
- return
- page(self.shell.inspector.format(file(filename).read()))
- def _inspect(self,meth,oname,namespaces=None,**kw):
- """Generic interface to the inspector system.
- This function is meant to be called by pdef, pdoc & friends."""
- #oname = oname.strip()
- #print '1- oname: <%r>' % oname # dbg
- try:
- oname = oname.strip().encode('ascii')
- #print '2- oname: <%r>' % oname # dbg
- except UnicodeEncodeError:
- print 'Python identifiers can only contain ascii characters.'
- return 'not found'
-
- info = Struct(self._ofind(oname, namespaces))
-
- if info.found:
- try:
- IPython.generics.inspect_object(info.obj)
- return
- except IPython.ipapi.TryNext:
- pass
- # Get the docstring of the class property if it exists.
- path = oname.split('.')
- root = '.'.join(path[:-1])
- if info.parent is not None:
- try:
- target = getattr(info.parent, '__class__')
- # The object belongs to a class instance.
- try:
- target = getattr(target, path[-1])
- # The class defines the object.
- if isinstance(target, property):
- oname = root + '.__class__.' + path[-1]
- info = Struct(self._ofind(oname))
- except AttributeError: pass
- except AttributeError: pass
-
- pmethod = getattr(self.shell.inspector,meth)
- formatter = info.ismagic and self.format_screen or None
- if meth == 'pdoc':
- pmethod(info.obj,oname,formatter)
- elif meth == 'pinfo':
- pmethod(info.obj,oname,formatter,info,**kw)
- else:
- pmethod(info.obj,oname)
- else:
- print 'Object `%s` not found.' % oname
- return 'not found' # so callers can take other action
-
- def magic_psearch(self, parameter_s=''):
- """Search for object in namespaces by wildcard.
- %psearch [options] PATTERN [OBJECT TYPE]
- Note: ? can be used as a synonym for %psearch, at the beginning or at
- the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
- rest of the command line must be unchanged (options come first), so
- for example the following forms are equivalent
- %psearch -i a* function
- -i a* function?
- ?-i a* function
- Arguments:
-
- PATTERN
- where PATTERN is a string containing * as a wildcard similar to its
- use in a shell. The pattern is matched in all namespaces on the
- search path. By default objects starting with a single _ are not
- matched, many IPython generated objects have a single
- underscore. The default is case insensitive matching. Matching is
- also done on the attributes of objects and not only on the objects
- in a module.
- [OBJECT TYPE]
- Is the name of a python type from the types module. The name is
- given in lowercase without the ending type, ex. StringType is
- written string. By adding a type here only objects matching the
- given type are matched. Using all here makes the pattern match all
- types (this is the default).
- Options:
- -a: makes the pattern match even objects whose names start with a
- single underscore. These names are normally ommitted from the
- search.
- -i/-c: make the pattern case insensitive/sensitive. If neither of
- these options is given, the default is read from your ipythonrc
- file. The option name which sets this value is
- 'wildcards_case_sensitive'. If this option is not specified in your
- ipythonrc file, IPython's internal default is to do a case sensitive
- search.
- -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
- specifiy can be searched in any of the following namespaces:
- 'builtin', 'user', 'user_global','internal', 'alias', where
- 'builtin' and 'user' are the search defaults. Note that you should
- not use quotes when specifying namespaces.
- 'Builtin' contains the python module builtin, 'user' contains all
- user data, 'alias' only contain the shell aliases and no python
- objects, 'internal' contains objects used by IPython. The
- 'user_global' namespace is only used by embedded IPython instances,
- and it contains module-level globals. You can add namespaces to the
- search with -s or exclude them with -e (these options can be given
- more than once).
-
- Examples:
-
- %psearch a* -> objects beginning with an a
- %psearch -e builtin a* -> objects NOT in the builtin space starting in a
- %psearch a* function -> all functions beginning with an a
- %psearch re.e* -> objects beginning with an e in module re
- %psearch r*.e* -> objects that start with e in modules starting in r
- %psearch r*.* string -> all strings in modules beginning with r
- Case sensitve search:
-
- %psearch -c a* list all object beginning with lower case a
- Show objects beginning with a single _:
-
- %psearch -a _* list objects beginning with a single underscore"""
- try:
- parameter_s = parameter_s.encode('ascii')
- except UnicodeEncodeError:
- print 'Python identifiers can only contain ascii characters.'
- return
- # default namespaces to be searched
- def_search = ['user','builtin']
- # Process options/args
- opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
- opt = opts.get
- shell = self.shell
- psearch = shell.inspector.psearch
- # select case options
- if opts.has_key('i'):
- ignore_case = True
- elif opts.has_key('c'):
- ignore_case = False
- else:
- ignore_case = not shell.rc.wildcards_case_sensitive
- # Build list of namespaces to search from user options
- def_search.extend(opt('s',[]))
- ns_exclude = ns_exclude=opt('e',[])
- ns_search = [nm for nm in def_search if nm not in ns_exclude]
-
- # Call the actual search
- try:
- psearch(args,shell.ns_table,ns_search,
- show_all=opt('a'),ignore_case=ignore_case)
- except:
- shell.showtraceback()
- def magic_who_ls(self, parameter_s=''):
- """Return a sorted list of all interactive variables.
- If arguments are given, only variables of types matching these
- arguments are returned."""
- user_ns = self.shell.user_ns
- internal_ns = self.shell.internal_ns
- user_config_ns = self.shell.user_config_ns
- out = []
- typelist = parameter_s.split()
- for i in user_ns:
- if not (i.startswith('_') or i.startswith('_i')) \
- and not (i in internal_ns or i in user_config_ns):
- if typelist:
- if type(user_ns[i]).__name__ in typelist:
- out.append(i)
- else:
- out.append(i)
- out.sort()
- return out
-
- def magic_who(self, parameter_s=''):
- """Print all interactive variables, with some minimal formatting.
- If any arguments are given, only variables whose type matches one of
- these are printed. For example:
- %who function str
- will only list functions and strings, excluding all other types of
- variables. To find the proper type names, simply use type(var) at a
- command line to see how python prints type names. For example:
- In [1]: type('hello')\\
- Out[1]: <type 'str'>
- indicates that the type name for strings is 'str'.
- %who always excludes executed names loaded through your configuration
- file and things which are internal to IPython.
- This is deliberate, as typically you may load many modules and the
- purpose of %who is to show you only what you've manually defined."""
- varlist = self.magic_who_ls(parameter_s)
- if not varlist:
- if parameter_s:
- print 'No variables match your requested type.'
- else:
- print 'Interactive namespace is empty.'
- return
- # if we have variables, move on...
- count = 0
- for i in varlist:
- print i+'\t',
- count += 1
- if count > 8:
- count = 0
- print
- print
- def magic_whos(self, parameter_s=''):
- """Like %who, but gives some extra information about each variable.
- The same type filtering of %who can be applied here.
- For all variables, the type is printed. Additionally it prints:
-
- - For {},[],(): their length.
- - For numpy and Numeric arrays, a summary with shape, number of
- elements, typecode and size in memory.
- - Everything else: a string representation, snipping their middle if
- too long."""
-
- varnames = self.magic_who_ls(parameter_s)
- if not varnames:
- if parameter_s:
- print 'No variables match your requested type.'
- else:
- print 'Interactive namespace is empty.'
- return
- # if we have variables, move on...
- # for these types, show len() instead of data:
- seq_types = [types.DictType,types.ListType,types.TupleType]
- # for numpy/Numeric arrays, display summary info
- try:
- import numpy
- except ImportError:
- ndarray_type = None
- else:
- ndarray_type = numpy.ndarray.__name__
- try:
- import Numeric
- except ImportError:
- array_type = None
- else:
- array_type = Numeric.ArrayType.__name__
- # Find all variable names and types so we can figure out column sizes
- def get_vars(i):
- return self.shell.user_ns[i]
-
- # some types are well known and can be shorter
- abbrevs = {'IPython.macro.Macro' : 'Macro'}
- def type_name(v):
- tn = type(v).__name__
- return abbrevs.get(tn,tn)
-
- varlist = map(get_vars,varnames)
- typelist = []
- for vv in varlist:
- tt = type_name(vv)
- if tt=='instance':
- typelist.append( abbrevs.get(str(vv.__class__),
- str(vv.__class__)))
- else:
- typelist.append(tt)
- # column labels and # of spaces as separator
- varlabel = 'Variable'
- typelabel = 'Type'
- datalabel = 'Data/Info'
- colsep = 3
- # variable format strings
- vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
- vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
- aformat = "%s: %s elems, type `%s`, %s bytes"
- # find the size of the columns to format the output nicely
- varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
- typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
- # table header
- print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
- ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
- # and the table itself
- kb = 1024
- Mb = 1048576 # kb**2
- for vname,var,vtype in zip(varnames,varlist,typelist):
- print itpl(vformat),
- if vtype in seq_types:
- print len(var)
- elif vtype in [array_type,ndarray_type]:
- vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
- if vtype==ndarray_type:
- # numpy
- vsize = var.size
- vbytes = vsize*var.itemsize
- vdtype = var.dtype
- else:
- # Numeric
- vsize = Numeric.size(var)
- vbytes = vsize*var.itemsize()
- vdtype = var.typecode()
-
- if vbytes < 100000:
- print aformat % (vshape,vsize,vdtype,vbytes)
- else:
- print aformat % (vshape,vsize,vdtype,vbytes),
- if vbytes < Mb:
- print '(%s kb)' % (vbytes/kb,)
- else:
- print '(%s Mb)' % (vbytes/Mb,)
- else:
- try:
- vstr = str(var)
- except UnicodeEncodeError:
- vstr = unicode(var).encode(sys.getdefaultencoding(),
- 'backslashreplace')
- vstr = vstr.replace('\n','\\n')
- if len(vstr) < 50:
- print vstr
- else:
- printpl(vfmt_short)
-
- def magic_reset(self, parameter_s=''):
- """Resets the namespace by removing all names defined by the user.
- Input/Output history are left around in case you need them.
- Parameters
- ----------
- -y : force reset without asking for confirmation.
- Examples
- --------
- In [6]: a = 1
- In [7]: a
- Out[7]: 1
- In [8]: 'a' in _ip.user_ns
- Out[8]: True
- In [9]: %reset -f
- In [10]: 'a' in _ip.user_ns
- Out[10]: False
- """
- if parameter_s == '-f':
- ans = True
- else:
- ans = self.shell.ask_yes_no(
- "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
- if not ans:
- print 'Nothing done.'
- return
- user_ns = self.shell.user_ns
- for i in self.magic_who_ls():
- del(user_ns[i])
-
- # Also flush the private list of module references kept for script
- # execution protection
- self.shell.clear_main_mod_cache()
- def magic_logstart(self,parameter_s=''):
- """Start logging anywhere in a session.
- %logstart [-o|-r|-t] [log_name [log_mode]]
- If no name is given, it defaults to a file named 'ipython_log.py' in your
- current directory, in 'rotate' mode (see below).
- '%logstart name' saves to file 'name' in 'backup' mode. It saves your
- history up to that point and then continues logging.
- %logstart takes a second optional parameter: logging mode. This can be one
- of (note that the modes are given unquoted):\\
- append: well, that says it.\\
- backup: rename (if exists) to name~ and start name.\\
- global: single logfile in your home dir, appended to.\\
- over : overwrite existing log.\\
- rotate: create rotating logs name.1~, name.2~, etc.
- Options:
- -o: log also IPython's output. In this mode, all commands which
- generate an Out[NN] prompt are recorded to the logfile, right after
- their corresponding input line. The output lines are always
- prepended with a '#[Out]# ' marker, so that the log remains valid
- Python code.
- Since this marker is always the same, filtering only the output from
- a log is very easy, using for example a simple awk call:
- awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
- -r: log 'raw' input. Normally, IPython's logs contain the processed
- input, so that user lines are logged in their final form, converted
- into valid Python. For example, %Exit is logged as
- '_ip.magic("Exit"). If the -r flag is given, all input is logged
- exactly as typed, with no transformations applied.
- -t: put timestamps before each input line logged (these are put in
- comments)."""
-
- opts,par = self.parse_options(parameter_s,'ort')
- log_output = 'o' in opts
- log_raw_input = 'r' in opts
- timestamp = 't' in opts
- rc = self.shell.rc
- logger = self.shell.logger
- # if no args are given, the defaults set in the logger constructor by
- # ipytohn remain valid
- if par:
- try:
- logfname,logmode = par.split()
- except:
- logfname = par
- logmode = 'backup'
- else:
- logfname = logger.logfname
- logmode = logger.logmode
- # put logfname into rc struct as if it had been called on the command
- # line, so it ends up saved in the log header Save it in case we need
- # to restore it...
- old_logfile = rc.opts.get('logfile','')
- if logfname:
- logfname = os.path.expanduser(logfname)
- rc.opts.logfile = logfname
- loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
- try:
- started = logger.logstart(logfname,loghead,logmode,
- log_output,timestamp,log_raw_input)
- except:
- rc.opts.logfile = old_logfile
- warn("Couldn't start log: %s" % sys.exc_info()[1])
- else:
- # log input history up to this point, optionally interleaving
- # output if requested
- if timestamp:
- # disable timestamping for the previous history, since we've
- # lost those already (no time machine here).
- logger.timestamp = False
- if log_raw_input:
- input_hist = self.shell.input_hist_raw
- else:
- input_hist = self.shell.input_hist
-
- if log_output:
- log_write = logger.log_write
- output_hist = self.shell.output_hist
- for n in range(1,len(input_hist)-1):
- log_write(input_hist[n].rstrip())
- if n in output_hist:
- log_write(repr(output_hist[n]),'output')
- else:
- logger.log_write(input_hist[1:])
- if timestamp:
- # re-enable timestamping
- logger.timestamp = True
-
- print ('Activating auto-logging. '
- 'Current session state plus future input saved.')
- logger.logstate()
- def magic_logstop(self,parameter_s=''):
- """Fully stop logging and close log file.
- In order to start logging again, a new %logstart call needs to be made,
- possibly (though not necessarily) with a new filename, mode and other
- options."""
- self.logger.logstop()
- def magic_logoff(self,parameter_s=''):
- """Temporarily stop logging.
- You must have previously started logging."""
- self.shell.logger.switch_log(0)
-
- def magic_logon(self,parameter_s=''):
- """Restart logging.
- This function is for restarting logging which you've temporarily
- stopped with %logoff. For starting logging for the first time, you
- must use the %logstart function, which allows you to specify an
- optional log filename."""
-
- self.shell.logger.switch_log(1)
-
- def magic_logstate(self,parameter_s=''):
- """Print the status of the logging system."""
- self.shell.logger.logstate()
-
- def magic_pdb(self, parameter_s=''):
- """Control the automatic calling of the pdb interactive debugger.
- Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
- argument it works as a toggle.
- When an exception is triggered, IPython can optionally call the
- interactive pdb debugger after the traceback printout. %pdb toggles
- this feature on and off.
- The initial state of this feature is set in your ipythonrc
- configuration file (the variable is called 'pdb').
- If you want to just activate the debugger AFTER an exception has fired,
- without having to type '%pdb on' and rerunning your code, you can use
- the %debug magic."""
- par = parameter_s.strip().lower()
- if par:
- try:
- new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
- except KeyError:
- print ('Incorrect argument. Use on/1, off/0, '
- 'or nothing for a toggle.')
- return
- else:
- # toggle
- new_pdb = not self.shell.call_pdb
- # set on the shell
- self.shell.call_pdb = new_pdb
- print 'Automatic pdb calling has been turned',on_off(new_pdb)
- def magic_debug(self, parameter_s=''):
- """Activate the interactive debugger in post-mortem mode.
- If an exception has just occurred, this lets you inspect its stack
- frames interactively. Note that this will always work only on the last
- traceback that occurred, so you must call this quickly after an
- exception that you wish to inspect has fired, because if another one
- occurs, it clobbers the previous one.
- If you want IPython to automatically do this on every exception, see
- the %pdb magic for more details.
- """
-
- self.shell.debugger(force=True)
- @testdec.skip_doctest
- def magic_prun(self, parameter_s ='',user_mode=1,
- opts=None,arg_lst=None,prog_ns=None):
- """Run a statement through the python code profiler.
- Usage:
- %prun [options] statement
- 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 st…
Large files files are truncated, but you can click here to view the full file