Update web-platform-tests to revision d011702f368b88b3bae86e7a8fd2ddd22e18b33c

tests/wpt/web-platform-tests/tools/py/doc/code.txt

@@ -0,0 +1,150 @@
+================================================================================
+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:
+