Document new Py_ssize_t API.

diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
index fd02ecdbae2a7c608daa5d47d6812806f869cf08..5521b80ba9bf53dbd8e82ce77488b6e1f93fe810 100644 (file)
--- a/Doc/api/concrete.tex
+++ b/Doc/api/concrete.tex
@@ -162,9 +162,20 @@ There is no \cfunction{PyNone_Check()} function for the same reason.
   suspect the behaviour of Python in this case is undefined. :-)
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{PyObject*}{PyInt_FromSsize_t}{Py_ssize_t ival}
+  Create a new integer object with a value of \var{ival}.
+  If the value exceeds \code{LONG_MAX}, a long integer object is
+  returned.
+
+ \versionadded{2.5}
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
   Will first attempt to cast the object to a \ctype{PyIntObject}, if
-  it is not already one, and then return its value.
+  it is not already one, and then return its value. If there is an
+  error, \code{-1} is returned, and the caller should check
+  \code{PyErr_Occurred()} to find out whether there was an error, or
+  whether the value just happened to be -1.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
@@ -186,6 +197,13 @@ There is no \cfunction{PyNone_Check()} function for the same reason.
   \versionadded{2.3}
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{Py_ssize_t}{PyInt_AsSsize_t}{PyObject *io}
+  Will first attempt to cast the object to a \ctype{PyIntObject} or
+  \ctype{PyLongObject}, if it is not already one, and then return its
+  value as \ctype{Py_ssize_t}.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{long}{PyInt_GetMax}{}
   Return the system's idea of the largest integer it can handle
   (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system

diff --git a/Doc/api/utilities.tex b/Doc/api/utilities.tex
index 094cbf307ca2bf187bdc16de3338bffc358f717b..5aecbc39b237baf8deb5d57a26dbb3ac431c38a1 100644 (file)
--- a/Doc/api/utilities.tex
+++ b/Doc/api/utilities.tex
@@ -553,6 +553,10 @@ whose address should be passed.
   platforms that support \ctype{unsigned long long} (or
   \ctype{unsigned _int64} on Windows).  \versionadded{2.3}
 
+  \item[\samp{n} (integer) {[Py_ssize_t]}]
+  Convert a Python integer or long integer to a C \ctype{Py_ssize_t}.
+  \versionadded{2.5}
+
   \item[\samp{c} (string of length 1) {[char]}]
   Convert a Python character, represented as a string of length 1, to
   a C \ctype{char}.
@@ -866,6 +870,10 @@ PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
     Convert a C \ctype{unsigned long long} to a Python long integer object.
     Only available on platforms that support \ctype{unsigned long long}.
 
+    \item[\samp{n} (int) {[Py_ssize_t]}]
+    Convert a C \ctype{Py_ssize_t) to a Python integer or long integer.
+    \versionadded{2.5}
+
     \item[\samp{c} (string of length 1) {[char]}]
     Convert a C \ctype{int} representing a character to a Python
     string of length 1.