Add documentation for the public API for weak reference objects.
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 @@
\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 @@
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 @@
\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}