Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5b8a523

Browse files
gvanrossumgvanrossum
committed
A whole bunch of typos fixed by Andrew Kuchling.
Added a warning about the incompleteness to the front. Added a reminder about CObject to the back.
1 parent 24df684 commit 5b8a523

2 files changed

Lines changed: 66 additions & 44 deletions

File tree

‎Doc/api.tex‎

Lines changed: 33 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,11 @@
2424
the general principles of extension writing but does not document the
2525
API functions in detail.
2626

27+
\strong{Warning:} The current version of this document is incomplete.
28+
I hope that it is nevertheless useful. I will continue to work on it,
29+
and release new versions from time to time, independent from Python
30+
source code releases.
31+
2732
\end{abstract}
2833

2934
\pagebreak
@@ -179,7 +184,7 @@ \subsubsection{Reference Count Details}
179184
properly -- either by passing ownership on (usually to its caller) or
180185
by calling \code{Py_DECREF()} or \code{Py_XDECREF()}. When a function
181186
passes ownership of a reference on to its caller, the caller is said
182-
to receive a \emph{new} reference. When to ownership is transferred,
187+
to receive a \emph{new} reference. When no ownership is transferred,
183188
the caller is said to \emph{borrow} the reference. Nothing needs to
184189
be done for a borrowed reference.
185190

@@ -203,25 +208,26 @@ \subsubsection{Reference Count Details}
203208
PyTuple_SetItem(t, 2, PyString_FromString("three"));
204209
\end{verbatim}
205210

206-
Incidentally, \code{PyTuple_SetItem()} is the \emph{only} way to set
207-
tuple items; \code{PyObject_SetItem()} refuses to do this since tuples
208-
are an immutable data type. You should only use
209-
\code{PyTuple_SetItem()} for tuples that you are creating yourself.
211+
Incidentally, \code{PyTuple_SetItem()} is the \emph{only} way to set
212+
tuple items; \code{PySequence_SetItem()} and \code{PyObject_SetItem()}
213+
refuse to do this since tuples are an immutable data type. You should
214+
only use \code{PyTuple_SetItem()} for tuples that you are creating
215+
yourself.
210216

211217
Equivalent code for populating a list can be written using
212218
\code{PyList_New()} and \code{PyList_SetItem()}. Such code can also
213219
use \code{PySequence_SetItem()}; this illustrates the difference
214-
between the two:
220+
between the two (the extra \code{Py_DECREF()} calls):
215221

216222
\begin{verbatim}
217223
PyObject *l, *x;
218224
l = PyList_New(3);
219225
x = PyInt_FromLong(1L);
220-
PyObject_SetItem(l, 0, x); Py_DECREF(x);
226+
PySequence_SetItem(l, 0, x); Py_DECREF(x);
221227
x = PyInt_FromLong(2L);
222-
PyObject_SetItem(l, 1, x); Py_DECREF(x);
228+
PySequence_SetItem(l, 1, x); Py_DECREF(x);
223229
x = PyString_FromString("three");
224-
PyObject_SetItem(l, 2, x); Py_DECREF(x);
230+
PySequence_SetItem(l, 2, x); Py_DECREF(x);
225231
\end{verbatim}
226232

227233
You might find it strange that the ``recommended'' approach takes more
@@ -276,7 +282,7 @@ \subsubsection{Reference Count Details}
276282
by a function depends on which function you call only -- \emph{the
277283
plumage} (i.e., the type of the type of the object passed as an
278284
argument to the function) \emph{don't enter into it!} Thus, if you
279-
extract an item from a list using \code{PyList_GetItem()}, yo don't
285+
extract an item from a list using \code{PyList_GetItem()}, you don't
280286
own the reference -- but if you obtain the same item from the same
281287
list using \code{PySequence_GetItem()} (which happens to take exactly
282288
the same arguments), you do own a reference to the returned object.
@@ -318,7 +324,7 @@ \subsubsection{Reference Count Details}
318324
return -1; /* Not a sequence, or other failure */
319325
if (PyInt_Check(item))
320326
total += PyInt_AsLong(item);
321-
Py_DECREF(item); /* Discared reference ownership */
327+
Py_DECREF(item); /* Discard reference ownership */
322328
}
323329
return total;
324330
}
@@ -416,7 +422,7 @@ \section{Exceptions}
416422
{
417423
/* Objects all initialized to NULL for Py_XDECREF */
418424
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
419-
int rv = -1; /* Return value initialized to -1 (faulure) */
425+
int rv = -1; /* Return value initialized to -1 (failure) */
420426
421427
item = PyObject_GetItem(dict, key);
422428
if (item == NULL) {
@@ -460,7 +466,7 @@ \section{Exceptions}
460466
the variables used to hold owned references are initialized to
461467
\NULL{} for this to work; likewise, the proposed return value is
462468
initialized to \code{-1} (failure) and only set to success after
463-
the final call made is succesful.
469+
the final call made is successful.
464470

465471

466472
\section{Embedding Python}
@@ -611,7 +617,7 @@ \chapter{Exception Handling}
611617
functions also return an error indicator, usually \NULL{} if they are
612618
supposed to return a pointer, or -1 if they return an integer
613619
(exception: the \code{PyArg_Parse*()} functions return 1 for success and
614-
0 for failure). When a function must fail because of some function it
620+
0 for failure). When a function must fail because some function it
615621
called failed, it generally doesn't set the error indicator; the
616622
function it called already set it.
617623

@@ -935,13 +941,13 @@ \section{Importing modules}
935941
Finalize the import mechanism. For internal use only.
936942
\end{cfuncdesc}
937943
938-
\begin{cvardesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
944+
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
939945
For internal use only.
940-
\end{cvardesc}
946+
\end{cfuncdesc}
941947
942-
\begin{cvardesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
948+
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
943949
For internal use only.
944-
\end{cvardesc}
950+
\end{cfuncdesc}
945951
946952
\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
947953
Load a frozen module. Return \code{1} for success, \code{0} if the
@@ -1039,7 +1045,7 @@ \section{Object Protocol}
10391045
\end{cfuncdesc}
10401046
10411047
\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name}
1042-
Retrieve an attributed named attr_name from object o.
1048+
Retrieve an attribute named attr_name from object o.
10431049
Returns the attribute value on success, or \NULL{} on failure.
10441050
This is the equivalent of the Python expression: \code{o.attr_name}.
10451051
\end{cfuncdesc}
@@ -1054,7 +1060,7 @@ \section{Object Protocol}
10541060
10551061
10561062
\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name}
1057-
Retrieve an attributed named attr_name form object o.
1063+
Retrieve an attribute named attr_name from object o.
10581064
Returns the attribute value on success, or \NULL{} on failure.
10591065
This is the equivalent of the Python expression: o.attr_name.
10601066
\end{cfuncdesc}
@@ -1374,7 +1380,7 @@ \section{Sequence protocol}
13741380
13751381
13761382
\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
1377-
Return the concatination of \code{o1} and \code{o2} on success, and \NULL{} on
1383+
Return the concatenation of \code{o1} and \code{o2} on success, and \NULL{} on
13781384
failure. This is the equivalent of the Python
13791385
expression: \code{o1+o2}.
13801386
\end{cfuncdesc}
@@ -2213,7 +2219,7 @@ \section{Thread State and the Global Interpreter Lock}
22132219
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{}
22142220
Return the current thread state. The interpreter lock must be held.
22152221
When the current thread state is \NULL{}, this issues a fatal
2216-
error (so that the caller needn't check for \NULL{}.
2222+
error (so that the caller needn't check for \NULL{}).
22172223
\end{cfuncdesc}
22182224
22192225
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate}
@@ -2822,6 +2828,11 @@ \subsection{File Objects}
28222828
\end{cfuncdesc}
28232829
28242830
2831+
\subsection{CObjects}
2832+
2833+
XXX
2834+
2835+
28252836
\input{api.ind} % Index -- must be last
28262837
28272838
\end{document}

‎Doc/api/api.tex‎

Lines changed: 33 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,11 @@
2424
the general principles of extension writing but does not document the
2525
API functions in detail.
2626

27+
\strong{Warning:} The current version of this document is incomplete.
28+
I hope that it is nevertheless useful. I will continue to work on it,
29+
and release new versions from time to time, independent from Python
30+
source code releases.
31+
2732
\end{abstract}
2833

2934
\pagebreak
@@ -179,7 +184,7 @@ \subsubsection{Reference Count Details}
179184
properly -- either by passing ownership on (usually to its caller) or
180185
by calling \code{Py_DECREF()} or \code{Py_XDECREF()}. When a function
181186
passes ownership of a reference on to its caller, the caller is said
182-
to receive a \emph{new} reference. When to ownership is transferred,
187+
to receive a \emph{new} reference. When no ownership is transferred,
183188
the caller is said to \emph{borrow} the reference. Nothing needs to
184189
be done for a borrowed reference.
185190

@@ -203,25 +208,26 @@ \subsubsection{Reference Count Details}
203208
PyTuple_SetItem(t, 2, PyString_FromString("three"));
204209
\end{verbatim}
205210

206-
Incidentally, \code{PyTuple_SetItem()} is the \emph{only} way to set
207-
tuple items; \code{PyObject_SetItem()} refuses to do this since tuples
208-
are an immutable data type. You should only use
209-
\code{PyTuple_SetItem()} for tuples that you are creating yourself.
211+
Incidentally, \code{PyTuple_SetItem()} is the \emph{only} way to set
212+
tuple items; \code{PySequence_SetItem()} and \code{PyObject_SetItem()}
213+
refuse to do this since tuples are an immutable data type. You should
214+
only use \code{PyTuple_SetItem()} for tuples that you are creating
215+
yourself.
210216

211217
Equivalent code for populating a list can be written using
212218
\code{PyList_New()} and \code{PyList_SetItem()}. Such code can also
213219
use \code{PySequence_SetItem()}; this illustrates the difference
214-
between the two:
220+
between the two (the extra \code{Py_DECREF()} calls):
215221

216222
\begin{verbatim}
217223
PyObject *l, *x;
218224
l = PyList_New(3);
219225
x = PyInt_FromLong(1L);
220-
PyObject_SetItem(l, 0, x); Py_DECREF(x);
226+
PySequence_SetItem(l, 0, x); Py_DECREF(x);
221227
x = PyInt_FromLong(2L);
222-
PyObject_SetItem(l, 1, x); Py_DECREF(x);
228+
PySequence_SetItem(l, 1, x); Py_DECREF(x);
223229
x = PyString_FromString("three");
224-
PyObject_SetItem(l, 2, x); Py_DECREF(x);
230+
PySequence_SetItem(l, 2, x); Py_DECREF(x);
225231
\end{verbatim}
226232

227233
You might find it strange that the ``recommended'' approach takes more
@@ -276,7 +282,7 @@ \subsubsection{Reference Count Details}
276282
by a function depends on which function you call only -- \emph{the
277283
plumage} (i.e., the type of the type of the object passed as an
278284
argument to the function) \emph{don't enter into it!} Thus, if you
279-
extract an item from a list using \code{PyList_GetItem()}, yo don't
285+
extract an item from a list using \code{PyList_GetItem()}, you don't
280286
own the reference -- but if you obtain the same item from the same
281287
list using \code{PySequence_GetItem()} (which happens to take exactly
282288
the same arguments), you do own a reference to the returned object.
@@ -318,7 +324,7 @@ \subsubsection{Reference Count Details}
318324
return -1; /* Not a sequence, or other failure */
319325
if (PyInt_Check(item))
320326
total += PyInt_AsLong(item);
321-
Py_DECREF(item); /* Discared reference ownership */
327+
Py_DECREF(item); /* Discard reference ownership */
322328
}
323329
return total;
324330
}
@@ -416,7 +422,7 @@ \section{Exceptions}
416422
{
417423
/* Objects all initialized to NULL for Py_XDECREF */
418424
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
419-
int rv = -1; /* Return value initialized to -1 (faulure) */
425+
int rv = -1; /* Return value initialized to -1 (failure) */
420426
421427
item = PyObject_GetItem(dict, key);
422428
if (item == NULL) {
@@ -460,7 +466,7 @@ \section{Exceptions}
460466
the variables used to hold owned references are initialized to
461467
\NULL{} for this to work; likewise, the proposed return value is
462468
initialized to \code{-1} (failure) and only set to success after
463-
the final call made is succesful.
469+
the final call made is successful.
464470

465471

466472
\section{Embedding Python}
@@ -611,7 +617,7 @@ \chapter{Exception Handling}
611617
functions also return an error indicator, usually \NULL{} if they are
612618
supposed to return a pointer, or -1 if they return an integer
613619
(exception: the \code{PyArg_Parse*()} functions return 1 for success and
614-
0 for failure). When a function must fail because of some function it
620+
0 for failure). When a function must fail because some function it
615621
called failed, it generally doesn't set the error indicator; the
616622
function it called already set it.
617623

@@ -935,13 +941,13 @@ \section{Importing modules}
935941
Finalize the import mechanism. For internal use only.
936942
\end{cfuncdesc}
937943
938-
\begin{cvardesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
944+
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
939945
For internal use only.
940-
\end{cvardesc}
946+
\end{cfuncdesc}
941947
942-
\begin{cvardesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
948+
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
943949
For internal use only.
944-
\end{cvardesc}
950+
\end{cfuncdesc}
945951
946952
\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
947953
Load a frozen module. Return \code{1} for success, \code{0} if the
@@ -1039,7 +1045,7 @@ \section{Object Protocol}
10391045
\end{cfuncdesc}
10401046
10411047
\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name}
1042-
Retrieve an attributed named attr_name from object o.
1048+
Retrieve an attribute named attr_name from object o.
10431049
Returns the attribute value on success, or \NULL{} on failure.
10441050
This is the equivalent of the Python expression: \code{o.attr_name}.
10451051
\end{cfuncdesc}
@@ -1054,7 +1060,7 @@ \section{Object Protocol}
10541060
10551061
10561062
\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name}
1057-
Retrieve an attributed named attr_name form object o.
1063+
Retrieve an attribute named attr_name from object o.
10581064
Returns the attribute value on success, or \NULL{} on failure.
10591065
This is the equivalent of the Python expression: o.attr_name.
10601066
\end{cfuncdesc}
@@ -1374,7 +1380,7 @@ \section{Sequence protocol}
13741380
13751381
13761382
\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
1377-
Return the concatination of \code{o1} and \code{o2} on success, and \NULL{} on
1383+
Return the concatenation of \code{o1} and \code{o2} on success, and \NULL{} on
13781384
failure. This is the equivalent of the Python
13791385
expression: \code{o1+o2}.
13801386
\end{cfuncdesc}
@@ -2213,7 +2219,7 @@ \section{Thread State and the Global Interpreter Lock}
22132219
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{}
22142220
Return the current thread state. The interpreter lock must be held.
22152221
When the current thread state is \NULL{}, this issues a fatal
2216-
error (so that the caller needn't check for \NULL{}.
2222+
error (so that the caller needn't check for \NULL{}).
22172223
\end{cfuncdesc}
22182224
22192225
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate}
@@ -2822,6 +2828,11 @@ \subsection{File Objects}
28222828
\end{cfuncdesc}
28232829
28242830
2831+
\subsection{CObjects}
2832+
2833+
XXX
2834+
2835+
28252836
\input{api.ind} % Index -- must be last
28262837
28272838
\end{document}

0 commit comments

Comments
 (0)