| ================================================================================ | |
| py.code: higher level python code and introspection objects | |
| ================================================================================ | |
| ``py.code`` provides higher level APIs and objects for Code, Frame, Traceback, | |
| ExceptionInfo and source code construction. The ``py.code`` library | |
| tries to simplify accessing the code objects as well as creating them. | |
| There is a small set of interfaces a user needs to deal with, all nicely | |
| bundled together, and with a rich set of 'Pythonic' functionality. | |
| Contents of the library | |
| ======================= | |
| Every object in the ``py.code`` library wraps a code Python object related | |
| to code objects, source code, frames and tracebacks: the ``py.code.Code`` | |
| class wraps code objects, ``py.code.Source`` source snippets, | |
| ``py.code.Traceback` exception tracebacks, ``py.code.Frame`` frame | |
| objects (as found in e.g. tracebacks) and ``py.code.ExceptionInfo`` the | |
| tuple provided by sys.exc_info() (containing exception and traceback | |
| information when an exception occurs). Also in the library is a helper function | |
| ``py.code.compile()`` that provides the same functionality as Python's | |
| built-in 'compile()' function, but returns a wrapped code object. | |
| The wrappers | |
| ============ | |
| ``py.code.Code`` | |
| ------------------- | |
| Code objects are instantiated with a code object or a callable as argument, | |
| and provide functionality to compare themselves with other Code objects, get to | |
| the source file or its contents, create new Code objects from scratch, etc. | |
| A quick example:: | |
| >>> import py | |
| >>> c = py.code.Code(py.path.local.read) | |
| >>> c.path.basename | |
| 'common.py' | |
| >>> isinstance(c.source(), py.code.Source) | |
| True | |
| >>> str(c.source()).split('\n')[0] | |
| "def read(self, mode='r'):" | |
| .. autoclass:: py.code.Code | |
| :members: | |
| :inherited-members: | |
| ``py.code.Source`` | |
| --------------------- | |
| Source objects wrap snippets of Python source code, providing a simple yet | |
| powerful interface to read, deindent, slice, compare, compile and manipulate | |
| them, things that are not so easy in core Python. | |
| Example:: | |
| >>> s = py.code.Source("""\ | |
| ... def foo(): | |
| ... print "foo" | |
| ... """) | |
| >>> str(s).startswith('def') # automatic de-indentation! | |
| True | |
| >>> s.isparseable() | |
| True | |
| >>> sub = s.getstatement(1) # get the statement starting at line 1 | |
| >>> str(sub).strip() # XXX why is the strip() required?!? | |
| 'print "foo"' | |
| .. autoclass:: py.code.Source | |
| :members: | |
| ``py.code.Traceback`` | |
| ------------------------ | |
| Tracebacks are usually not very easy to examine, you need to access certain | |
| somewhat hidden attributes of the traceback's items (resulting in expressions | |
| such as 'fname = tb.tb_next.tb_frame.f_code.co_filename'). The Traceback | |
| interface (and its TracebackItem children) tries to improve this. | |
| Example:: | |
| >>> import sys | |
| >>> try: | |
| ... py.path.local(100) # illegal argument | |
| ... except: | |
| ... exc, e, tb = sys.exc_info() | |
| >>> t = py.code.Traceback(tb) | |
| >>> first = t[1] # get the second entry (first is in this doc) | |
| >>> first.path.basename # second is in py/path/local.py | |
| 'local.py' | |
| >>> isinstance(first.statement, py.code.Source) | |
| True | |
| >>> str(first.statement).strip().startswith('raise ValueError') | |
| True | |
| .. autoclass:: py.code.Traceback | |
| :members: | |
| ``py.code.Frame`` | |
| -------------------- | |
| Frame wrappers are used in ``py.code.Traceback`` items, and will usually not | |
| directly be instantiated. They provide some nice methods to evaluate code | |
| 'inside' the frame (using the frame's local variables), get to the underlying | |
| code (frames have a code attribute that points to a ``py.code.Code`` object) | |
| and examine the arguments. | |
| Example (using the 'first' TracebackItem instance created above):: | |
| >>> frame = first.frame | |
| >>> isinstance(frame.code, py.code.Code) | |
| True | |
| >>> isinstance(frame.eval('self'), py.path.local) | |
| True | |
| >>> [namevalue[0] for namevalue in frame.getargs()] | |
| ['cls', 'path'] | |
| .. autoclass:: py.code.Frame | |
| :members: | |
| ``py.code.ExceptionInfo`` | |
| ---------------------------- | |
| A wrapper around the tuple returned by sys.exc_info() (will call sys.exc_info() | |
| itself if the tuple is not provided as an argument), provides some handy | |
| attributes to easily access the traceback and exception string. | |
| Example:: | |
| >>> import sys | |
| >>> try: | |
| ... foobar() | |
| ... except: | |
| ... excinfo = py.code.ExceptionInfo() | |
| >>> excinfo.typename | |
| 'NameError' | |
| >>> isinstance(excinfo.traceback, py.code.Traceback) | |
| True | |
| >>> excinfo.exconly() | |
| "NameError: name 'foobar' is not defined" | |
| .. autoclass:: py.code.ExceptionInfo | |
| :members: | |
| .. autoclass:: py.code.Traceback | |
| :members: | |