From 9b743f514c8e6781ebcb9ef444555b3a88633e6d Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Mon, 20 Feb 2006 12:57:53 +0000
Subject: [PATCH] Bug #1013800: document PyFunction_* functions

---
 Doc/api/concrete.tex  | 76 ++++++++++++++++++++++++++++++++++++++++++-
 Doc/api/refcounts.dat | 47 ++++++++++++++++++++------
 2 files changed, 112 insertions(+), 11 deletions(-)

diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
index 6079a93e2cb..583a54858cd 100644
--- a/Doc/api/concrete.tex
+++ b/Doc/api/concrete.tex
@@ -2222,6 +2222,80 @@ There are very few functions specific to instance objects.
 \end{cfuncdesc}
 
 
+\subsection{Function Objects \label{function-objects}}
+
+\obindex{function}
+There are a few functions specific to Python functions.
+
+\begin{ctypedesc}{PyFunctionObject}
+  The C structure used for functions.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyFunction_Type}
+  This is an instance of \ctype{PyTypeObject} and represents the
+  Python function type.  It is exposed to Python programmers as
+  \code{types.FunctionType}.
+  \withsubitem{(in module types)}{\ttindex{MethodType}}
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyFunction_Check}{PyObject *o}
+  Return true if \var{o} is a function object (has type
+  \cdata{PyFunction_Type}).  The parameter must not be \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_New}{PyObject *code,
+                                             PyObject *globals}
+  Return a new function object associated with the code object
+  \var{code}. \var{globals} must be a dictionary with the the global
+  varaibles accessible to the function.
+
+  The function's docstring, name and \var{__module__} are retrieved
+  from the code object, the argument defaults and closure are set to
+  \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetCode}{PyObject *op}
+  Return the code object associated with the function object \var{op}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetGlobals}{PyObject *op}
+  Return the globals dictionary associated with the function object
+  \var{op}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetModule}{PyObject *op}
+  Return the \var{__module__} attribute of the function object \var{op}.
+  This is normally a string containing the module name, but can be set
+  to any other object by Python code.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetDefaults}{PyObject *op}
+  Return the argument default values of the function object \var{op}.
+  This can be a tuple of arguments or \NULL{}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFunction_SetDefaults}{PyObject *op,
+                                               PyObject *defaults}
+  Set the argument default values for the function object \var{op}.
+  \var{defaults} must be \var{Py_None} or a tuple.
+
+  Raises \exception{SystemError} and returns \code{-1} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFunction_GetClosure}{PyObject *op}
+  Return the closure associated with the function object \var{op}.
+  This can be \NULL{} or a tuple of cell objects.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyFunction_SetClosure}{PyObject *op,
+                                              PyObject *closure}
+  Set the closure associated with the function object \var{op}.
+  \var{closure} must be \var{Py_None} or a tuple of cell objects.
+
+  Raises \exception{SystemError} and returns \code{-1} on failure.
+\end{cfuncdesc}
+
+
 \subsection{Method Objects \label{method-objects}}
 
 \obindex{method}
@@ -2655,7 +2729,7 @@ when accessed.  Cell objects are not likely to be useful elsewhere.
 \end{ctypedesc}
 
 \begin{cvardesc}{PyTypeObject}{PyCell_Type}
-  The type object corresponding to cell objects
+  The type object corresponding to cell objects.
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyCell_Check}{ob}
diff --git a/Doc/api/refcounts.dat b/Doc/api/refcounts.dat
index a8f3817e76f..f3bd32e7fc1 100644
--- a/Doc/api/refcounts.dat
+++ b/Doc/api/refcounts.dat
@@ -337,21 +337,48 @@ PyFloat_Check:PyObject*:p:0:
 PyFloat_FromDouble:PyObject*::+1:
 PyFloat_FromDouble:double:v::
 
+PyFunction_GetClosure:PyObject*::0:
+PyFunction_GetClosure:PyObject*:op:0:
+
+PyFunction_GetCode:PyObject*::0:
+PyFunction_GetCode:PyObject*:op:0:
+
+PyFunction_GetDefaults:PyObject*::0:
+PyFunction_GetDefaults:PyObject*:op:0:
+
+PyFunction_GetGlobals:PyObject*::0:
+PyFunction_GetGlobals:PyObject*:op:0:
+
+PyFunction_GetModule:PyObject*::0:
+PyFunction_GetModule:PyObject*:op:0:
+
+PyFunction_New:PyObject*::+1:
+PyFunction_New:PyObject*:code:+1:
+PyFunction_New:PyObject*:globals:+1:
+
+PyFunction_SetClosure:int:::
+PyFunction_SetClosure:PyObject*:op:0:
+PyFunction_SetClosure:PyObject*:closure:+1:
+
+PyFunction_SetDefaults:int:::
+PyFunction_SetDefaults:PyObject*:op:0:
+PyFunction_SetDefaults:PyObject*:defaults:+1:
+
 Py_InitModule:PyObject*::0:
-Py_InitModule:name:char*::
-Py_InitModule:methods:PyMethodDef[]::
+Py_InitModule:char*:name::
+Py_InitModule:PyMethodDef[]:methods::
 
 Py_InitModule3:PyObject*::0:
-Py_InitModule3:name:char*::
-Py_InitModule3:methods:PyMethodDef[]::
-Py_InitModule3:doc:char*::
+Py_InitModule3:char*:name::
+Py_InitModule3:PyMethodDef[]:methods::
+Py_InitModule3:char*:doc::
 
 Py_InitModule4:PyObject*::0:
-Py_InitModule4:name:char*::
-Py_InitModule4:methods:PyMethodDef[]::
-Py_InitModule4:doc:char*::
-Py_InitModule4:self:PyObject*::
-Py_InitModule4:apiver:int::usually provided by Py_InitModule or Py_InitModule3
+Py_InitModule4:char*:name::
+Py_InitModule4:PyMethodDef[]:methods::
+Py_InitModule4:char*:doc::
+Py_InitModule4:PyObject*:self::
+Py_InitModule4:int:apiver::usually provided by Py_InitModule or Py_InitModule3
 
 PyImport_AddModule:PyObject*::0:reference borrowed from sys.modules
 PyImport_AddModule:char*:name::