Commit Graph

220 Commits

Author SHA1 Message Date
Jim Fulton aed0a4a138 Rewrote the basic section of the chapter on defining new types.
Changed the example to show how to create types the new way:

- Use a class new method rather than a new function.

- Use self->ob_type->tp_free in deallocators

- Use attribute descriptors rather than set/getattr methods.

- Make the type usable as a base type.

I split the example into 3 parts:

1. The minimal new type

2. Adding attributes and methods.

3. Finer control over attributes.

It's much simpler to define builtin types. These updates hopefully
show this.

I also made minor wording changes in two other places.

I still need to update xxobject.c
2003-05-07 19:48:13 +00:00
Michael W. Hudson 241c2e9692 Remove another lie. 2003-02-06 18:38:11 +00:00
Greg Ward d4fee28717 Rewrite awkward/ungrammatical sentence.
Typo fix.
2003-01-08 03:02:26 +00:00
Greg Ward fdf65d9106 Grammatical fix: change possessive "it's" to "its". 2003-01-03 21:09:57 +00:00
Greg Ward 3ebf56c60f Two more typo fixes. 2002-12-17 23:27:41 +00:00
Greg Ward 1d5d8cf61f Typo fix. 2002-12-17 18:14:21 +00:00
Neal Norwitz 0f30dbd991 Fix SF # 626275, missing DECREF's in embedding example
Tested w/valgrind, all paths except the return on PyInt_AsLong() failure
I think I got all of these right.

Backport candidate.
2002-12-17 00:40:38 +00:00
Neal Norwitz 75bc8ba0d7 Fix SF # 646578, Documentation Typo 2002-12-02 04:42:58 +00:00
Neal Norwitz ae6bf4adfa Remove unused variable 2002-12-02 04:40:21 +00:00
Fred Drake cc6cc5ddff Fix minor markup nits. 2002-11-05 16:52:50 +00:00
Greg Ward 373198e751 Fix peculiar (and ungrammatical) wording in an example program. 2002-08-22 19:15:35 +00:00
Mark Hammond 543fb35cca Replace DL_EXPORT with PyMODINIT_FUNC 2002-07-31 06:17:46 +00:00
Mark Hammond 8235ea1c3a Land Patch [ 566100 ] Rationalize DL_IMPORT and DL_EXPORT. 2002-07-19 06:55:41 +00:00
Fred Drake 50ceb68b4f Change staticforward and statichere to just use static.
Removed ^M from some line-ends.
2002-07-17 16:42:48 +00:00
Fred Drake a3cd9bbaa3 Remove now-obsolete staticforward/statichere discussion. 2002-07-17 16:40:39 +00:00
Thomas Heller 291e9ee341 Fix a typo. 2002-07-04 08:36:53 +00:00
Fred Drake 723f94bd66 Convert the example C code to ANSI rather than K&R.
This matches the Python C style guide (PEP 7).
Closes SF patch #571489.
2002-06-22 01:42:00 +00:00
Greg Ward 6f45eeb0f3 Typo fix. 2002-06-21 12:33:08 +00:00
Guido van Rossum 18ca791028 Typo. 2002-05-16 14:45:37 +00:00
Fred Drake 4e7655558c Fix broken reference, minor clarification. 2002-05-16 13:48:14 +00:00
Fred Drake 742dc774af Typo: build -> built 2002-05-16 13:48:01 +00:00
Fred Drake 9aa97e835d Minor wording changes, plus correct a typo. 2002-05-14 22:02:07 +00:00
Fred Drake c55ae4b98c Clean up the use of version numbers in filenames; always use an "abstract"
version number, and explain what it is at the top of the chapter.
This closes SF bug #225003.
2002-04-19 04:04:57 +00:00
Fred Drake c63042bcc4 Move the listing of the type structure, since both the C API reference and
the Extending & Embedding manual use it.
2002-04-15 18:43:20 +00:00
Fred Drake fd92304ae8 Update the type of the tp_free slot. 2002-04-12 19:49:13 +00:00
Fred Drake 63e40a598d Do not use PyModule_GetDict().
Clean up the example of exporting a C-callable API from an extension module.
Add a hyperlink to a related section in the Python/C API reference.
2002-04-12 19:08:31 +00:00
Fred Drake e77e5ef2af Change example of retrieving & calling a Python function to not use
PyModule_GetDict(), which is also more flexible: it does not assume that the
"module" is a real module.
2002-04-12 19:04:17 +00:00
Fred Drake 292da58a5c Change the type of the tp_dealloc back to what it really is.
Change a section title to fit in better.
2002-04-12 18:28:08 +00:00
Fred Drake ee48519bc6 Modernize the minimal example of an extension type. 2002-04-12 16:17:06 +00:00
Fred Drake 0babc44ab2 Update the type of tp_dealloc. 2002-04-12 15:37:43 +00:00
Fred Drake 375e30225e Update to use the new \csimplemacro macro 2002-04-09 21:09:42 +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 9651198db4 Remove weird spacing in typeset version of the chapter head. 2002-04-05 19:54:19 +00:00
Fred Drake 103b548a76 Add a note warning against semicolons following PyObject_HEAD.
Minor cleanups.
2002-04-02 15:42:46 +00:00
Fred Drake d764b0a484 There is no PyArg_ConvertTuple(); call it by the right name.
This closes SF bug #537511.
2002-04-01 23:12:25 +00:00
Fred Drake fe5a5388c3 Use the right types for a couple of fields of the type structure. 2002-03-29 22:46:04 +00:00
Fred Drake 0ffd14c9ea Started updating information about defining attributes on types.
There's still a long way to go, but we're starting to see some real
content in the docs.
2002-03-29 22:45:28 +00:00
Fred Drake b1af6376e9 Mark a couple of types that had not been marked. 2002-03-28 23:46:41 +00:00
Fred Drake 0f9a34da2c Added comments for more entries of the type structure in the example
type implementation.
2002-03-28 23:45:22 +00:00
Fred Drake 2ab0a10913 The new files included by \verbatiminput in newtypes.tex. 2002-03-28 23:32:53 +00:00
Fred Drake 81b750d467 Move some of the longer example code to external fragments, and
include them using \verbatiminput.  This has the advantage that pages
can still break at reasonable places, and examples that go longer than
a page won't get cut off.

Make a few small markup adjustments for consistency.

Explain that PyObject_New() is not a C function but a polymorphic
beast that returns a pointer to the type that's passed as the first
arg.

Explain why type objects use the PyObject_VAR_HEAD.
2002-03-28 23:12:09 +00:00
Fred Drake e9fba9188e Added index entries. 2002-03-28 22:36:56 +00:00
Fred Drake 31f8483eef Allow a page break in a code longish example. 2002-03-28 20:19:23 +00:00
Fred Drake 5d117472b4 Describe how to support the iterator protocol in extension types.
This closes SF bug #420851.
2002-03-13 03:55:11 +00:00
Martin v. Löwis 27761f39a5 Patch #500136: Update Update ext build documentation. 2.2.1 candidate. 2002-03-09 10:06:14 +00:00
Michael W. Hudson 8fbd4a3e78 That hasn't been my email address for a while! 2002-01-16 14:55:05 +00:00
Marc-André Lemburg 3e3eacb5fc Fixed "u#" parser marker to pass through Unicode objects as-is without
going through the buffer interface API.

Added tests for this to the _testcapi module and updated docs.
2002-01-09 16:21:27 +00:00
Fred Drake 5f29319197 Replace the "Cookbook approach" with the approach documented in
PC/example_nt/readme.txt; this one does not rely on any external scripts.
This "fixes" SF bug #221671 and most of SF bug #225003.
2001-12-13 17:20:32 +00:00
Fred Drake 145b479508 Added discussion of protecting against screwing up the exception state in
an object's deallocator, including an example of how to do this.
2001-12-11 19:28:22 +00:00
Guido van Rossum 44b3f76adf More info about the cycle detector. 2001-12-07 17:57:56 +00:00
Tim Peters 874c4f0f99 Trivial spelling repair on new cyclic garbage text. 2001-12-07 17:51:41 +00:00
Fred Drake 024e647972 Added more information about reference counting limitations and the cycle
detector.
This closes SF bug #484950.
2001-12-07 17:30:40 +00:00
Fred Drake 92024d1a99 Clarify the description of the creation of an owned reference from an API
function.
This closes SF bug #486657.
2001-11-29 07:16:19 +00:00
Fred Drake 99181ac64e Add an index entry for the discussion of PyEval_CallObject().
This is related to SF bug #485165.
2001-11-29 05:02:34 +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 ef6373a4f6 Exhibit good form in C code: always provide docstrings in method tables, and
always fill in all slots of table entries.
Fixed a few minor markup errors.
2001-11-17 06:50:42 +00:00
Fred Drake 0aa811c527 Use the \note and \warning macros where appropriate. 2001-10-20 04:24:09 +00:00
Guido van Rossum 7a59445e37 Document required return values -1, 0, 1 for tp_compare handler, as
suggested in SF patch #424475.  Also document exception return.
2001-10-16 20:32:05 +00:00
Tim Peters d38b1c74f3 SF [#466125] PyLong_AsLongLong works for any integer.
Generalize PyLong_AsLongLong to accept int arguments too.  The real point
is so that PyArg_ParseTuple's 'L' code does too.  That code was
undocumented (AFAICT), so documented it.
2001-09-30 05:09:37 +00:00
Fred Drake 3ab0ac7cd4 Remove comment that no longer applies. 2001-09-26 22:26:45 +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
Fred Drake 9b88b4c9e8 Do not #include <stdio.h> since Python.h already does that. 2001-09-06 16:20:33 +00:00
Fred Drake adaca02f9e Use the standard argument convention for main(), and conform to the
Python/C style guide.
2001-09-06 16:17:24 +00:00
Barry Warsaw da21ce3e31 On Fred's suggestion, convert sprintf() examples to use
PyString_FromFormat().  Also fixed one grammar problem, and a few
other mark-up issues.  Sample code not checked.
2001-08-29 01:41:58 +00:00
Fred Drake cc8f44b884 Split "Extending & Embedding" into separate files, one per chapter. 2001-08-20 19:30:29 +00:00
Fred Drake ce1650f3a5 A large contribution from Dave Kuhlman describing what each of the slots
in the type object is used for, for many of the more commonly used slots.
Thanks!

(But there is still a lot more to write on this topic.)
Markup and organizational changes by your friendly neighborhood
documentation czar.
2001-08-15 19:07:18 +00:00
Fred Drake 53765753c4 Lots of new text and example code on embedding Python in C, contributed
by Albert Hofkamp.  Some editing has been done for style and markup
consistency.

This also supplies an example of importing modules and calling a function
defined in the module, so this closes SF bug #440037 as well.

(The long example code was moved to a separate file so that it would
format properly.)
2001-08-04 01:58:36 +00:00
Martin v. Löwis 4f1cd8bdcb Patch #411138: Rename config.h to pyconfig.h. Closes bug #231774. 2001-07-26 13:41:06 +00:00
Fred Drake 3332778f35 Corrected a section reference (title was wrong).
Added information on the return values of PyArg_ParseTuple() and
PyArg_ParseTupleAndKeywords().
2001-07-20 20:59:49 +00:00
Fred Drake 7a889ceb1e Minor change to match the style guide. 2001-07-14 02:27:22 +00:00
Fred Drake 15e33d828c 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-06 06:49:32 +00:00
Fred Drake d5df09cfb6 Update to include the license information in a less annoying place. 2001-06-20 21:37:34 +00:00
Marc-André Lemburg 6f15e5796e Added new parser markers 'et' and 'et#' which do not recode string
objects but instead assume that they use the requested encoding.

This is needed on Windows to enable opening files by passing in
Unicode file names.
2001-05-02 17:16:16 +00:00
Fred Drake f531ad698c Markup nit: For the Python documents, we use \empt instead of \textit. 2001-03-19 04:19:56 +00:00
Fred Drake 93fe96a3c8 Py_BuildValue(): Add "D" conversion to create a Python complex value from
a Py_complex C value.

Patch by Walter Dörwald.
This closes SF patch #407148.
2001-03-12 21:06:31 +00:00
Fred Drake 80d4c07775 There was a real leak in the "export a C API" example; fix that one.
(There are too many initspam() functions; they need to be renamed
post-beta.)
2001-03-02 19:48:06 +00:00
Fred Drake 0539bfaaa4 There is no longer a -X option to the interpreter, so remove the comments
on how PyErr_NewException() behaves in that case.

Clarify why an owned reference is kept in an extension module's
variable that refers to the result of PyErr_NewException(); one reader
thought that was a leak.

Clean up some tabs and simplify some markup.
2001-03-02 18:15:11 +00:00
Fred Drake f6a9617ba0 Michael Hudson <mwh21@cam.ac.uk>:
New material on defining extension types.  Thanks!

(Small markup adjustments made, but this is mostly as received.)
2001-02-19 19:22:00 +00:00
Fred Drake bcb09fa33f Worked around bug SF #125880: changed the text of three sections that
really nasty TeX source to "bleed" into the PDF "bookmarks".
2001-01-22 18:38:00 +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 aa126e1e21 Corrected a number of typos reported by Gilles Civario
<gcivario@users.sourceforge.net>.

This closes bug #122562.
2000-11-17 18:20:33 +00:00
Fred Drake 4bc0aed3a6 Fix cut & paste error that describes three paramters when there are only
two [bug #119729].

Update use of distutils.sysconfig that "broke" when Greg W. changed the API
[bug #119645].
2000-11-02 21:49:17 +00:00
Fred Drake 585698aa59 All acknowledgements have been moved to the Doc/ACKS file.
Adjusted to reflect the rename of Setup.in to Setup.dist.

Added pointer to the "Distributing Python Modules" manual in the
appropriate place.
2000-10-26 17:19:58 +00:00
Fred Drake 4dc1a6d6ba Added some comments on the interaction of reload() and extension modules.
Based on comments from Chris Barker <cbarker@jps.net>.
2000-10-02 22:38:09 +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 3578b77312 Special case the "s#" PyArg_Parse() token for Unicode objects:
"s#" will now return a pointer to the default encoded string data
of the Unicode object instead of a pointer to the raw UTF-16
data.

The latter is still available via PyObject_AsReadBuffer().
2000-09-21 21:08:08 +00:00
Fred Drake 1c25803647 Add a brief section on linking Python as an embedded scripting language.
This closes SourceForge bug #110833.
2000-09-08 22:54:53 +00:00
Fred Drake 4e15945fff Markup errors: \cfuntion -> \cfunction 2000-08-11 17:09:23 +00:00
Marc-André Lemburg 8b9835cdb2 Added descriptions of the new parser markers for PyArg_ParseTuple(). 2000-08-03 19:38:07 +00:00
Greg Stein c2844af87b needs a space 2000-07-09 16:27:33 +00:00
Fred Drake a83b68a143 Remove the only Py_PROTO in the docs. 2000-07-09 03:35:10 +00:00
Fred Drake 1739be50cb Small grammatical correction from Frank Stajano. Added comment with
suggestion from Frank for an example and further explanation.
2000-06-30 17:58:34 +00:00
Fred Drake ec105d0993 Enhanced memory-reference information in the description of Py_BuildValue(),
based on response from Frank Stajano <fstajano@uk.research.att.com>.
2000-06-28 16:15:08 +00:00
Fred Drake 2b9e180ec3 Added memory-reference information to the description of Py_BuildValue(),
based on comments from Frank Stajano <fstajano@uk.research.att.com>.
2000-06-28 15:32:29 +00:00
Fred Drake 65e69002a2 Oops, better also note that the module initialization function must be
extern "C" for C++.
2000-05-10 20:36:34 +00:00
Fred Drake 2d54523551 Section "The Module's Method Table and Initialization Function":
Explain that the name of the initialization function must be
        init<module>().  Omission noted by Daniel Kozan
        <crum@dev-group.com>.
2000-05-10 20:33:18 +00:00
Fred Drake 25871c001f Brian Hooper <brian_takashi@hotmail.com>:
Added 'u' and 'u#' tags for PyArg_ParseTuple - these turn a
PyUnicodeObject argument into a Py_UNICODE * buffer, or a Py_UNICODE *
buffer plus a length with the '#'.  Also added an analog to 'U'
for Py_BuildValue.
2000-05-03 15:17:02 +00:00
Fred Drake 3c3507fd4f Documentation patch describing the 'u' and 'u#' format specifiers,
from Brian Hooper <brian_takashi@hotmail.com>.
2000-04-28 14:43:33 +00:00
Fred Drake 54fd8452a1 Merge in changes from the 1.5.2p2 release. 2000-04-03 04:54:28 +00:00
Fred Drake 9fa76f1090 Use \citetitle in several places, and \programopt where appropriate. 1999-11-10 16:01:43 +00:00