Commit Graph

433 Commits

Author SHA1 Message Date
Michael W. Hudson 5efaf7eac8 This is my nearly two year old patch
[ 400998 ] experimental support for extended slicing on lists

somewhat spruced up and better tested than it was when I wrote it.

Includes docs & tests.  The whatsnew section needs expanding, and arrays
should support extended slices -- later.
2002-06-11 10:55:12 +00:00
Guido van Rossum 9788384d02 Explain that tp_basicsize must provide alignment for the items. 2002-05-31 21:00:18 +00:00
Fred Drake ffb294bd34 Add refcount information for PySequence_ITEM(). 2002-05-23 16:03:16 +00:00
Fred Drake 86228e4ca2 Add version annotation for PySequence_ITEM(). 2002-05-23 16:02:28 +00:00
Martin v. Löwis 01f94bda38 Patch #552433: Special-case tuples. Avoid sub-type checking for lists.
Avoid checks for negative indices and duplicate checks for support of
the sequence protocol.
2002-05-08 08:44:21 +00:00
Thomas Heller 541703b18f Typo: whcar_t should be wchar_t.
Bugfix candidate? Don't know how this is handled in the docs.
2002-04-29 17:28:43 +00:00
Fred Drake 432425e834 Small markup adjustments for consistency. 2002-04-29 15:17:16 +00:00
Tim Peters 5de9842b34 Repair widespread misuse of _PyString_Resize. Since it's clear people
don't understand how this function works, also beefed up the docs.  The
most common usage error is of this form (often spread out across gotos):

	if (_PyString_Resize(&s, n) < 0) {
		Py_DECREF(s);
		s = NULL;
		goto outtahere;
	}

The error is that if _PyString_Resize runs out of memory, it automatically
decrefs the input string object s (which also deallocates it, since its
refcount must be 1 upon entry), and sets s to NULL.  So if the "if"
branch ever triggers, it's an error to call Py_DECREF(s):  s is already
NULL!  A correct way to write the above is the simpler (and intended)

	if (_PyString_Resize(&s, n) < 0)
		goto outtahere;

Bugfix candidate.
2002-04-27 18:44:32 +00:00
Thomas Heller 8da4b59221 Fix a small mistake and complete some function prototypes.
SF Patch #547813.
2002-04-24 06:35:11 +00:00
Fred Drake b957bc3dcc Clarify the return value of PyObject_IsInstance(). 2002-04-23 18:15:44 +00:00
Fred Drake 8d95ca4469 Add text on tp_as_buffer that refers tothe section that covers the topic.
Additional material is still needed in that section.
2002-04-17 13:44:58 +00:00
Fred Drake 121460d8cb Minor wording change. 2002-04-16 18:32:37 +00:00
Fred Drake 9ad70f9cb0 Add more text from Guido on the type structure fields.
Small additional changes.
2002-04-16 16:22:24 +00:00
Fred Drake 0e0b6180ba Add documentation for PyObject_Call().
Note that PyObject_Size() is a synonym for PyObject_Length().
This closes SF patch #544330 (contributed by Thomas Heller).
2002-04-15 20:51:19 +00:00
Fred Drake 188ecd141a Integrated more text from Guido. 2002-04-15 18:44:46 +00:00
Fred Drake 4d2a95dfe7 Integrate a bunch of new text from Guido. 2002-04-12 22:47:18 +00:00
Fred Drake f495ef7466 Warn people away from PyModule_GetDict(), but not too strongly.
(The real issue is whether modules can benefit from an alternate
implementation strategy rather than using a dictionary.  We should migrate
away from direct dictionary manipulation to allow more room for Jeremy to
flex the implementation with changes in globals lookup.)
2002-04-12 19:32:07 +00:00
Fred Drake 28de8d4b37 Add a (very) simple description of PyType_Ready(). 2002-04-12 16:15:10 +00:00
Fred Drake e3c764b6c2 Document PyType_CheckExact(), PyType_IS_GC().
Update description of PyType_Check().
2002-04-10 17:52:52 +00:00
Fred Drake 4d61775a35 Started filling in the information about some of the basic types and macros
used to define Python objects.
2002-04-09 21:22:07 +00:00
Fred Drake 375e30225e Update to use the new \csimplemacro macro 2002-04-09 21:09:42 +00:00
Tim Peters 87bbdd3085 Minor clarification about what's actually promised for PyMem_Malloc(0).
I probably didn't do a correct thing for the LaTeX spelling of the
integer 1.
2002-04-06 09:14:33 +00:00
Fred Drake 68304ccce3 Move reference material on PyArg_Parse*() out of the Extending & Embedding
document to the C API reference.  Move some instructional text from the API
reference to the Extending & Embedding manual.

Fix the descriptions of the es and es# formats for PyArg_Parse*().
This closes SF bug #536516.
2002-04-05 23:01:14 +00:00
Fred Drake 243ea71669 Correct the descriptions of the PyObject_As*Buffer() return values.
This closes SF bug #539081.
2002-04-04 04:10:36 +00:00
Fred Drake 7bf9715a8b Introduce two new flag bits that can be set in a PyMethodDef method
descriptor, as used for the tp_methods slot of a type.  These new flag
bits are both optional, and mutually exclusive.  Most methods will not
use either.  These flags are used to create special method types which
exist in the same namespace as normal methods without having to use
tedious construction code to insert the new special method objects in
the type's tp_dict after PyType_Ready() has been called.

If METH_CLASS is specified, the method will represent a class method
like that returned by the classmethod() built-in.

If METH_STATIC is specified, the method will represent a static method
like that returned by the staticmethod() built-in.

These flags may not be used in the PyMethodDef table for modules since
these special method types are not meaningful in that case; a
ValueError will be raised if these flags are found in that context.
2002-03-28 05:33:33 +00:00
Skip Montanaro 9e38c100ab fix a typo in PyErr_Format table and add row for 'p' format char
closes bug 534495
2002-03-27 13:42:50 +00:00
Neil Schemenauer 194152845c Fix example for PyErr_SetFromErrno() (need to pass exception type). 2002-03-23 20:57:11 +00:00
Fred Drake 6ccdccd35d Add a note that Py_None needs the same reference count treatment as any
other PyObject *.
This closes SF bug #494007.
2002-03-12 20:12:54 +00:00
Fred Drake 314bae50b9 Documentation for PyObject_GetIter(), contributed by Greg Chapman
(with only minor changes by Fred).
This closes SF bug #498607.
2002-03-11 18:46:29 +00:00
Fred Drake 8371e840d2 Correct the refcount information for the PyWeakref_GetObject() function.
This closes SF bug #520087.
2002-02-20 05:07:36 +00:00
Skip Montanaro ea3ceaa913 PyDict_Next: update doc to indicate that pkey and pvalue return values are
borrowed references.
2002-01-23 10:54:41 +00:00
Skip Montanaro a23bc42ad5 add missing return value info for PyDict_DelItem 2002-01-23 08:18:30 +00:00
Fred Drake 8b8fe288b3 Close an improperly-closed verbatim environment.
This closes SF patch #496215.

Add a little more detail to the example that had not been closed.

Bugfix: this should be made part of 2.2.1.
2001-12-26 16:53:48 +00:00
Fred Drake 54e6294197 A number of small adjustments. 2001-12-11 19:40:16 +00:00
Tim Peters f582b82fe9 SF bug #491415 PyDict_UpdateFromSeq2() unused
PyDict_UpdateFromSeq2():  removed it.
PyDict_MergeFromSeq2():  made it public and documented it.
PyDict_Merge() docs:  updated to reveal <wink> that the second
argument can be any mapping object.
2001-12-11 18:51:08 +00:00
Fred Drake 32a3587345 Document that PyString_FromString() cannot take NULL as a parameter.
This closes SF bug #489872.
2001-12-06 20:38:15 +00:00
Fred Drake 551ffae30c Clarify that the Python runtime may behave mysteriously when an exception
is not handled properly.
This closes SF bug #485153.
2001-12-03 17:56:09 +00:00
Fred Drake 3570551d6f Remove most references to __members__ and __methods__, leaving only one pair
of references that now state that these attributes have been removed,
directing the reader to the dir() function.
This closes SF bug #456420.
2001-12-03 17:32:27 +00:00
Fred Drake f07125ee53 PyErr_Format() does not return a new reference; it always returns NULL.
This closes SF bug #488387.
2001-12-03 16:36:43 +00:00
Fred Drake 454af89712 Update the signature of PyFile_WriteString(). 2001-11-29 22:42:59 +00:00
Fred Drake c37b65ee10 Clean up some markup cruft. A number of the macros that take no
parameters (like \UNIX) are commonly entered using an empty group to
separate the markup from a following inter-word space; this is not
needed when the next character is punctuation, or the markup is the
last thing in the enclosing group.  These cases were marked
inconsistently; the empty group is now *only* used when needed.
2001-11-28 07:26:15 +00:00
Fred Drake cd8474e6a2 Add documentation for the PyCell* APIs. 2001-11-26 21:29:17 +00:00
Fred Drake 50ecc15d05 Add omitted word for clarity. 2001-11-17 06:39:18 +00:00
Thomas Heller bfeeeee851 Fix obvious typos. 2001-11-12 07:46:31 +00:00
Fred Drake 94ead57dc3 Added version annotations, remove hard tabs. 2001-11-09 23:34:26 +00:00
Jeremy Hylton 89c3a22a27 Add PyObject_CheckReadBuffer(), which returns true if its argument
supports the single-segment readable buffer interface.

Add documentation for this and other PyObject_XXXBuffer() calls.
2001-11-09 21:59:42 +00:00
Fred Drake 1b58bff8a0 More refcount information. 2001-10-29 17:43:14 +00:00
Fred Drake b0c079e3e5 PyObject_CallFunctionObArgs() ---> PyObject_CallFunctionObjArgs()
PyObject_CallMethodObArgs() ---> PyObject_CallMethodObjArgs()
2001-10-28 02:39:03 +00:00
Fred Drake c44e9eca66 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs().
Minor cleanups & markup consistency fixes.
2001-10-26 16:38:38 +00:00
Fred Drake 81c7aa2c7b Added refcount data for PyObject_CallFunctionObArgs() and
PyObject_CallMethodObArgs().
2001-10-26 16:29:22 +00:00
Tim Peters 1fc240e851 Generalize dictionary() to accept a sequence of 2-sequences. At the
outer level, the iterator protocol is used for memory-efficiency (the
outer sequence may be very large if fully materialized); at the inner
level, PySequence_Fast() is used for time-efficiency (these should
always be sequences of length 2).

dictobject.c, new functions PyDict_{Merge,Update}FromSeq2.  These are
wholly analogous to PyDict_{Merge,Update}, but process a sequence-of-2-
sequences argument instead of a mapping object.  For now, I left these
functions file static, so no corresponding doc changes.  It's tempting
to change dict.update() to allow a sequence-of-2-seqs argument too.

Also changed the name of dictionary's keyword argument from "mapping"
to "x".  Got a better name?  "mapping_or_sequence_of_pairs" isn't
attractive, although more so than "mosop" <wink>.

abstract.h, abstract.tex:  Added new PySequence_Fast_GET_SIZE function,
much faster than going thru the all-purpose PySequence_Size.

libfuncs.tex:
- Document dictionary().
- Fiddle tuple() and list() to admit that their argument is optional.
- The long-winded repetitions of "a sequence, a container that supports
  iteration, or an iterator object" is getting to be a PITA.  Many
  months ago I suggested factoring this out into "iterable object",
  where the definition of that could include being explicit about
  generators too (as is, I'm not sure a reader outside of PythonLabs
  could guess that "an iterator object" includes a generator call).
- Please check my curly braces -- I'm going blind <0.9 wink>.

abstract.c, PySequence_Tuple():  When PyObject_GetIter() fails, leave
its error msg alone now (the msg it produces has improved since
PySequence_Tuple was generalized to accept iterable objects, and
PySequence_Tuple was also stomping on the msg in cases it shouldn't
have even before PyObject_GetIter grew a better msg).
2001-10-26 05:06:50 +00:00
Fred Drake 847c51a181 Slightly better conformance to the Python C style guide. 2001-10-25 15:53:44 +00:00
Fred Drake c84f2c5068 Documentation for the new PyArg_UnpackTuple() function. 2001-10-23 21:10:18 +00:00
Fred Drake 5bf1ecd503 Update the description of PyTrace_EXCEPT. 2001-10-16 19:23:55 +00:00
Fred Drake 0fae49fc7b Added documentation for the functions listed in marshal.h.
Prompted by Jim Ahlstrom.  This closes SF patch #470614.
2001-10-14 04:45:51 +00:00
Fred Drake 3adf79e3e2 Break the Python/C API manual into smaller files by chapter. This manual
has grown beyond what font-lock will work with using the default (X)Emacs
settings.

Indentation of the description has been made consistent, and a number of
smaller markup adjustments have been made as well.
2001-10-12 19:01:43 +00:00
Fred Drake bf88b68f38 Add documentation for the public API for weak reference objects. 2001-10-05 22:03:58 +00:00
Fred Drake 6f3d82693a Expand the documentation of the low-level tracing/profiling interface.
This reflects what is currently in CVS, which may change before 2.2 is final.
2001-10-03 21:52:51 +00:00
Greg Ward e22871e9ed Typo fix. 2001-09-26 18:12:49 +00:00
Fred Drake f244b2e47c Add more signature information and some descriptions for the new APIs
introduced in Python 2.2.
Add documentation for the slice object interface (not complete).
Added version annotations for several of the Python 2.2 APIs already
documented.
2001-09-24 15:31:50 +00:00
Fred Drake 23a78cf1c1 Add more reference count information. 2001-09-24 15:29:47 +00:00
Fred Drake d61d0d3f6d Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Added signatures for some new PyType_*() functions.
2001-09-23 02:05:26 +00:00
Fred Drake f47d8ef683 Document all the Py*_CheckExact() functions.
Document many more of the PyLong_{As,From}*() functions.
2001-09-20 19:18:52 +00:00
Fred Drake 9c75ff785a Fix parameter for PyInt_Check().
Add refcount information for other recently documented APIs.
2001-09-06 18:06:46 +00:00
Fred Drake f8d7a5d391 Document the PyMethod_* type object, functions, and macros. 2001-09-06 17:12:44 +00:00
Fred Drake 396ca574dd Document the rule that Python.h must be included before any standard
headers.  This is the final checkin for SF bug #458768.
2001-09-06 16:30:30 +00:00
Martin v. Löwis 7c82a3e0fc Patch #449815: Set filesystemencoding based on CODESET. 2001-09-05 17:09:48 +00:00
Tim Peters 7eea37e831 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
__builtin__.dir().  Moved the guts from bltinmodule.c to object.c.
2001-09-04 22:08:56 +00:00
Neil Schemenauer 55cdc88c09 Update documentation for GC API. Closes SF patch #421893. 2001-08-30 15:24:17 +00:00
Barry Warsaw 8c64a54f75 Refcount info for PyString_FromFormat() and PyString_FromFormatV().
Closes SF patch #455666.
2001-08-28 02:32:04 +00:00
Barry Warsaw c86aa57f58 Documentation for PyString_FromFormat() and PyString_FromFormatV().
Closes SF patch #455666.
2001-08-28 02:31:28 +00:00
Fred Drake 0e40c3d012 Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
description.

This fixes SF bug #453111.
2001-08-20 16:48:59 +00:00
Martin v. Löwis e3eb1f2b23 Patch #427190: Implement and use METH_NOARGS and METH_O. 2001-08-16 13:15:00 +00:00
Fred Drake 680cabb225 Add "exceptions" to the list of fundamental modules
created by Py_Initialize().

This closes SF bug #450621.
2001-08-14 15:32:16 +00:00
Fred Drake 11ee90289c Added documentation for PyDict_Update() and PyDict_Merge(). 2001-08-10 21:31:12 +00:00
Fred Drake 024ef6f493 Remove the bogus flags parameter from the PyFile_WriteString() signature;
it has no such parameter.

This closes SF bug #449761.
2001-08-10 14:27:38 +00:00
Fred Drake 0197858f62 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
PyInterpreterState_*Head(), PyInterpreterState_Next(), and
PyThreadState_Next().

Wrapped some long lines, added some others.
2001-08-08 19:14:53 +00:00
Fred Drake 03590c6bdc Reference counting information for PyNumber_*FloorDivide() and
PyNumber_*TrueDivide().
2001-08-08 18:50:18 +00:00
Fred Drake f90490ef94 Move away from apply() to using extended call syntax for some example
fragments when discussing equivalence of thhe C API to what a Python
programmer sees.

Added descriptions of PyEval_SetProfile() and PyEval_SetTrace().
2001-08-02 18:00:28 +00:00
Fred Drake 88fdaa7c9e Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Moved the PyArg_Parse*(), Py_BuildValue() functions to the Utilities
chapter, added a minimal description and reference to the Extending
manual for Py_BuildValue().
2001-07-20 20:56:11 +00:00
Fred Drake 6d988559a3 Added information on Py_BuildValue(). 2001-07-20 20:55:31 +00:00
Fred Drake 68db730324 Adding what's done of the documentation for the new profiling &
tracing interface.  Incomplete, but better to check it in since I've
been including it in my updates.
2001-07-17 19:48:30 +00:00
Fred Drake 755c23dcc4 Oops, one more caret. 2001-07-14 03:05:53 +00:00
Fred Drake 377fb1e1f6 Fix the markup of the caret charater in a couple of places; LaTeX's
special character bite us again.  ;-(

This fixes SF bug #440911.
2001-07-14 03:01:48 +00:00
Fred Drake fa774872b8 Move the section on concrete numeric objects before the section on
concrete sequence objects, since their API is simpler.

This is in response to a comment in SF bug #440037.
2001-07-11 20:35:37 +00:00
Fred Drake d854831ddd Corrected the refcount information for PyList_SET_ITEM(). 2001-07-10 16:19:13 +00:00
Fred Drake bab2965c7c Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
PyObject_InitVar(), PyObject_Del(), PyObject_NEW(),
PyObject_NEW_VAR(), and PyObject_DEL().

Add notes to PyMem_Malloc() and PyMem_New() about the memory buffers
not being initialized.

This fixes SF bug #439012.


Added explicit return value information for PyList_SetItem(),
PyDict_SetItem(), and PyDict_SetItemString().  Corrected return type
for PyList_SET_ITEM().

Fixed index entries in the descriptions of PyLong_AsLong() and
PyLong_AsUnignedLong().

This fixes the API manual portion of SF bug #440037.


Note that the headers properly declare everything as 'extern "C"' for
C++ users.

Document _Py_NoneStruct.

Added links to the Extending & Embedding manual for PyArg_ParseTuple()
and PyArg_ParseTupleAndKeywords().

Added note that PyArg_Parse() should not be used in new code.

Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
translation more difficult, as well as reading the English more
difficult for non-native speakers.
2001-07-10 16:10:08 +00:00
Thomas Wouters e30ac57038 Fix for SF bug #436525, reported by Greg Kochanski:
The block/unblock thread macros are called 'Py_BLOCK_THREADS' and
'Py_UNBLOCK_THREADS', not 'Py_BEGIN_BLOCK_THREADS' and
'Py_BEGIN_UNBLOCK_THREADS'.
2001-07-09 14:35:01 +00:00
Fred Drake 8e0c09da62 More reference count information. 2001-07-06 23:31:49 +00:00
Fred Drake 490d34dbad Move license information to a less annoying location in the document.
Add documentation for PyErr_SetFromErrnoWithFilename().
2001-06-20 21:39:12 +00:00
Fred Drake 00d0cb6ec3 Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
In particular, the affect on existing list content was not sufficiently
explained.

This closes SF bug #429554.
2001-06-03 03:12:57 +00:00
Fred Drake 96a2a80065 Users of PySequence_GET_FAST() should get the length of the sequence using
PySequence_Size(), not PyObject_Size(): the later considers the mapping
methods as well as the sequence methods, which is not needed here.  Either
should be equally fast in this case, but PySequence_Size() offers a better
conceptual match.
2001-05-29 18:51:41 +00:00
Fred Drake b2625eb10e Removed information on the old third parameter to _PyTuple_Resize().
Added information on PyIter_Check(), PyIter_Next(),
PyObject_Unicode(), PyString_AsDecodedObject(),
PyString_AsEncodedObject(), and PyThreadState_GetDict().
2001-05-29 15:34:06 +00:00
Fred Drake fac312ff88 Do not start API descriptions with "Does the same, but ..." -- actually
state *which* other function the current one is like, even if the
descriptions are adjacent.

Revise the _PyTuple_Resize() description to reflect the removal of the
third parameter.
2001-05-29 15:13:00 +00:00
Fred Drake 24e621918b Add documentation for Py_Main() and PyThreadState_GetDict(). 2001-05-21 15:56:55 +00:00
Fred Drake fc43d00c17 Typo: "that" --> "than"
This closes SF bug #425320.
2001-05-21 15:03:35 +00:00
Marc-André Lemburg 2d9204199f This patch changes the way the string .encode() method works slightly
and introduces a new method .decode().

The major change is that strg.encode() will no longer try to convert
Unicode returns from the codec into a string, but instead pass along
the Unicode object as-is. The same is now true for all other codec
return types. The underlying C APIs were changed accordingly.

Note that even though this does have the potential of breaking
existing code, the chances are low since conversion from Unicode
previously took place using the default encoding which is normally
set to ASCII rendering this auto-conversion mechanism useless for
most Unicode encodings.

The good news is that you can now use .encode() and .decode() with
much greater ease and that the door was opened for better accessibility
of the builtin codecs.

As demonstration of the new feature, the patch includes a few new
codecs which allow string to string encoding and decoding (rot13,
hex, zip, uu, base64).

Written by Marc-Andre Lemburg. Copyright assigned to the PSF.
2001-05-15 12:00:02 +00:00
Fred Drake a8e0827614 Hmm... better add a version annotation for the Iterator Protocol section. 2001-05-07 17:47:07 +00:00
Fred Drake dbcaeda79a Added documentation for PyIter_Check() and PyIter_Next().
Wrapped a long line.
2001-05-07 17:42:18 +00:00
Marc-André Lemburg 8155e0e541 This patch originated from an idea by Martin v. Loewis who submitted a
patch for sharing single character Unicode objects.

Martin's patch had to be reworked in a number of ways to take Unicode
resizing into consideration as well. Here's what the updated patch
implements:

* Single character Unicode strings in the Latin-1 range are shared
  (not only ASCII chars as in Martin's original patch).

* The ASCII and Latin-1 codecs make use of this optimization,
  providing a noticable speedup for single character strings. Most
  Unicode methods can use the optimization as well (by virtue
  of using PyUnicode_FromUnicode()).

* Some code cleanup was done (replacing memcpy with Py_UNICODE_COPY)

* The PyUnicode_Resize() can now also handle the case of resizing
  unicode_empty which previously resulted in an error.

* Modified the internal API _PyUnicode_Resize() and
  the public PyUnicode_Resize() API to handle references to
  shared objects correctly. The _PyUnicode_Resize() signature
  changed due to this.

* Callers of PyUnicode_FromUnicode() may now only modify the Unicode
  object contents of the returned object in case they called the API
  with NULL as content template.

Note that even though this patch passes the regression tests, there
may still be subtle bugs in the sharing code.
2001-04-23 14:44:21 +00:00
Fred Drake 8d00a0ffc3 Michael Hudson:
Update docs for PyDict_Next() based on the most recent changes to the
dictionary code.

This closes SF patch #409864.
2001-04-13 17:55:02 +00:00
Fred Drake d20d8b319c Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping. 2001-04-13 14:52:39 +00:00
Greg Stein 4d4d0034c0 Correct the documentation for getreadbufferproc and getwritebufferproc.
Fixes bug #233308 from Travis Oliphant.
2001-04-07 16:14:49 +00:00
Fred Drake c6a3cb4baf Document PySequence_Size(), and describe PySequence_Length() as simply an
alternate name for the same function.
2001-04-04 01:25:17 +00:00
Fred Drake 58c8f9f631 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). 2001-03-28 21:14:32 +00:00
Fred Drake 8f6df46d40 Strengthen the constraints on calling PyObject_GC_Fini(). 2001-03-23 17:42:09 +00:00
Fred Drake e28d8aef2d Be more clear about the specific rules for supporting the cyclic GC in an
extension object.  Also included an example showing exactly what needs to
be done and nothing else.

This closes SF bug #228591.
2001-03-22 16:30:17 +00:00
Fred Drake c392b570db Integrated an expanded version of some text from Neil Schemenauer about
supporting cyclic garbage collection.  (This is not all of it, but I'm
taking a break!)

Also fixed some markup nits.
2001-03-21 22:15:01 +00:00
Fred Drake 83e01bf6c8 Finally fill in the documentation for the PyDict_Next() function. It is
different enough to actually require an explanation.  ;-)

Fix a couple of PyDictObject* types that should be PyObject* types.
2001-03-16 15:41:29 +00:00
Guido van Rossum 1874c8f23b Document PyErr_WarnExplicit(). 2001-02-28 23:46:44 +00:00
Fred Drake a05460c148 PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
This closes SF bug #131304.
2001-02-12 17:38:18 +00:00
Fred Drake f0e08ef9cb Remove an now-false statement about there being only one type flag
defined.
2001-02-03 01:11:26 +00:00
Fred Drake 5838d0fc84 Document the PyInstance_*() functions and data. 2001-01-28 06:39:35 +00:00
Fred Drake 5566c1ce36 Fixed a bunch of typos caught by Gilles Civario. 2001-01-19 22:48:33 +00:00
Marc-André Lemburg a544ea2354 Undoing the whitespace patches which sneaked into the earlier patch. 2001-01-17 18:04:31 +00:00
Marc-André Lemburg ad7c98e264 This patch adds a new builtin unistr() which behaves like str()
except that it always returns Unicode objects.

A new C API PyObject_Unicode() is also provided.

This closes patch #101664.

Written by Marc-Andre Lemburg. Copyright assigned to Guido van Rossum.
2001-01-17 17:09:53 +00:00
Fred Drake 81473b12b7 The Python/C API deals in PyObject*, not PyDictObject*. 2001-01-08 05:53:53 +00:00
Fred Drake 316ef7c574 Markup nit: Command line options should be marked with \programopt. 2001-01-04 05:56:34 +00:00
Guido van Rossum e22e4b2b59 Oops. The value "0 or +1" for the category argument of PyErr_Warn()
doesn't work.  Make it 0.  (Although it really *should* be 0 or +1 --
the refcount is incremented when it is raised as an exception, but not
otherwise.)
2000-12-19 03:58:11 +00:00
Guido van Rossum 9a18a7ed03 Document Pyerr_Warn().
Add an XXX comment at the beginning expressing disappointment over the
confusing way refcount behavior of arguments is documented.
2000-12-19 03:53:57 +00:00
Guido van Rossum 3dbb406335 Document Pyerr_Warn(). 2000-12-19 03:53:01 +00:00
Fred Drake 6b3f3f2861 In the first discussion showing how to handle exceptions from C, make the
Python equivalent actually equivalent to the C code.  Also, in the C code,
place the "goto" statements on a line by themselves for better visibility
of statements that affect control flow.

This closes bug #123398.
2000-11-29 15:48:22 +00:00
Fred Drake ee814bf2c9 Added documentation for the Py_InitModule*() family of functions. 2000-11-28 22:34:32 +00:00
Fred Drake 0ac000cd54 Updates to reflect pending changes to the XML conversion process. 2000-11-22 16:42:37 +00:00
Fred Drake 8902442e2f Added exception to the rule that the buffer returned by PyString_AsString()
and PyString_AsStringAndSize() for strings that were just created using
PyString_FromStringAndSize(NULL, n).

This closes bug #117377.

Added warning about passing NULL to the concrete object functions; many of
them use the appropriate Py<Type>_Check() test, but do not check for NULL.

"de-allocated" --> "deallocated"
2000-10-23 16:00:54 +00:00
Fred Drake 89fb035248 For PyErr_Format(), note that the exception parameter can be a string or
class, but not an instance (since an instance will be created using the
formatted message string as the constructor parameter).
2000-10-14 05:49:30 +00:00
Fred Drake 5d64421c23 Fix a couple of places where the descriptions of *_GET_SIZE() macros said
they were similar to *_GetSize(); should be similar to *_Size().

Error noted by William Park <parkw@better.net>.
2000-10-07 12:31:50 +00:00
Neil Schemenauer 410cb6be8f The _PyTuple_Resize() last_is_sticky flag must now always be false. 2000-10-05 19:38:24 +00:00
Fred Drake ffe58ca6ef Reversely --> Conversely
This closes SourceForge bug #115673.
2000-09-29 17:31:54 +00:00
Fred Drake 0b71ceaeff Note that including Python.h includes limits.h when available. 2000-09-26 05:51:50 +00:00
Fred Drake 891150bdf2 Added documentation for the new PyModule_*() convenience functions.
This closes SourceForge patch #101233.
2000-09-23 03:25:42 +00:00
Fred Drake 1fa9365066 Added refcount information for the *_InPlace*() API series.
This closes SourceForge bug #114287.
2000-09-22 18:19:37 +00:00
Fred Drake c0e6c5beb2 PyNumber_Coerce() returns an int, not a PyObject *. 2000-09-22 18:17:49 +00:00
Fred Drake ed773ef78d Include the new text on reporting bugs in a few useful places.
This closes SourceForge bug #114792.
2000-09-21 21:35:22 +00:00
Marc-André Lemburg d1ba443206 This patch adds a new Python C API called PyString_AsStringAndSize()
which implements the automatic conversion from Unicode to a string
object using the default encoding.

The new API is then put to use to have eval() and exec accept
Unicode objects as code parameter. This closes bugs #110924
and #113890.

As side-effect, the traditional C APIs PyString_Size() and
PyString_AsString() will also accept Unicode objects as
parameters.
2000-09-19 21:04:18 +00:00
Guido van Rossum c96ec6ef2b Document new APIs PyOS_getsig() and PyOS_setsig().
(Is there no macro to document a typedef?)

Fred, please check my latex!
2000-09-16 16:30:48 +00:00
Fred Drake d5d0435617 Use \shortversion in a number of places.
This partially addresses SourceForge bug #114318.
2000-09-14 20:24:17 +00:00
Fred Drake 933f0c38ef Avoid reference to specific versions of Python where possible.
This partially addresses SourceForge bug #114318.
2000-09-14 18:12:48 +00:00
Fred Drake 7740a01096 Thomas Wouters <thomas@xs4all.net>:
Fix up some of the PyNumber_*() documentation.
Add documentation for the InPlace API calls.
2000-09-12 20:27:05 +00:00
Fred Drake f913e542be Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Here are some changes to the C API docs. The memory examples & API have
been updated because one malloc family is gone (Py_Malloc).
You'll see other small additions to the "building new types" section
for completeness and some cleanup at the end of the memory section.
2000-09-12 20:17:17 +00:00
Fred Drake 81cccb7563 Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). 2000-09-12 15:22:05 +00:00
Moshe Zadka 57a5932f13 Update documentation for PyErr_Format, because the function has changed.
Connected to patch 100895
2000-09-01 09:47:20 +00:00
Fred Drake e0d9a83bea Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
struct _inittab.

This closes SourceForge bug #111499.
2000-09-01 05:30:00 +00:00
Jeremy Hylton b709df3810 refactor __del__ exception handler into PyErr_WriteUnraisable
add sanity check to gc: if an exception occurs during GC, call
PyErr_WriteUnraisable and then call Py_FatalEror.
2000-09-01 02:47:25 +00:00
Fred Drake 17e6343d2d Document PyOS_CheckStack().
Fix a couple of really minor markup nits.
2000-08-31 05:50:40 +00:00
Fred Drake 34c391d743 Correct the reference count information for the parameters of
PyErr_Restore().
2000-08-15 04:36:16 +00:00
Fred Drake 510d08bfe4 In the section on the "Very High Level Layer", address concerns brought up
by Edward K. Ream <edream@users.sourceforge.net> about FILE* values and
incompatible C libraries in dynamically linked extensions.  It is not clear
(to me) how realistic the issue is, but it is better documented than not.

This closes SourceForge bug #111520.
2000-08-14 02:50:21 +00:00
Fred Drake 4ca744c70e Added information for PyEval_EvalCode().
Fixed a couple of typos (new references are represented by "+1", not "1").
2000-08-12 03:39:47 +00:00
Fred Drake a8d7341f63 PyRun_InteractiveOne(),
PyRun_InteractiveLoop():  Added descriptions.

PyExc_WindowsError:  Added to list of standard exceptions and added note
                     about the right preprocessor symbol to use to protect
                     code that uses it.
2000-08-11 20:39:29 +00:00
Fred Drake 7d45d34ed7 ANY becomes void, to reflect the requirement for ANSI C. 2000-08-11 17:07:32 +00:00
Andrew M. Kuchling 8c46b30e0a Document PyObject_AsFileDescriptor 2000-07-13 23:58:16 +00:00
Marc-André Lemburg 4707320566 Added new APIs and fixed some other Unicode ones (missing * or
extra ' ').
2000-07-07 15:48:54 +00:00
Marc-André Lemburg 5a20b21fb1 Added docs for the new Unicode and string APIs. 2000-07-07 15:47:06 +00:00
Fred Drake ae96aab1fe Marc-Andre Lemburg <mal@lemburg.com>:
Update the API docs for the new macros Py_UNICODE_ISALPHA() and
Py_UNICODE_ISALNUM().
2000-07-03 13:38:10 +00:00
Fred Drake e06f0f9a13 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2. 2000-06-30 15:52:39 +00:00
Fred Drake d04038d9d2 Update comments relating to the removal of the -X option and of string
exceptions in the interpreter and standard library.
2000-06-29 20:15:14 +00:00
Fred Drake cabbc3be5b Added documentation for PyOS_AfterFork(). 2000-06-28 15:53:13 +00:00
Fred Drake 1d15869534 Markup consistency nits. 2000-06-18 05:21:21 +00:00
Fred Drake 992fe5a83e Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support. 2000-06-16 21:04:15 +00:00
Fred Drake 1c2d06acaf Added reference count information for PySequence_List(). 2000-06-16 20:00:04 +00:00
Fred Drake a8455abcf8 Documented PySequence_List() and PySequence_Tuple().
Added a bit more documentation in the chapter on building extension types,
including Py_FindMethod() documentation.

Several minor consistency nits were fixed.
2000-06-16 19:58:42 +00:00
Fred Drake 8520cc2328 Added reference count information for Py_FindMethod(). 2000-04-10 19:38:24 +00:00
Fred Drake 7357770153 Yet another markup nit: functions that are part of the Python/C API
are still C functions, and should be marked.
2000-04-10 18:50:14 +00:00
Fred Drake 37f41565a8 PyErr_Format():
Remove statement that the return value is always NULL; this is
        generated by the formatting.
2000-04-10 18:46:22 +00:00
Jeremy Hylton 98605b54b4 document PyErr_Format 2000-04-10 18:40:57 +00:00
Fred Drake 8394595f3b Add to the comment a description of the "null" value for returned
PyObject* values.
2000-04-10 18:29:21 +00:00
Fred Drake db2764d941 The reference count field for PyErr_NoMemory() and
PyErr_SetFromErrno() should be "null".
2000-04-10 18:25:09 +00:00
Fred Drake a4cd2611f4 Marc-Andre Lemburg <mal@lemburg.com>:
API documentation for Unicode support from C.
2000-04-06 14:10:29 +00:00
Fred Drake 659ebfa79e Merge in changes from the 1.5.2p2 release.
Hopefully I got all this right!
2000-04-03 15:42:13 +00:00
Fred Drake eb725cd045 Merged changes from the 1.5.2p2 release. 2000-04-03 15:06:40 +00:00
Fred Drake ddc6c276b7 Improve explanation of reference counts for PyString_Concat(). 2000-03-31 18:22:38 +00:00
Jeremy Hylton a12c7a7620 Add PyDict_Copy() function to C API for dicts. It returns a new
dictionary that contains the same key/value pairs as p.
2000-03-30 22:27:31 +00:00
Fred Drake 310ee61f20 Missed a couple of program options that had been marked by \code. 1999-11-09 17:31:42 +00:00
Fred Drake be48646cfa Use \citetitle and \programopt as appropriate. 1999-11-09 17:03:03 +00:00
Fred Drake 805bf1b330 Added note that Skip created the initial version of this file.
Fixed up a few of his ??? comments.
1999-10-20 16:03:38 +00:00
Fred Drake 7b7dc6b49d Initial version as provided by Skip Montanaro <skip@mojam.com>. 1999-10-20 15:06:24 +00:00
Fred Drake c924b8d976 Clarified start parameter to Py_CompileString, documented
Py_eval_input, Py_file_input, and Py_single_input.

Problems reported by Aaron Brancotti <aaron@icona.it>.
1999-08-23 18:57:25 +00:00
Fred Drake 58c5a2a53c Started documentation on buffer objects & types. Very preliminary.
Greg Stein:  Please help with this; it's your baby!
1999-08-04 13:13:24 +00:00
Guido van Rossum 32bc45f737 Removed PyMapping_Clear() -- it was wishful thinking and serves no
great purpose.
1999-08-02 20:49:37 +00:00
Fred Drake dab44682c2 PyCObject_FromVoidPtr(): Clarify that the destr function will only be
called on destruction is non-NULL.
1999-05-13 18:41:14 +00:00
Fred Drake 0041a94e74 Fill in a few holes in the "Very High Level" chapter. 1999-04-29 04:20:46 +00:00
Fred Drake 127ed0a71e Updated list of standard exceptions in section 4.1. 1999-02-17 23:09:05 +00:00
Fred Drake 66b989c805 Be explicit about the reference count of the original value of the
first parameter to PyString_Concat().
1999-02-15 20:15:39 +00:00
Fred Drake efd146c916 Markup nits.
Added section on module objects; described functions in
moduleobject.c.
1999-02-15 15:30:45 +00:00
Guido van Rossum d1dbf633ed Header for PyObject_DelItem() mentioned non-existing 3rd argument. 1999-01-22 20:10:49 +00:00
Fred Drake 2f8592cbea Ignore the byproducts of SGML/XML conversions for now. 1998-12-01 18:58:28 +00:00
Guido van Rossum a096a2e6a2 Warn that AddModule doesn't import the module. 1998-11-02 17:02:42 +00:00
Guido van Rossum 0a0f11b6d4 PyMapping_SetItemString() returns int, not an object. 1998-10-16 17:43:53 +00:00
Guido van Rossum ed9dcc10f8 Clarify that the Python interpreter lock need *not* be held by
PyInterpreterState_New() and PyThreadState_New() -- but that you may
use it to serialize calls to them.
1998-08-07 18:28:03 +00:00
Fred Drake 9f86b662d1 Update to use a separate page for front matter. 1998-07-28 21:55:19 +00:00
Guido van Rossum a937d14898 Fred's right -- we need PyList_SET_ITEM(). 1998-04-24 18:22:02 +00:00
Fred Drake f8830d1de5 Convert recent additions to use new, "logical" markup.
I suppose we really do need a markup guide.  -sigh-
1998-04-23 14:06:01 +00:00
Guido van Rossum 4447513e94 Filled in some more blanks, with the help of Drew Csillag. 1998-04-21 15:30:01 +00:00
Guido van Rossum 3c4378bd9b Some patches by Drew Csillag; plus a few of my own uncommitted changes. 1998-04-14 20:21:10 +00:00
Fred Drake 003d8da779 Typo: (and often severly limited) -- severely
Typo: (but not to the tuple or list into which the item it put!) -- is put

Thanks, AMK!
1998-04-13 00:53:42 +00:00
Fred Drake c94d9348ca In descriptions of Py_GetPrefix() and Py_GetExecPrefix(), make sure the
"--" at the start of the configure options isn't collapsed to "-" when the
HTML is generated.
1998-04-12 02:39:13 +00:00
Fred Drake 2de75ec245 Don't assume that \version expands to the 3-character major.minor number; it
is the full release version name ("1.5.1beta1", for instance).
1998-04-09 14:12:11 +00:00
Fred Drake 7e9d3148d1 Capitalize "Python" for consistency. 1998-04-03 05:02:28 +00:00
Fred Drake c6fa34e4d0 Markup consistency & nits.
Fix typo in a C code example:  KeyError is spelled PyExc_KeyError in C; the
"K" is upper case!

Some index entries.

On function signatures, always use parameter names.  Make return types match
what's in the header files.  When the return type is a pointer, always omit
the space between te type name and the "*"; leaving it in results in

	type * func(..)

and having two spaces there just looks terrible.
1998-04-02 06:47:24 +00:00
Fred Drake f3aa0e0627 Revert the index stuff to work better with LaTeX2HTML. 1998-03-17 06:23:13 +00:00
Fred Drake 7d20ffe245 Adjust the index inclusion for the new index support. 1998-03-09 16:39:22 +00:00
Fred Drake 6659c30b67 Convert LaTeX support to create a new class of documents. HTML generation
now requires LaTeX2HTML 98.1p1 or newer (& and is still in progress).

This means that doing things to change the formatting of the manuals (at the
"normal user" level, like A4 paper), can happen in just one place, rather
than in each document file.
1998-03-03 22:02:19 +00:00
Fred Drake f39ed67fa2 Added \label{}s for logical addressing. 1998-02-26 22:01:23 +00:00
Fred Drake b92dce38e7 PyFile_FromFile() description: make sure the closing brace for the arguments
comes after the arguments are complete.
1998-02-25 15:40:22 +00:00
Fred Drake 7baf3d4ea7 Fixed typo reported by Vladimir Marangozov <Vladimir.Marangozov@imag.fr>. 1998-02-20 00:45:52 +00:00
Fred Drake 9d20ac36a9 Removed various "(New in 1.5a?!)" constructs. Other notes pertaining to
versioning remain intact.
1998-02-16 15:27:08 +00:00
Fred Drake 4de05a90be Place C typedef for Py_complex after brief description, to be more consistent
with the other example of a structure description (struct _frozen).

Added index entries for the modules referenced in the document.
1998-02-16 14:25:26 +00:00
Fred Drake 53fb7723ee Added index enties for the Python built-in functions, where appropriate. 1998-02-16 06:23:20 +00:00
Fred Drake e058b4f124 Lots of nitty-gritty stuff:
Use \emph{} when referring to title of any of the Python manuals, like is
done in the other manuals.

In some places, use \emph{} or \dfn{} instead of ``...''.

Use \samp{} instead of \code{} when marking identifier prefixes.

Use logical markup wherever it made sense.

Fixed a bunch of typos.

In several places, use "---" instead of "--" to get the emdash.

Start sentences with capital letters and end them with periods, as needed.

"it's" --> "its" in many places:  "it's" it *always* a contraction of "it is",
and "its" should always be used for the possessive.

"don't" --> "doesn't"

"should discards any" --> "should discard any"

In C function descriptions, use \var{} to mark parameters in the running
text instead of \code{}.  This matches usage in the other manauls better,
and is more consistent with the formatting of the function signatures.
Lots of little changes to implement this.

Lots of fixups needed due to appearant heavy cut-&-paste in the orignal
document.

Mention that the exception objects may be either classes or strings,
depending on the use of -X; they were unequivocally stated to be strings
in the section "Standard Exceptions".

"mkvalue()" --> "Py_BuildValue()"

Description of PyNumber_Power() indicates that the third value is option,
but not how to indicate that it was omitted.  Clarified.

Explain the behavior of PyString_FromStringAndSize() if the buffer is NULL.

Explain the Py_complex structure a little (tell what it's used for) and use
a {verbatim} environment for the structure definition itself.

Fix explanation of PyFile_SoftSpace().

Update the example version string to 1.5.

Combined the sections on defining new object types.
1998-02-16 06:15:35 +00:00
Fred Drake 2a4646c660 Remove obsolete pagenumbering / pagestyle cruft. 1998-02-13 07:08:56 +00:00
Fred Drake e5bc49785c "ASCII" --> "\ASCII{}" 1998-02-12 23:36:49 +00:00
Fred Drake e5bf8b2c79 Reorganized a bit. No changed content.
Guido, please take a look at new structure, at least the ToC.
1998-02-12 21:22:28 +00:00
Fred Drake f44617d298 For sections describing the "Foo Protocol", consistently use the capitalized
"Protocol" and not "protocol".
1998-02-12 20:57:15 +00:00
Fred Drake faa1afe2d7 Py_Exit(status) calls exit(status), not exit(0). 1998-02-12 20:51:02 +00:00
Fred Drake c6c921a4de Py_AtExit(): Added brief note about the constraint on cleanup functions not
calling the Python API.
1998-01-26 19:16:27 +00:00
Fred Drake 4d4f9e726a Removed \mytableofcontents; just use \tableofcontents. 1998-01-13 22:25:02 +00:00
Fred Drake b0a78738ea Consistency:
"Unix" ==> "\UNIX{}"

"C" ==> "\C{}"

"C++" ==> "\Cpp{}"
1998-01-13 18:51:10 +00:00
Fred Drake dca8792b52 Added openright option the the \documentclass{} for each of the manuals. 1998-01-13 16:53:23 +00:00
Fred Drake 1f8449af4e Revise prologue and frontmatter to use latex2e (not in 2.09 compatibility
mode) and take advantage of changes in myformat.sty.
1998-01-09 05:36:43 +00:00
Fred Drake 85a5c52752 Descriptions for PyRun_String(), PyRun_File(), and PyRun_CompileString() all
gave the return type as part of the function field and used an empty return
type field.  Fixed.

Function name field for PyLong_FromString() included an asterisk at the
beginning of the function name field; removed.
1998-01-02 03:24:19 +00:00
Guido van Rossum 5b8a523538 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.
1997-12-30 04:38:44 +00:00
Guido van Rossum 580aa8dbc3 Several changes, e.g. restructuring of the intro to be closer to what
it ought to be.  Maybe the last checkin before 1.5b1 is released.
1997-11-25 15:34:51 +00:00
Fred Drake 36fbe76a45 struct _frozen:
Use spaces instead of tabs to indent structure definition; tabs don't
	work in tex/latex.

PyImport_FrozenModules:
	struct _freeze ==> struct _frozen
1997-10-13 18:18:33 +00:00
Guido van Rossum 9faf4c57b0 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
which appears to be out of fashion in this file.
1997-10-07 14:38:54 +00:00
Guido van Rossum c44d3d6664 Done with tread state descriptions. Sigh! 1997-10-06 05:10:47 +00:00
Guido van Rossum 42cefd03cf Checkpoint. Added docs for the new exception handling APIs and for
the interfaces defined in import.h.
1997-10-05 15:27:29 +00:00
Guido van Rossum b904629f75 Fix some badly botched prototypes for PyRun* c.s. 1997-08-21 02:28:57 +00:00
Guido van Rossum 5060b3be9b Consistently change Python-C API to Python/C API; added lots of new
introductory text for reference counts and error handling, with good
examples.
1997-08-17 18:02:23 +00:00
Guido van Rossum 09270b51e4 Fixes to make it pass latex without complaints. 1997-08-15 18:57:32 +00:00
Guido van Rossum 4a944d7a47 Added more stuff on initialization (still rudimentary) 1997-08-14 20:35:38 +00:00
Guido van Rossum 59a61352ad Added new intro sections (incomplete); fixed various typos 1997-08-14 20:34:33 +00:00
Guido van Rossum ae110af13b Just another checkin for backup. Nothing substantial yet. 1997-05-22 20:11:52 +00:00
Guido van Rossum 9231c8f176 Made a start with api.tex, the Python-C API Reference Manual.
Removed extref.tex (which provided the starting point).
Also removed qua.tex, which is out of date and no longer needed.
1997-05-15 21:43:21 +00:00