Add documentation for the public API for weak reference objects.

1 files changed, 70 insertions, 1 deletions

diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index 6549e86..2e2c63e 100644
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -1099,13 +1099,14 @@ completeness, here are all the variables:
   \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
   \lineiii{PyExc_OSError}{\exception{OSError}}{}
   \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
+  \lineiii{PyExc_ReferenceError}{\exception{ReferenceError}}{(2)}
   \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
   \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
   \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
   \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
   \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
   \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
-  \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(2)}
+  \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(3)}
   \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
 \end{tableiii}
 
@@ -1116,6 +1117,9 @@ Notes:
   This is a base class for other standard exceptions.
 
 \item[(2)]
+  This is the same as \exception{weakref.ReferenceError}.
+
+\item[(3)]
   Only defined on Windows; protect code that uses this by testing that
   the preprocessor macro \code{MS_WINDOWS} is defined.
 \end{description}
@@ -4502,6 +4506,71 @@ returned.
 \end{cfuncdesc}
 
 
+\subsection{Weak Reference Objects \label{weakref-objects}}
+
+Python supports \emph{weak references} as first-class objects.  There
+are two specific object types which directly implement weak
+references.  The first is a simple reference object, and the second
+acts as a proxy for the original object as much as it can.
+
+\begin{cfuncdesc}{int}{PyWeakref_Check}{ob}
+  Return true if \var{ob} is either a reference or proxy object.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob}
+  Return true if \var{ob} is a reference object.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob}
+  Return true if \var{ob} is a proxy object.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob,
+                                               PyObject *callback}
+  Return a weak reference object for the object \var{ob}.  This will
+  always return a new reference, but is not guaranteed to create a new
+  object; an existing reference object may be returned.  The second
+  parameter, \var{callback}, can be a callable object that receives
+  notification when \var{ob} is garbage collected; it should accept a
+  single paramter, which will be the weak reference object itself.
+  \var{callback} may also be \code{None} or \NULL.  If \var{ob}
+  is not a weakly-referencable object, or if \var{callback} is not
+  callable, \code{None}, or \NULL, this will return \NULL{} and
+  raise \exception{TypeError}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob,
+                                                 PyObject *callback}
+  Return a weak reference proxy object for the object \var{ob}.  This
+  will always return a new reference, but is not guaranteed to create
+  a new object; an existing proxy object may be returned.  The second
+  parameter, \var{callback}, can be a callable object that receives
+  notification when \var{ob} is garbage collected; it should accept a
+  single paramter, which will be the weak reference object itself.
+  \var{callback} may also be \code{None} or \NULL.  If \var{ob} is not
+  a weakly-referencable object, or if \var{callback} is not callable,
+  \code{None}, or \NULL, this will return \NULL{} and raise
+  \exception{TypeError}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref}
+  Returns the referenced object from a weak reference, \var{ref}.  If
+  the referent is no longer live, returns \NULL.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref}
+  Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a
+  macro that does no error checking.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+
 \subsection{CObjects \label{cObjects}}
 
 \obindex{CObject}