4 files changed, 61 insertions, 3 deletions
diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
new file mode 100644
index 0000000..c6ca8c5
--- /dev/null
+++ b/Doc/c-api/code.rst
@@ -0,0 +1,50 @@
+.. highlightlang:: c
+
+.. _codeobjects:
+
+Code Objects
+------------
+
+.. sectionauthor:: Jeffrey Yasskin <jyasskin@gmail.com>
+
+
+.. index::
+   object: code
+
+Code objects are a low-level detail of the CPython implementation.
+Each one represents a chunk of executable code that hasn't yet been
+bound into a function.
+
+.. ctype:: PyCodeObject
+
+   The C structure of the objects used to describe code objects.  The
+   fields of this type are subject to change at any time.
+
+
+.. cvar:: PyTypeObject PyCode_Type
+
+   This is an instance of :ctype:`PyTypeObject` representing the Python
+   :class:`code` type.
+
+
+.. cfunction:: int PyCode_Check(PyObject *co)
+
+   Return true if *co* is a :class:`code` object
+
+.. cfunction:: int PyCode_GetNumFree(PyObject *co)
+
+   Return the number of free variables in *co*.
+
+.. cfunction:: PyCodeObject *PyCode_New(int argcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
+
+   Return a new code object.  If you need a dummy code object to
+   create a frame, use :cfunc:`PyCode_NewEmpty` instead.  Calling
+   :cfunc:`PyCode_New` directly can bind you to a precise Python
+   version since the definition of the bytecode changes often.
+
+
+.. cfunction:: int PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
+
+   Return a new empty code object with the specified filename,
+   function name, and first line number.  It is illegal to
+   :keyword:`exec` or :func:`eval` the resulting code object.
diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst
index 4a4c142..8096054 100644
--- a/Doc/c-api/concrete.rst
+++ b/Doc/c-api/concrete.rst
@@ -105,3 +105,4 @@ Other Objects
    cell.rst
    gen.rst
    datetime.rst
+   code.rst
diff --git a/Doc/c-api/reflection.rst b/Doc/c-api/reflection.rst
index 822c593..3996c1f 100644
--- a/Doc/c-api/reflection.rst
+++ b/Doc/c-api/reflection.rst
@@ -29,6 +29,11 @@ Reflection
    currently executing.
 
 
+.. cfunction:: int PyFrame_GetLineNumber(PyFrameObject *frame)
+
+   Return the line number that *frame* is currently executing.
+
+
 .. cfunction:: int PyEval_GetRestricted()
 
    If there is a current frame and it is executing in restricted mode, return true,
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index ba22dc3..c4e3923 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -720,9 +720,11 @@ always available.
       specifies the local trace function.
 
    ``'line'``
-      The interpreter is about to execute a new line of code (sometimes multiple
-      line events on one line exist).  The local trace function is called; *arg*
-      is ``None``; the return value specifies the new local trace function.
+      The interpreter is about to execute a new line of code or re-execute the
+      condition of a loop.  The local trace function is called; *arg* is
+      ``None``; the return value specifies the new local trace function.  See
+      :file:`Objects/lnotab_notes.txt` for a detailed explanation of how this
+      works.
 
    ``'return'``
       A function (or other code block) is about to return.  The local trace