9.1 Structured Documentation

futures.html | futures.html | discussion.html | Documenting Python | contents.html
---
## 9.1 Structured Documentation
Most of the small changes to the LATEX markup have been made
with an eye to divorcing the markup from the presentation, making
both a bit more maintainable. Over the course of 1998, a large
number of changes were made with exactly this in mind; previously,
changes had been made but in a less systematic manner and with
more concern for not needing to update the existing content. The
result has been a highly structured and semantically loaded markup
language implemented in LATEX. With almost no basic TEX or
LATEX markup in use, however, the markup syntax is about the
only evidence of LATEX in the actual document sources.
One side effect of this is that while we've been able to use
standard ``engines'' for manipulating the documents, such as
LATEX and LATEX2HTML, most of the actual transformations have
been created specifically for Python. The LATEX document
classes and LATEX2HTML support are both complete implementations
of the specific markup designed for these documents.
Combining highly customized markup with the somewhat esoteric
systems used to process the documents leads us to ask some
questions: Can we do this more easily? and, Can we do this
better? After a great deal of discussion with the community, we
have determined that actively pursuing modern structured
documentation systems is worth some investment of time.
There appear to be two real contenders in this arena: the Standard
General Markup Language (SGML), and the Extensible Markup Language
(XML). Both of these standards have advantages and disadvantages,
and many advantages are shared.
SGML offers advantages which may appeal most to authors,
especially those using ordinary text editors. There are also
additional abilities to define content models. A number of
high-quality tools with demonstrated maturity are available, but
most are not free; for those which are, portability issues remain
a problem.
The advantages of XML include the availability of a large number
of evolving tools. Unfortunately, many of the associated
standards are still evolving, and the tools will have to follow
along. This means that developing a robust tool set that uses
more than the basic XML 1.0 recommendation is not possible in the
short term. The promised availability of a wide variety of
high-quality tools which support some of the most important
related standards is not immediate. Many tools are likely to be
free, and the portability issues of those which are, are not
expected to be significant.
It turns out that converting to an XML or SGML system holds
promise for translators as well; how much can be done to ease the
burden on translators remains to be seen, and may have some impact
on the schema and specific technologies used.
XXX Eventual migration to XML.
The documentation will be moved to XML in the future, and tools
are being written which will convert the documentation from the
current format to something close to a finished version, to the
extent that the desired information is already present in the
documentation. Some XSLT stylesheets have been started for
presenting a preliminary XML version as HTML, but the results are
fairly rough..
The timeframe for the conversion is not clear since there doesn't
seem to be much time available to work on this, but the appearant
benefits are growing more substantial at a moderately rapid pace.


3 Style Guide

directories.html | doc.html | latex-primer.html | Documenting Python | contents.html
---
# 3 Style Guide
The Python documentation should follow the Apple Publications Style Guide (http://developer.apple.com/techpubs/macos8/pdf/apple_styleguide00.pdf) wherever possible. This particular
style guide was selected mostly because it seems reasonable and is
easy to get online. (Printed copies are available; see the Apple's
Developer
Documentation FAQ (http://developer.apple.com/techpubs/faq.html) for more information.)
Topics which are not covered in the Apple's style guide will be
discussed in this document if necessary.
Many special names are used in the Python documentation, including
the names of operating systems, programming languages, standards
bodies, and the like. Many of these were assigned LATEX macros
at some point in the distant past, and these macros lived on long
past their usefulness. In the current markup, most of these entities
are not assigned any special markup, but the preferred spellings are
given here to aid authors in maintaining the consistency of
presentation in the Python documentation.
Other terms and words deserve special mention as well; these conventions
should be used to ensure consistency throughout the documentation:
CPU: For ``central processing unit.'' Many style guides say this
should be spelled out on the first use (and if you must use it,
do so!). For the Python documentation, this abbreviation should
be avoided since there's no reasonable way to predict which occurance
will be the first seen by the reader. It is better to use the
word ``processor'' instead.
POSIX: The name assigned to a particular group of standards. This is
always uppercase. Use the macro \POSIX to represent this
name.
Python: The name of our favorite programming language is always
capitalized.
Unicode: The name of a character set and matching encoding. This is
always written capitalized.
Unix: The name of the operating system developed at AT&T Bell Labs
in the early 1970s. Use the macro \UNIX to use this name.


6.9 Table Markup

library-markup.html | special-constructs.html | references.html | Documenting Python | contents.html
---
## 6.9 Table Markup
There are three general-purpose table environments defined which
should be used whenever possible. These environments are defined
to provide tables of specific widths and some convenience for
formatting. These environments are not meant to be general
replacements for the standard LATEX table environments, but can
be used for an advantage when the documents are processed using
the tools for Python documentation processing. In particular, the
generated HTML looks good! There is also an advantage for the
eventual conversion of the documentation to XML (see section
9 (futures.html#futures), ``Future Directions'').
Each environment is named \tablecols, where cols
is the number of columns in the table specified in lower-case
Roman numerals. Within each of these environments, an additional
macro, \linecols, is defined, where cols
matches the cols value of the corresponding table
environment. These are supported for cols values of
`ii`, `iii`, and `iv`. These environments are all
built on top of the \tabular environment. Variants based on
the \longtable environment are also provided.
Note that all tables in the standard Python documentation use
vertical lines between columns, and this must be specified in the
markup for each table. A general border around the outside of the
table is not used, but would be the responsibility of the
processor; the document markup should not include an exterior
border.
The \longtable-based variants of the table environments are
formatted with extra space before and after, so should only be
used on tables which are long enough that splitting over multiple
pages is reasonable; tables with fewer than twenty rows should
never by marked using the long flavors of the table environments.
The header row is repeated across the top of each part of the
table.
An additional table-like environment is \synopsistable. The
table generated by this environment contains two columns, and each
row is defined by an alternate definition of
\modulesynopsis. This environment is not normally used by
authors, but is created by the \localmoduletable macro.
Here is a small example of a table given in the documentation for
the warnings module; markup inside the table cells is
minimal so the markup for the table itself is readily discernable.
Here is the markup for the table:
```text

\begin{tableii}{l|l}{exception}{Class}{Description}
\lineii{Warning}
{This is the base class of all warning category classes. It
is a subclass of \exception{Exception}.}
\lineii{UserWarning}
{The default category for \function{warn()}.}
\lineii{DeprecationWarning}
{Base category for warnings about deprecated features.}
\lineii{SyntaxWarning}
{Base category for warnings about dubious syntactic
features.}
\lineii{RuntimeWarning}
{Base category for warnings about dubious runtime features.}
\end{tableii}
```
Here is the resulting table:
Note that the class names are implicitly marked using the
\exception macro, since that is given as the col1font
value for the \tableii environment. To create a table using
different markup for the first column, use `textrm` for the
col1font value and mark each entry individually.
To add a horizontal line between vertical sections of a table, use
the standard \hline macro between the rows which should be
separated:
```text

\begin{tableii}{l|l}{constant}{Language}{Audience}
\lineii{APL}{Masochists.}
\lineii{BASIC}{First-time programmers on PC hardware.}
\lineii{C}{\UNIX{} \&\ Linux kernel developers.}
\hline
\lineii{Python}{Everyone!}
\end{tableii}
```
Note that not all presentation formats are capable of displaying a
horizontal rule in this position. This is how the table looks in
the format you're reading now:


8.1 External Tools

tools.html | tools.html | tools-internal.html | Documenting Python | contents.html
---
## 8.1 External Tools
Many tools are needed to be able to process the Python
documentation if all supported formats are required. This
section lists the tools used and when each is required. Consult
the Doc/README file to see if there are specific version
requirements for any of these.
dvips: This program is a typical part of TEX installations. It is
used to generate PostScript from the ``device independent''
.dvi files. It is needed for the conversion to
PostScript.
emacs: Emacs is the kitchen sink of programmers' editors, and a damn
fine kitchen sink it is. It also comes with some of the
processing needed to support the proper menu structures for
Texinfo documents when an info conversion is desired. This is
needed for the info conversion. Using xemacs
instead of FSF emacs may lead to instability in the
conversion, but that's because nobody seems to maintain the
Emacs Texinfo code in a portable manner.
latex: LATEX is a large and extensible macro package by Leslie
Lamport, based on TEX, a world-class typesetter by Donald
Knuth. It is used for the conversion to PostScript, and is
needed for the HTML conversion as well (LATEX2HTML requires
one of the intermediate files it creates).
latex2html: Probably the longest Perl script anyone ever attempted to
maintain. This converts LATEX documents to HTML documents,
and does a pretty reasonable job. It is required for the
conversions to HTML and GNU info.
lynx: This is a text-mode Web browser which includes an
HTML-to-plain text conversion. This is used to convert
`howto` documents to text.
make: Just about any version should work for the standard documents,
but GNU make is required for the experimental
processes in Doc/tools/sgmlconv/, at least while
they're experimental. This is not required for running the
mkhowto script.
makeindex: This is a standard program for converting LATEX index data
to a formatted index; it should be included with all LATEX
installations. It is needed for the PDF and PostScript
conversions.
makeinfo: GNU makeinfo is used to convert Texinfo documents to
GNU info files. Since Texinfo is used as an intermediate
format in the info conversion, this program is needed in that
conversion.
pdflatex: pdfTEX is a relatively new variant of TEX, and is used to
generate the PDF version of the manuals. It is typically
installed as part of most of the large TEX distributions.
pdflatex is pdfTEX using the LATEX format.
perl: Perl is required for LATEX2HTML and one of the scripts used
to post-process LATEX2HTML output, as well as the
HTML-to-Texinfo conversion. This is required for
the HTML and GNU info conversions.
python: Python is used for many of the scripts in the
Doc/tools/ directory; it is required for all
conversions. This shouldn't be a problem if you're interested
in writing documentation for Python!


8.2 Internal Tools

tools-external.html | tools.html | futures.html | Documenting Python | contents.html
---
## 8.2 Internal Tools
This section describes the various scripts that are used to
implement various stages of document processing or to orchestrate
entire build sequences. Most of these tools are only useful
in the context of building the standard documentation, but some
are more general.
mkhowto: This is the primary script used to format third-party
documents. It contains all the logic needed to ``get it
right.'' The proper way to use this script is to make a
symbolic link to it or run it in place; the actual script file
must be stored as part of the documentation source tree,
though it may be used to format documents outside the
tree. Use mkhowto --help
for a list of
command line options.
mkhowto can be used for both `howto` and
`manual` class documents. (For the later, be sure to get
the latest version from the Python CVS repository rather than
the version distributed in the latex-1.5.2.tgz source
archive.)
XXX Need more here.


8 Processing Tools

gui-markup.html | doc.html | tools-external.html | Documenting Python | contents.html
---
# 8 Processing Tools


About this document ...

node48.html | ext.html | Extending and Embedding the Python Interpreter | contents.html
---
# About this document ...
Extending and Embedding the Python Interpreter,
December 21, 2001, Release 2.2
This document was generated using the LaTeX2HTML (http://saftsack.fs.uni-bayreuth.de/~latex2ht/) translator.
LaTeX2HTML (http://saftsack.fs.uni-bayreuth.de/~latex2ht/) is Copyright ©
1993, 1994, 1995, 1996, 1997, Nikos
Drakos (http://cbl.leeds.ac.uk/nikos/personal.html), Computer Based Learning Unit, University of
Leeds, and Copyright © 1997, 1998, Ross
Moore (http://www.maths.mq.edu.au/~ross/), Mathematics Department, Macquarie University,
Sydney.
The application of LaTeX2HTML (http://saftsack.fs.uni-bayreuth.de/~latex2ht/) to the Python
documentation has been heavily tailored by Fred L. Drake,
Jr. Original navigation icons were contributed by Christopher
Petrilli.
---
## Comments and Questions
General comments and questions regarding this document should
be sent by email to python-docs@python.org (mailto:python-docs@python.org). If you find specific errors in
this document, please report the bug at the Python Bug
Tracker (http://sourceforge.net/bugs/?group_id=5470) at SourceForge (http://sourceforge.net/).
Questions regarding how to use the information in this
document should be sent to the Python news group, comp.lang.python (news:comp.lang.python), or the Python mailing list (http://www.python.org/mailman/listinfo/python-list) (which is gated to the newsgroup and
carries the same content).
For any of these channels, please be sure not to send HTML email.
Thanks.
---
node48.html | ext.html | Extending and Embedding the Python Interpreter | contents.html
---
Release 2.2, documentation updated on December 21, 2001.


1.3 Back to the Example

errors.html | intro.html | methodTable.html | Extending and Embedding the Python Interpreter | contents.html
---
# 1.3 Back to the Example
Going back to our example function, you should now be able to
understand this statement:
```text

if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
```
It returns NULL (the error indicator for functions returning
object pointers) if an error is detected in the argument list, relying
on the exception set by PyArg_ParseTuple(). Otherwise the
string value of the argument has been copied to the local variable
command. This is a pointer assignment and you are not supposed
to modify the string to which it points (so in Standard C, the variable
command should properly be declared as "const char
*command").
The next statement is a call to the Unix function
system(), passing it the string we just got from
PyArg_ParseTuple():
```text

sts = system(command);
```
Our spam.system() function must return the value of
sts as a Python object. This is done using the function
Py_BuildValue(), which is something like the inverse of
PyArg_ParseTuple(): it takes a format string and an
arbitrary number of C values, and returns a new Python object.
More info on Py_BuildValue() is given later.
```text

return Py_BuildValue("i", sts);
```
In this case, it will return an integer object. (Yes, even integers
are objects on the heap in Python!)
If you have a C function that returns no useful argument (a function
returning void), the corresponding Python function must return
`None`. You need this idiom to do so:
```text

Py_INCREF(Py_None);
return Py_None;
```
Py_None is the C name for the special Python object
`None`. It is a genuine Python object rather than a NULL
pointer, which means ``error'' in most contexts, as we have seen.


node28.html | ext.html | custom-interps.html | Extending and Embedding the Python Interpreter | contents.html
---
# 3. Building C and C++ Extensions on Unix
Starting in Python 1.4, Python provides a special make file for
building make files for building dynamically-linked extensions and
custom interpreters. The make file make file builds a make file
that reflects various system variables determined by configure when
the Python interpreter was built, so people building module's don't
have to resupply these settings. This vastly simplifies the process
of building extensions and custom interpreters on Unix systems.
The make file make file is distributed as the file
Misc/Makefile.pre.in in the Python source distribution. The
first step in building extensions or custom interpreters is to copy
this make file to a development directory containing extension module
source.
The make file make file, Makefile.pre.in uses metadata
provided in a file named Setup. The format of the Setup
file is the same as the Setup (or Setup.dist) file
provided in the Modules/ directory of the Python source
distribution. The Setup file contains variable definitions:
```text

EC=/projects/ExtensionClass
```
and module description lines. It can also contain blank lines and
comment lines that start with "#".
A module description line includes a module name, source files,
options, variable references, and other input files, such
as libraries or object files. Consider a simple example:
```text

ExtensionClass ExtensionClass.c
```
This is the simplest form of a module definition line. It defines a
module, ExtensionClass, which has a single source file,
ExtensionClass.c.
This slightly more complex example uses an -I option to
specify an include directory:
```text

EC=/projects/ExtensionClass
cPersistence cPersistence.c -I$(EC)
```
This example also illustrates the format for variable references.
For systems that support dynamic linking, the Setup file should
begin:
```text

*shared*
```
to indicate that the modules defined in Setup are to be built
as dynamically linked modules. A line containing only "*static*"can be used to indicate the subsequently listed modules should be
statically linked.
Here is a complete Setup file for building a
cPersistent module:
```text

# Set-up file to build the cPersistence module.
# Note that the text should begin in the first column.
*shared*

# We need the path to the directory containing the ExtensionClass
# include file.
EC=/projects/ExtensionClass
cPersistence cPersistence.c -I$(EC)
```
After the Setup file has been created, Makefile.pre.in
is run with the "boot" target to create a make file:
```text

make -f Makefile.pre.in boot
```
This creates the file, Makefile. To build the extensions, simply
run the created make file:
```text

make
```
It's not necessary to re-run Makefile.pre.in if the
Setup file is changed. The make file automatically rebuilds
itself if the Setup file changes.


distributing.html | ext.html | win-cookbook.html | Extending and Embedding the Python Interpreter | contents.html
---
# 4. Building C and C++ Extensions on Windows
This chapter briefly explains how to create a Windows extension module
for Python using Microsoft Visual C++, and follows with more
detailed background information on how it works. The explanatory
material is useful for both the Windows programmer learning to build
Python extensions and the Unix programmer interested in producing
software which can be successfully built on both Unix and Windows.


1.9 Building Arbitrary Values

parseTupleAndKeywords.html | intro.html | refcounts.html | Extending and Embedding the Python Interpreter | contents.html
---
# 1.9 Building Arbitrary Values
This function is the counterpart to PyArg_ParseTuple(). It is
declared as follows:
```text

PyObject *Py_BuildValue(char *format, ...);
```
It recognizes a set of format units similar to the ones recognized by
PyArg_ParseTuple(), but the arguments (which are input to the
function, not output) must not be pointers, just values. It returns a
new Python object, suitable for returning from a C function called
from Python.
One difference with PyArg_ParseTuple(): while the latter
requires its first argument to be a tuple (since Python argument lists
are always represented as tuples internally),
Py_BuildValue() does not always build a tuple. It builds
a tuple only if its format string contains two or more format units.
If the format string is empty, it returns `None`; if it contains
exactly one format unit, it returns whatever object is described by
that format unit. To force it to return a tuple of size 0 or one,
parenthesize the format string.
When memory buffers are passed as parameters to supply data to build
objects, as for the "s" and "s#" formats, the required data
is copied. Buffers provided by the caller are never referenced by the
objects created by Py_BuildValue(). In other words, if
your code invokes malloc() and passes the allocated memory
to Py_BuildValue(), your code is responsible for
calling free() for that memory once
Py_BuildValue() returns.
In the following description, the quoted form is the format unit; the
entry in (round) parentheses is the Python object type that the format
unit will return; and the entry in [square] brackets is the type of
the C value(s) to be passed.
The characters space, tab, colon and comma are ignored in format
strings (but not within format units such as "s#"). This can be
used to make long format strings a tad more readable.
"s" (string) [char *]: Convert a null-terminated C string to a Python object. If the C
string pointer is NULL, `None` is used.
"s#" (string) [char *, int]: Convert a C string and its length to a Python object. If the C string
pointer is NULL, the length is ignored and `None` is
returned.
"z" (string or `None`) [char *]: Same as "s".
"z#" (string or `None`) [char *, int]: Same as "s#".
"u" (Unicode string) [Py_UNICODE *]: Convert a null-terminated buffer of Unicode (UCS-2) data to a Python
Unicode object. If the Unicode buffer pointer is NULL,
`None` is returned.
"u#" (Unicode string) [Py_UNICODE *, int]: Convert a Unicode (UCS-2) data buffer and its length to a Python
Unicode object. If the Unicode buffer pointer is NULL, the length
is ignored and `None` is returned.
"i" (integer) [int]: Convert a plain C int to a Python integer object.
"b" (integer) [char]: Same as "i".
"h" (integer) [short int]: Same as "i".
"l" (integer) [long int]: Convert a C long int to a Python integer object.
"c" (string of length 1) [char]: Convert a C int representing a character to a Python string of
length 1.
"d" (float) [double]: Convert a C double to a Python floating point number.
"f" (float) [float]: Same as "d".
"D" (complex) [Py_complex *]: Convert a C Py_complex structure to a Python complex number.
"O" (object) [PyObject *]: Pass a Python object untouched (except for its reference count, which
is incremented by one). If the object passed in is a NULL
pointer, it is assumed that this was caused because the call producing
the argument found an error and set an exception. Therefore,
Py_BuildValue() will return NULL but won't raise an
exception. If no exception has been raised yet,
PyExc_SystemError is set.
"S" (object) [PyObject *]: Same as "O".
"U" (object) [PyObject *]: Same as "O".
"N" (object) [PyObject *]: Same as "O", except it doesn't increment the reference count on
the object. Useful when the object is created by a call to an object
constructor in the argument list.
"O&" (object) [converter, anything]: Convert anything to a Python object through a converter
function. The function is called with anything (which should be
compatible with void *) as its argument and should return a
``new'' Python object, or NULL if an error occurred.
"(items)" (tuple) [matching-items]: Convert a sequence of C values to a Python tuple with the same number
of items.
"[items]" (list) [matching-items]: Convert a sequence of C values to a Python list with the same number
of items.
"{items}" (dictionary) [matching-items]: Convert a sequence of C values to a Python dictionary. Each pair of
consecutive C values adds one item to the dictionary, serving as key
and value, respectively.
If there is an error in the format string, the
PyExc_SystemError exception is raised and NULL returned.
Examples (to the left the call, to the right the resulting Python value):
```text

Py_BuildValue("") None
Py_BuildValue("i", 123) 123
Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
Py_BuildValue("s", "hello") 'hello'
Py_BuildValue("ss", "hello", "world") ('hello', 'world')
Py_BuildValue("s#", "hello", 4) 'hell'
Py_BuildValue("()") ()
Py_BuildValue("(i)", 123) (123,)
Py_BuildValue("(ii)", 123, 456) (123, 456)
Py_BuildValue("(i,i)", 123, 456) (123, 456)
Py_BuildValue("[i,i]", 123, 456) [123, 456]
Py_BuildValue("{s:i,s:i}",
"abc", 123, "def", 456) {'abc': 123, 'def': 456}
Py_BuildValue("((ii)(ii)) (ii)",
1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
```


1.6 Calling Python Functions from C

compilation.html | intro.html | parseTuple.html | Extending and Embedding the Python Interpreter | contents.html
---
# 1.6 Calling Python Functions from C
So far we have concentrated on making C functions callable from
Python. The reverse is also useful: calling Python functions from C.
This is especially the case for libraries that support so-called
``callback'' functions. If a C interface makes use of callbacks, the
equivalent Python often needs to provide a callback mechanism to the
Python programmer; the implementation will require calling the Python
callback functions from a C callback. Other uses are also imaginable.
Fortunately, the Python interpreter is easily called recursively, and
there is a standard interface to call a Python function. (I won't
dwell on how to call the Python parser with a particular string as
input -- if you're interested, have a look at the implementation of
the -c command line option in Python/pythonmain.c
from the Python source code.)
Calling a Python function is easy. First, the Python program must
somehow pass you the Python function object. You should provide a
function (or some other interface) to do this. When this function is
called, save a pointer to the Python function object (be careful to
Py_INCREF() it!) in a global variable -- or wherever you
see fit. For example, the following function might be part of a module
definition:
```text

static PyObject *my_callback = NULL;

static PyObject *
my_set_callback(dummy, args)
PyObject *dummy, *args;
{
PyObject *result = NULL;
PyObject *temp;

if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
if (!PyCallable_Check(temp)) {
PyErr_SetString(PyExc_TypeError, "parameter must be callable");
return NULL;
}
Py_XINCREF(temp); /* Add a reference to new callback */
Py_XDECREF(my_callback); /* Dispose of previous callback */
my_callback = temp; /* Remember new callback */
/* Boilerplate to return "None" */
Py_INCREF(Py_None);
result = Py_None;
}
return result;
}
```
This function must be registered with the interpreter using the
METH_VARARGS flag; this is described in section
1.4 (methodTable.html#methodTable), ``The Module's Method Table and Initialization
Function.'' The PyArg_ParseTuple() function and its
arguments are documented in section 1.7 (parseTuple.html#parseTuple), ``Extracting
Parameters in Extension Functions.''
The macros Py_XINCREF() and Py_XDECREF()
increment/decrement the reference count of an object and are safe in
the presence of NULL pointers (but note that temp will not be
NULL in this context). More info on them in
section 1.10 (refcounts.html#refcounts), ``Reference Counts.''
Later, when it is time to call the function, you call the C function
PyEval_CallObject(). This
function has two arguments, both pointers to arbitrary Python objects:
the Python function, and the argument list. The argument list must
always be a tuple object, whose length is the number of arguments. To
call the Python function with no arguments, pass an empty tuple; to
call it with one argument, pass a singleton tuple.
Py_BuildValue() returns a tuple when its format string
consists of zero or more format codes between parentheses. For
example:
```text

int arg;
PyObject *arglist;
PyObject *result;
...
arg = 123;
...
/* Time to call the callback */
arglist = Py_BuildValue("(i)", arg);
result = PyEval_CallObject(my_callback, arglist);
Py_DECREF(arglist);
```
PyEval_CallObject() returns a Python object pointer: this is
the return value of the Python function. PyEval_CallObject() is
``reference-count-neutral'' with respect to its arguments. In the
example a new tuple was created to serve as the argument list, which
is Py_DECREF()-ed immediately after the call.
The return value of PyEval_CallObject() is ``new'': either it
is a brand new object, or it is an existing object whose reference
count has been incremented. So, unless you want to save it in a
global variable, you should somehow Py_DECREF() the result,
even (especially!) if you are not interested in its value.
Before you do this, however, it is important to check that the return
value isn't NULL. If it is, the Python function terminated by
raising an exception. If the C code that called
PyEval_CallObject() is called from Python, it should now
return an error indication to its Python caller, so the interpreter
can print a stack trace, or the calling Python code can handle the
exception. If this is not possible or desirable, the exception should
be cleared by calling PyErr_Clear(). For example:
```text

if (result == NULL)
return NULL; /* Pass error back */
...use result...
Py_DECREF(result);
```
Depending on the desired interface to the Python callback function,
you may also have to provide an argument list to
PyEval_CallObject(). In some cases the argument list is
also provided by the Python program, through the same interface that
specified the callback function. It can then be saved and used in the
same manner as the function object. In other cases, you may have to
construct a new tuple to pass as the argument list. The simplest way
to do this is to call Py_BuildValue(). For example, if
you want to pass an integral event code, you might use the following
code:
```text

PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
result = PyEval_CallObject(my_callback, arglist);
Py_DECREF(arglist);
if (result == NULL)
return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
```
Note the placement of "Py_DECREF(arglist)" immediately after the
call, before the error check! Also note that strictly spoken this
code is not complete: Py_BuildValue() may run out of
memory, and this should be checked.


1.5 Compilation and Linkage

methodTable.html | intro.html | callingPython.html | Extending and Embedding the Python Interpreter | contents.html
---
# 1.5 Compilation and Linkage
There are two more things to do before you can use your new extension:
compiling and linking it with the Python system. If you use dynamic
loading, the details depend on the style of dynamic loading your
system uses; see the chapters about building extension modules on
Unix (chapter 3 (building-on-unix.html#building-on-unix)) and Windows (chapter
4 (building-on-windows.html#building-on-windows)) for more information about this.
If you can't use dynamic loading, or if you want to make your module a
permanent part of the Python interpreter, you will have to change the
configuration setup and rebuild the interpreter. Luckily, this is
very simple: just place your file (spammodule.c for example) in
the Modules/ directory of an unpacked source distribution, add
a line to the file Modules/Setup.local describing your file:
```text

spam spammodule.o
```
and rebuild the interpreter by running make in the toplevel
directory. You can also run make in the Modules/
subdirectory, but then you must first rebuild Makefile
there by running `make Makefile'. (This is necessary each
time you change the Setup file.)
If your module requires additional libraries to link with, these can
be listed on the line in the configuration file as well, for instance:
```text

spam spammodule.o -lX11
```


Contents

front.html | ext.html | intro.html | Extending and Embedding the Python Interpreter
---
## Contents
Table of Contents
- Front Matter (front.html)
  1. Extending Python with C or C++ (intro.html)
  - 1.1 A Simple Example (simpleExample.html)
  1.2 Intermezzo: Errors and Exceptions (errors.html)
  1.3 Back to the Example (backToExample.html)
  1.4 The Module's Method Table and Initialization Function (methodTable.html)
  1.5 Compilation and Linkage (compilation.html)
  1.6 Calling Python Functions from C (callingPython.html)
  1.7 Extracting Parameters in Extension Functions (parseTuple.html)
  1.8 Keyword Parameters for Extension Functions (parseTupleAndKeywords.html)
  1.9 Building Arbitrary Values (buildValue.html)
  1.10 Reference Counts (refcounts.html)
  - 1.10.1 Reference Counting in Python (refcountsInPython.html)
  1.10.2 Ownership Rules (ownershipRules.html)
  1.10.3 Thin Ice (thinIce.html)
  1.10.4 NULL Pointers (nullPointers.html)
  1.11 Writing Extensions in C++ (cplusplus.html)
  1.12 Providing a C API for an Extension Module (using-cobjects.html)
  2. Defining New Types (defining-new-types.html)
  - 2.1 The Basics (dnt-basics.html)
  2.2 Type Methods (dnt-type-methods.html)
  - 2.2.1 Finalization and De-allocation (node23.html)
  2.2.2 Object Representation (node24.html)
  2.2.3 Attribute Management Functions (node25.html)
  2.2.4 Object Comparison (node26.html)
  2.2.5 Abstract Protocol Support (node27.html)
  2.2.6 More Suggestions (node28.html)
  3. Building C and C++ Extensions on Unix (building-on-unix.html)
  - 3.1 Building Custom Interpreters (custom-interps.html)
  3.2 Module Definition Options (module-defn-options.html)
  3.3 Example (module-defn-example.html)
  3.4 Distributing your extension modules (distributing.html)
  4. Building C and C++ Extensions on Windows (building-on-windows.html)
  - 4.1 A Cookbook Approach (win-cookbook.html)
  4.2 Differences Between Unix and Windows (dynamic-linking.html)
  4.3 Using DLLs in Practice (win-dlls.html)
  5. Embedding Python in Another Application (embedding.html)
  - 5.1 Very High Level Embedding (high-level-embedding.html)
  5.2 Beyond Very High Level Embedding: An overview (lower-level-embedding.html)
  5.3 Pure Embedding (pure-embedding.html)
  5.4 Extending Embedded Python (extending-with-embedding.html)
  5.5 Embedding Python in C++ (embeddingInCplusplus.html)
  5.6 Linking Requirements (link-reqs.html)
  A. Reporting Bugs (reporting-bugs.html)
  B. History and License (node46.html)
  - B.1 History of the software (node47.html)
  B.2 Terms and conditions for accessing or otherwise using Python (node48.html)
  About this document ... (about.html)
End of Table of Contents


1.11 Writing Extensions in C++

nullPointers.html | intro.html | using-cobjects.html | Extending and Embedding the Python Interpreter | contents.html
---
# 1.11 Writing Extensions in C++
It is possible to write extension modules in C++. Some restrictions
apply. If the main program (the Python interpreter) is compiled and
linked by the C compiler, global or static objects with constructors
cannot be used. This is not a problem if the main program is linked
by the C++ compiler. Functions that will be called by the
Python interpreter (in particular, module initalization functions)
have to be declared using `extern "C"`.
It is unnecessary to enclose the Python header files in
`extern "C" {...}` -- they use this form already if the symbol
"__cplusplus" is defined (all recent C++ compilers define this
symbol).


3.1 Building Custom Interpreters

building-on-unix.html | building-on-unix.html | module-defn-options.html | Extending and Embedding the Python Interpreter | contents.html
---
# 3.1 Building Custom Interpreters
The make file built by Makefile.pre.in can be run with the
"static" target to build an interpreter:
```text

make static
```
Any modules defined in the Setup file before the
"*shared*" line will be statically linked into the interpreter.
Typically, a "*shared*" line is omitted from the
Setup file when a custom interpreter is desired.


2. Defining New Types

using-cobjects.html | ext.html | dnt-basics.html | Extending and Embedding the Python Interpreter | contents.html
---
# 2. Defining New Types
As mentioned in the last chapter, Python allows the writer of an
extension module to define new types that can be manipulated from
Python code, much like strings and lists in core Python.
This is not hard; the code for all extension types follows a pattern,
but there are some details that you need to understand before you can
get started.


3.4 Distributing your extension modules

module-defn-example.html | building-on-unix.html | building-on-windows.html | Extending and Embedding the Python Interpreter | contents.html
---
# 3.4 Distributing your extension modules
There are two ways to distribute extension modules for others to use.
The way that allows the easiest cross-platform support is to use the
distutilspackage. The manual
Distributing Python Modules (../dist/dist.html) contains
information on this approach. It is recommended that all new
extensions be distributed using this approach to allow easy building
and installation across platforms. Older extensions should migrate to
this approach as well.
What follows describes the older approach; there are still many
extensions which use this.
When distributing your extension modules in source form, make sure to
include a Setup file. The Setup file should be named
Setup.in in the distribution. The make file make file,
Makefile.pre.in, will copy Setup.in to Setup if
the person installing the extension doesn't do so manually.
Distributing a Setup.in file makes it easy for people to
customize the Setup file while keeping the original in
Setup.in.
It is a good idea to include a copy of Makefile.pre.in for
people who do not have a source distribution of Python.


2.1 The Basics

defining-new-types.html | defining-new-types.html | dnt-type-methods.html | Extending and Embedding the Python Interpreter | contents.html
---
# 2.1 The Basics
The Python runtime sees all Python objects as variables of type
PyObject*. A PyObject is not a very magnificent
object - it just contains the refcount and a pointer to the object's
``type object''. This is where the action is; the type object
determines which (C) functions get called when, for instance, an
attribute gets looked up on an object or it is multiplied by another
object. I call these C functions ``type methods'' to distinguish them
from things like `[].append` (which I will call ``object
methods'' when I get around to them).
So, if you want to define a new object type, you need to create a new
type object.
This sort of thing can only be explained by example, so here's a
minimal, but complete, module that defines a new type:
```text

#include <Python.h>

staticforward PyTypeObject noddy_NoddyType;

typedef struct {
PyObject_HEAD
} noddy_NoddyObject;

static PyObject*
noddy_new_noddy(PyObject* self, PyObject* args)
{
noddy_NoddyObject* noddy;

if (!PyArg_ParseTuple(args,":new_noddy"))
return NULL;

noddy = PyObject_New(noddy_NoddyObject, &noddy_NoddyType);

return (PyObject*)noddy;
}

static void
noddy_noddy_dealloc(PyObject* self)
{
PyObject_Del(self);
}

static PyTypeObject noddy_NoddyType = {
PyObject_HEAD_INIT(NULL)
0,
"Noddy",
sizeof(noddy_NoddyObject),
0,
noddy_noddy_dealloc, /*tp_dealloc*/
0, /*tp_print*/
0, /*tp_getattr*/
0, /*tp_setattr*/
0, /*tp_compare*/
0, /*tp_repr*/
0, /*tp_as_number*/
0, /*tp_as_sequence*/
0, /*tp_as_mapping*/
0, /*tp_hash */
};

static PyMethodDef noddy_methods[] = {
{"new_noddy", noddy_new_noddy, METH_VARARGS,
"Create a new Noddy object."},
{NULL, NULL, 0, NULL}
};

DL_EXPORT(void)
initnoddy(void)
{
noddy_NoddyType.ob_type = &PyType_Type;

Py_InitModule("noddy", noddy_methods);
}
```
Now that's quite a bit to take in at once, but hopefully bits will
seem familiar from the last chapter.
The first bit that will be new is:
```text

staticforward PyTypeObject noddy_NoddyType;
```
This names the type object that will be defining further down in the
file. It can't be defined here because its definition has to refer to
functions that have no yet been defined, but we need to be able to
refer to it, hence the declaration.
The `staticforward` is required to placate various brain dead
compilers.
```text

typedef struct {
PyObject_HEAD
} noddy_NoddyObject;
```
This is what a Noddy object will contain. In this case nothing more
than every Python object contains - a refcount and a pointer to a type
object. These are the fields the `PyObject_HEAD` macro brings
in. The reason for the macro is to standardize the layout and to
enable special debugging fields to be brought in debug builds.
For contrast
```text

typedef struct {
PyObject_HEAD
long ob_ival;
} PyIntObject;
```
is the corresponding definition for standard Python integers.
Next up is:
```text

static PyObject*
noddy_new_noddy(PyObject* self, PyObject* args)
{
noddy_NoddyObject* noddy;

if (!PyArg_ParseTuple(args,":new_noddy"))
return NULL;

noddy = PyObject_New(noddy_NoddyObject, &noddy_NoddyType);

return (PyObject*)noddy;
}
```
This is in fact just a regular module function, as described in the
last chapter. The reason it gets special mention is that this is
where we create our Noddy object. Defining PyTypeObject structures is
all very well, but if there's no way to actually create one
of the wretched things it is not going to do anyone much good.
Almost always, you create objects with a call of the form:
```text

PyObject_New(<type>, &<type object>);
```
This allocates the memory and then initializes the object (sets
the reference count to one, makes the ob_type pointer point at
the right place and maybe some other stuff, depending on build options).
You can do these steps separately if you have some reason to
-- but at this level we don't bother.
We cast the return value to a PyObject* because that's what
the Python runtime expects. This is safe because of guarantees about
the layout of structures in the C standard, and is a fairly common C
programming trick. One could declare noddy_new_noddy to
return a noddy_NoddyObject* and then put a cast in the
definition of noddy_methods further down the file -- it
doesn't make much difference.
Now a Noddy object doesn't do very much and so doesn't need to
implement many type methods. One you can't avoid is handling
deallocation, so we find
```text

static void
noddy_noddy_dealloc(PyObject* self)
{
PyObject_Del(self);
}
```
This is so short as to be self explanatory. This function will be
called when the reference count on a Noddy object reaches `0` (or
it is found as part of an unreachable cycle by the cyclic garbage
collector). PyObject_Del() is what you call when you want
an object to go away. If a Noddy object held references to other
Python objects, one would decref them here.
Moving on, we come to the crunch -- the type object.
```text

static PyTypeObject noddy_NoddyType = {
PyObject_HEAD_INIT(NULL)
0,
"Noddy",
sizeof(noddy_NoddyObject),
0,
noddy_noddy_dealloc, /*tp_dealloc*/
0, /*tp_print*/
0, /*tp_getattr*/
0, /*tp_setattr*/
0, /*tp_compare*/
0, /*tp_repr*/
0, /*tp_as_number*/
0, /*tp_as_sequence*/
0, /*tp_as_mapping*/
0, /*tp_hash */
};
```
Now if you go and look up the definition of PyTypeObject in
object.h you'll see that it has many, many more fields that the
definition above. The remaining fields will be filled with zeros by
the C compiler, and it's common practice to not specify them
explicitly unless you need them.
This is so important that I'm going to pick the top of it apart still
further:
```text

PyObject_HEAD_INIT(NULL)
```
This line is a bit of a wart; what we'd like to write is:
```text

PyObject_HEAD_INIT(&PyType_Type)
```
as the type of a type object is ``type'', but this isn't strictly
conforming C and some compilers complain. So instead we fill in the
ob_type field of noddy_NoddyType at the earliest
oppourtunity -- in initnoddy().
```text

0,
```
XXX why does the type info struct start PyObject_*VAR*_HEAD??
```text

"Noddy",
```
The name of our type. This will appear in the default textual
representation of our objects and in some error messages, for example:
```text

>>> "" + noddy.new_noddy()
Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: cannot add type "Noddy" to string
```
```text

sizeof(noddy_NoddyObject),
```
This is so that Python knows how much memory to allocate when you call
PyObject_New.
```text

0,
```
This has to do with variable length objects like lists and strings.
Ignore for now...
Now we get into the type methods, the things that make your objects
different from the others. Of course, the Noddy object doesn't
implement many of these, but as mentioned above you have to implement
the deallocation function.
```text

noddy_noddy_dealloc, /*tp_dealloc*/
```
From here, all the type methods are nil so I won't go over them yet -
that's for the next section!
Everything else in the file should be familiar, except for this line
in initnoddy:
```text

noddy_NoddyType.ob_type = &PyType_Type;
```
This was alluded to above -- the noddy_NoddyType object should
have type ``type'', but `&PyType_Type` is not constant and so
can't be used in its initializer. To work around this, we patch it up
in the module initialization.
That's it! All that remains is to build it; put the above code in a
file called noddymodule.c and
```text

from distutils.core import setup, Extension
setup(name = "noddy", version = "1.0",
ext_modules = [Extension("noddy", ["noddymodule.c"])])
```
in a file called setup.py; then typing
```text

$ python setup.py build%$
```
at a shell should produce a file noddy.so in a subdirectory;
move to that directory and fire up Python -- you should be able to
`import noddy` and play around with Noddy objects.
That wasn't so hard, was it?


2.2 Type Methods

dnt-basics.html | defining-new-types.html | node23.html | Extending and Embedding the Python Interpreter | contents.html
---
# 2.2 Type Methods
This section aims to give a quick fly-by on the various type methods
you can implement and what they do.
Here is the definition of PyTypeObject, with some fields only
used in debug builds omitted:
```text

typedef struct _typeobject {
PyObject_VAR_HEAD
char *tp_name; /* For printing */
int tp_basicsize, tp_itemsize; /* For allocation */

/* Methods to implement standard operations */

destructor tp_dealloc;
printfunc tp_print;
getattrfunc tp_getattr;
setattrfunc tp_setattr;
cmpfunc tp_compare;
reprfunc tp_repr;

/* Method suites for standard classes */

PyNumberMethods *tp_as_number;
PySequenceMethods *tp_as_sequence;
PyMappingMethods *tp_as_mapping;

/* More standard operations (here for binary compatibility) */

hashfunc tp_hash;
ternaryfunc tp_call;
reprfunc tp_str;
getattrofunc tp_getattro;
setattrofunc tp_setattro;

/* Functions to access object as input/output buffer */
PyBufferProcs *tp_as_buffer;

/* Flags to define presence of optional/expanded features */
long tp_flags;

char *tp_doc; /* Documentation string */

/* Assigned meaning in release 2.0 */
/* call function for all accessible objects */
traverseproc tp_traverse;

/* delete references to contained objects */
inquiry tp_clear;

/* Assigned meaning in release 2.1 */
/* rich comparisons */
richcmpfunc tp_richcompare;

/* weak reference enabler */
long tp_weaklistoffset;

/* Added in release 2.2 */
/* Iterators */
getiterfunc tp_iter;
iternextfunc tp_iternext;

/* Attribute descriptor and subclassing stuff */
struct PyMethodDef *tp_methods;
struct memberlist *tp_members;
struct getsetlist *tp_getset;
struct _typeobject *tp_base;
PyObject *tp_dict;
descrgetfunc tp_descr_get;
descrsetfunc tp_descr_set;
long tp_dictoffset;
initproc tp_init;
allocfunc tp_alloc;
newfunc tp_new;
destructor tp_free; /* Low-level free-memory routine */
PyObject *tp_bases;
PyObject *tp_mro; /* method resolution order */
PyObject *tp_defined;

} PyTypeObject;
```
Now that's a lot of methods. Don't worry too much though - if
you have a type you want to define, the chances are very good that you
will only implement a handful of these.
As you probably expect by now, we're going to go over this and give
more information about the various handlers. We won't go in the order
they are defined in the structure, because there is a lot of
historical baggage that impacts the ordering of the fields; be sure
your type initializaion keeps the fields in the right order! It's
often easiest to find an example that includes all the fields you need
(even if they're initialized to `0`) and then change the values
to suit your new type.
```text

char *tp_name; /* For printing */
```
The name of the type - as mentioned in the last section, this will
appear in various places, almost entirely for diagnostic purposes.
Try to choose something that will be helpful in such a situation!
```text

int tp_basicsize, tp_itemsize; /* For allocation */
```
These fields tell the runtime how much memory to allocate when new
objects of this typed are created. Python has some builtin support
for variable length structures (think: strings, lists) which is where
the tp_itemsize field comes in. This will be dealt with
later.
```text

char *tp_doc;
```
Here you can put a string (or its address) that you want returned when
the Python script references `obj.__doc__` to retrieve the
docstring.
Now we come to the basic type methods--the ones most extension types
will implement.


win-cookbook.html | building-on-windows.html | win-dlls.html | Extending and Embedding the Python Interpreter | contents.html
---
# 4.2 Differences Between Unix and Windows
Unix and Windows use completely different paradigms for run-time
loading of code. Before you try to build a module that can be
dynamically loaded, be aware of how your system works.
In Unix, a shared object (.so) file contains code to be used by the
program, and also the names of functions and data that it expects to
find in the program. When the file is joined to the program, all
references to those functions and data in the file's code are changed
to point to the actual locations in the program where the functions
and data are placed in memory. This is basically a link operation.
In Windows, a dynamic-link library (.dll) file has no dangling
references. Instead, an access to functions or data goes through a
lookup table. So the DLL code does not have to be fixed up at runtime
to refer to the program's memory; instead, the code already uses the
DLL's lookup table, and the lookup table is modified at runtime to
point to the functions and data.
In Unix, there is only one type of library file (.a) which
contains code from several object files (.o). During the link
step to create a shared object file (.so), the linker may find
that it doesn't know where an identifier is defined. The linker will
look for it in the object files in the libraries; if it finds it, it
will include all the code from that object file.
In Windows, there are two types of library, a static library and an
import library (both called .lib). A static library is like a
Unix .a file; it contains code to be included as necessary.
An import library is basically used only to reassure the linker that a
certain identifier is legal, and will be present in the program when
the DLL is loaded. So the linker uses the information from the
import library to build the lookup table for using identifiers that
are not included in the DLL. When an application or a DLL is linked,
an import library may be generated, which will need to be used for all
future DLLs that depend on the symbols in the application or DLL.
Suppose you are building two dynamic-load modules, B and C, which should
share another block of code A. On Unix, you would not pass
A.a to the linker for B.so and C.so; that would
cause it to be included twice, so that B and C would each have their
own copy. In Windows, building A.dll will also build
A.lib. You do pass A.lib to the linker for B and
C. A.lib does not contain code; it just contains information
which will be used at runtime to access A's code.
In Windows, using an import library is sort of like using "import
spam"; it gives you access to spam's names, but does not create a
separate copy. On Unix, linking with a library is more like
"from spam import *"; it does create a separate copy.


win-dlls.html | ext.html | high-level-embedding.html | Extending and Embedding the Python Interpreter | contents.html
---
# 5. Embedding Python in Another Application
The previous chapters discussed how to extend Python, that is, how to
extend the functionality of Python by attaching a library of C
functions to it. It is also possible to do it the other way around:
enrich your C/C++ application by embedding Python in it. Embedding
provides your application with the ability to implement some of the
functionality of your application in Python rather than C or C++.
This can be used for many purposes; one example would be to allow
users to tailor the application to their needs by writing some scripts
in Python. You can also use it yourself if some of the functionality
can be written in Python more easily.
Embedding Python is similar to extending it, but not quite. The
difference is that when you extend Python, the main program of the
application is still the Python interpreter, while if you embed
Python, the main program may have nothing to do with Python --
instead, some parts of the application occasionally call the Python
interpreter to run some Python code.
So if you are embedding Python, you are providing your own main
program. One of the things this main program has to do is initialize
the Python interpreter. At the very least, you have to call the
function Py_Initialize() (on Mac OS, call
PyMac_Initialize() instead). There are optional calls to
pass command line arguments to Python. Then later you can call the
interpreter from any part of the application.
There are several different ways to call the interpreter: you can pass
a string containing Python statements to
PyRun_SimpleString(), or you can pass a stdio file pointer
and a file name (for identification in error messages only) to
PyRun_SimpleFile(). You can also call the lower-level
operations described in the previous chapters to construct and use
Python objects.
A simple demo of embedding Python can be found in the directory
Demo/embed/ of the source distribution.
See Also:


5.5 Embedding Python in C++

extending-with-embedding.html | embedding.html | link-reqs.html | Extending and Embedding the Python Interpreter | contents.html
---
# 5.5 Embedding Python in C++
It is also possible to embed Python in a C++ program; precisely how this
is done will depend on the details of the C++ system used; in general you
will need to write the main program in C++, and use the C++ compiler
to compile and link your program. There is no need to recompile Python
itself using C++.


1.2 Intermezzo: Errors and Exceptions

simpleExample.html | intro.html | backToExample.html | Extending and Embedding the Python Interpreter | contents.html
---
# 1.2 Intermezzo: Errors and Exceptions
An important convention throughout the Python interpreter is the
following: when a function fails, it should set an exception condition
and return an error value (usually a NULL pointer). Exceptions
are stored in a static global variable inside the interpreter; if this
variable is NULL no exception has occurred. A second global
variable stores the ``associated value'' of the exception (the second
argument to raise). A third variable contains the stack
traceback in case the error originated in Python code. These three
variables are the C equivalents of the Python variables
`sys.exc_type`, `sys.exc_value` and `sys.exc_traceback` (see
the section on module sys in the
Python Library Reference (../lib/lib.html)). It is
important to know about them to understand how errors are passed
around.
The Python API defines a number of functions to set various types of
exceptions.
The most common one is PyErr_SetString(). Its arguments
are an exception object and a C string. The exception object is
usually a predefined object like PyExc_ZeroDivisionError. The
C string indicates the cause of the error and is converted to a
Python string object and stored as the ``associated value'' of the
exception.
Another useful function is PyErr_SetFromErrno(), which only
takes an exception argument and constructs the associated value by
inspection of the global variable errno. The most
general function is PyErr_SetObject(), which takes two object
arguments, the exception and its associated value. You don't need to
Py_INCREF() the objects passed to any of these functions.
You can test non-destructively whether an exception has been set with
PyErr_Occurred(). This returns the current exception object,
or NULL if no exception has occurred. You normally don't need
to call PyErr_Occurred() to see whether an error occurred in a
function call, since you should be able to tell from the return value.
When a function f that calls another function g detects
that the latter fails, f should itself return an error value
(usually NULL or `-1`). It should not call one of the
PyErr_*() functions -- one has already been called by g.
f's caller is then supposed to also return an error indication
to its caller, again without calling PyErr_*(),
and so on -- the most detailed cause of the error was already
reported by the function that first detected it. Once the error
reaches the Python interpreter's main loop, this aborts the currently
executing Python code and tries to find an exception handler specified
by the Python programmer.
(There are situations where a module can actually give a more detailed
error message by calling another PyErr_*() function, and in
such cases it is fine to do so. As a general rule, however, this is
not necessary, and can cause information about the cause of the error
to be lost: most operations can fail for a variety of reasons.)
To ignore an exception set by a function call that failed, the exception
condition must be cleared explicitly by calling PyErr_Clear().
The only time C code should call PyErr_Clear() is if it doesn't
want to pass the error on to the interpreter but wants to handle it
completely by itself (possibly by trying something else, or pretending
nothing went wrong).
Every failing malloc() call must be turned into an
exception -- the direct caller of malloc() (or
realloc()) must call PyErr_NoMemory() and
return a failure indicator itself. All the object-creating functions
(for example, PyInt_FromLong()) already do this, so this
note is only relevant to those who call malloc() directly.
Also note that, with the important exception of
PyArg_ParseTuple() and friends, functions that return an
integer status usually return a positive value or zero for success and
`-1` for failure, like Unix system calls.
Finally, be careful to clean up garbage (by making
Py_XDECREF() or Py_DECREF() calls for objects
you have already created) when you return an error indicator!
The choice of which exception to raise is entirely yours. There are
predeclared C objects corresponding to all built-in Python exceptions,
such as PyExc_ZeroDivisionError, which you can use directly.
Of course, you should choose exceptions wisely -- don't use
PyExc_TypeError to mean that a file couldn't be opened (that
should probably be PyExc_IOError). If something's wrong with
the argument list, the PyArg_ParseTuple() function usually
raises PyExc_TypeError. If you have an argument whose value
must be in a particular range or must satisfy other conditions,
PyExc_ValueError is appropriate.
You can also define a new exception that is unique to your module.
For this, you usually declare a static object variable at the
beginning of your file:
```text

static PyObject *SpamError;
```
and initialize it in your module's initialization function
(initspam()) with an exception object (leaving out
the error checking for now):
```text

void
initspam(void)
{
PyObject *m, *d;

m = Py_InitModule("spam", SpamMethods);
d = PyModule_GetDict(m);
SpamError = PyErr_NewException("spam.error", NULL, NULL);
PyDict_SetItemString(d, "error", SpamError);
}
```
Note that the Python name for the exception object is
spam.error. The PyErr_NewException() function
may create a class with the base class being Exception
(unless another class is passed in instead of NULL), described in the
Python Library Reference (../lib/lib.html) under ``Built-in
Exceptions.''
Note also that the SpamError variable retains a reference to
the newly created exception class; this is intentional! Since the
exception could be removed from the module by external code, an owned
reference to the class is needed to ensure that it will not be
discarded, causing SpamError to become a dangling pointer.
Should it become a dangling pointer, C code which raises the exception
could cause a core dump or other unintended side effects.


../index.html | front.html | Extending and Embedding the Python Interpreter | contents.html
---
# Extending and Embedding the Python Interpreter
Guido van Rossum
Fred L. Drake, Jr., editor
PythonLabs
Email: python-docs@python.org
Release 2.2
December 21, 2001


5.4 Extending Embedded Python

pure-embedding.html | embedding.html | embeddingInCplusplus.html | Extending and Embedding the Python Interpreter | contents.html
---
# 5.4 Extending Embedded Python
Until now, the embedded Python interpreter had no access to
functionality from the application itself. The Python API allows this
by extending the embedded interpreter. That is, the embedded
interpreter gets extended with routines provided by the application.
While it sounds complex, it is not so bad. Simply forget for a while
that the application starts the Python interpreter. Instead, consider
the application to be a set of subroutines, and write some glue code
that gives Python access to those routines, just like you would write
a normal Python extension. For example:
```text

static int numargs=0;

/* Return the number of arguments of the application command line */
static PyObject*
emb_numargs(PyObject *self, PyObject *args)
{
if(!PyArg_ParseTuple(args, ":numargs"))
return NULL;
return Py_BuildValue("i", numargs);
}

static PyMethodDef EmbMethods[] = {
{"numargs", emb_numargs, METH_VARARGS,
"Return the number of arguments received by the process."},
{NULL, NULL, 0, NULL}
};
```
Insert the above code just above the main() function.
Also, insert the following two statements directly after
Py_Initialize():
```text

numargs = argc;
Py_InitModule("emb", EmbMethods);
```
These two lines initialize the `numargs` variable, and make the
emb.numargs() function accessible to the embedded Python
interpreter. With these extensions, the Python script can do things
like
```text

import emb
print "Number of arguments", emb.numargs()
```
In a real application, the methods will expose an API of the
application to Python.


Front Matter

ext.html | ext.html | contents.html | Extending and Embedding the Python Interpreter | contents.html
---
# Front Matter
Copyright © 2001 Python Software Foundation.
All rights reserved.
Copyright © 2000 BeOpen.com.
All rights reserved.
Copyright © 1995-2000 Corporation for National Research Initiatives.
All rights reserved.
Copyright © 1991-1995 Stichting Mathematisch Centrum.
All rights reserved.
See the end of this document for complete license and permissions
information.
### Abstract:
Python is an interpreted, object-oriented programming language. This
document describes how to write modules in C or C++ to extend the
Python interpreter with new modules. Those modules can define new
functions but also new object types and their methods. The document
also describes how to embed the Python interpreter in another
application, for use as an extension language. Finally, it shows how
to compile and link extension modules so that they can be loaded
dynamically (at run time) into the interpreter, if the underlying
operating system supports this feature.
This document assumes basic knowledge about Python. For an informal
introduction to the language, see the
Python Tutorial (../tut/tut.html). The
Python Reference Manual (../ref/ref.html) gives a more
formal definition of the language. The
Python Library Reference (../lib/lib.html) documents the
existing object types, functions and modules (both built-in and
written in Python) that give the language its wide application range.
For a detailed description of the whole Python/C API, see the separate
Python/C API Reference Manual (../api/api.html).


5.1 Very High Level Embedding

embedding.html | embedding.html | lower-level-embedding.html | Extending and Embedding the Python Interpreter | contents.html
---
# 5.1 Very High Level Embedding
The simplest form of embedding Python is the use of the very
high level interface. This interface is intended to execute a
Python script without needing to interact with the application
directly. This can for example be used to perform some operation
on a file.
```text

#include <Python.h>

int
main(int argc, char *argv[])
{
Py_Initialize();
PyRun_SimpleString("from time import time,ctime\n"
"print 'Today is',ctime(time())\n");
Py_Finalize();
return 0;
}
```
The above code first initializes the Python interpreter with
Py_Initialize(), followed by the execution of a hard-coded
Python script that print the date and time. Afterwards, the
Py_Finalize() call shuts the interpreter down, followed by
the end of the program. In a real program, you may want to get the
Python script from another source, perhaps a text-editor routine, a
file, or a database. Getting the Python code from a file can better
be done by using the PyRun_SimpleFile() function, which
saves you the trouble of allocating memory space and loading the file
contents.


1. Extending Python with C or C++

contents.html | ext.html | simpleExample.html | Extending and Embedding the Python Interpreter | contents.html
---
# 1. Extending Python with C or C++
It is quite easy to add new built-in modules to Python, if you know
how to program in C. Such extension modules can do two things
that can't be done directly in Python: they can implement new built-in
object types, and they can call C library functions and system calls.
To support extensions, the Python API (Application Programmers
Interface) defines a set of functions, macros and variables that
provide access to most aspects of the Python run-time system. The
Python API is incorporated in a C source file by including the header
`"Python.h"`.
The compilation of an extension module depends on its intended use as
well as on your system setup; details are given in later chapters.


5.6 Linking Requirements

embeddingInCplusplus.html | embedding.html | reporting-bugs.html | Extending and Embedding the Python Interpreter | contents.html
---
# 5.6 Linking Requirements
While the configure script shipped with the Python sources
will correctly build Python to export the symbols needed by
dynamically linked extensions, this is not automatically inherited by
applications which embed the Python library statically, at least on
Unix. This is an issue when the application is linked to the static
runtime library (libpython.a) and needs to load dynamic
extensions (implemented as .so files).
The problem is that some entry points are defined by the Python
runtime solely for extension modules to use. If the embedding
application does not use any of these entry points, some linkers will
not include those entries in the symbol table of the finished
executable. Some additional options are needed to inform the linker
not to remove these symbols.
Determining the right options to use for any given platform can be
quite difficult, but fortunately the Python configuration already has
those values. To retrieve them from an installed Python interpreter,
start an interactive interpreter and have a short session like this:
```text

>>> import distutils.sysconfig
>>> distutils.sysconfig.get_config_var('LINKFORSHARED')
'-Xlinker -export-dynamic'
```
The contents of the string presented will be the options that should
be used. If the string is empty, there's no need to add any
additional options. The LINKFORSHARED definition
corresponds to the variable of the same name in Python's top-level
Makefile.


high-level-embedding.html | embedding.html | pure-embedding.html | Extending and Embedding the Python Interpreter | contents.html
---
# 5.2 Beyond Very High Level Embedding: An overview
The high level interface gives you the ability to execute
arbitrary pieces of Python code from your application, but
exchanging data values is quite cumbersome to say the least. If
you want that, you should use lower level calls. At the cost of
having to write more C code, you can achieve almost anything.
It should be noted that extending Python and embedding Python
is quite the same activity, despite the different intent. Most
topics discussed in the previous chapters are still valid. To
show this, consider what the extension code from Python to C
really does:
1. Convert data values from Python to C,
2. Perform a function call to a C routine using the
converted values, and
3. Convert the data values from the call from C to Python.
When embedding Python, the interface code does:
1. Convert data values from C to Python,
2. Perform a function call to a Python interface routine
using the converted values, and
3. Convert the data values from the call from Python to C.
As you can see, the data conversion steps are simply swapped to
accomodate the different direction of the cross-language transfer.
The only difference is the routine that you call between both
data conversions. When extending, you call a C routine, when
embedding, you call a Python routine.
This chapter will not discuss how to convert data from Python
to C and vice versa. Also, proper use of references and dealing
with errors is assumed to be understood. Since these aspects do not
differ from extending the interpreter, you can refer to earlier
chapters for the required information.


backToExample.html | intro.html | compilation.html | Extending and Embedding the Python Interpreter | contents.html
---
# 1.4 The Module's Method Table and Initialization Function
I promised to show how spam_system() is called from Python
programs. First, we need to list its name and address in a ``method
table'':
```text

static PyMethodDef SpamMethods[] = {
...
{"system", spam_system, METH_VARARGS,
"Execute a shell command."},
...
{NULL, NULL, 0, NULL} /* Sentinel */
};
```
Note the third entry ("METH_VARARGS"). This is a flag telling
the interpreter the calling convention to be used for the C
function. It should normally always be "METH_VARARGS" or
"METH_VARARGS | METH_KEYWORDS"; a value of `0` means that an
obsolete variant of PyArg_ParseTuple() is used.
When using only "METH_VARARGS", the function should expect
the Python-level parameters to be passed in as a tuple acceptable for
parsing via PyArg_ParseTuple(); more information on this
function is provided below.
The METH_KEYWORDS bit may be set in the third field if
keyword arguments should be passed to the function. In this case, the
C function should accept a third "PyObject *" parameter which
will be a dictionary of keywords. Use
PyArg_ParseTupleAndKeywords() to parse the arguments to
such a function.
The method table must be passed to the interpreter in the module's
initialization function. The initialization function must be named
initname(), where name is the name of the
module, and should be the only non-static item defined in
the module file:
```text

void
initspam(void)
{
(void) Py_InitModule("spam", SpamMethods);
}
```
Note that for C++, this method must be declared `extern "C"`.
When the Python program imports module spam for the first
time, initspam() is called. (See below for comments about
embedding Python.) It calls
Py_InitModule(), which creates a ``module object'' (which
is inserted in the dictionary `sys.modules` under the key
`"spam"`), and inserts built-in function objects into the newly
created module based upon the table (an array of PyMethodDef
structures) that was passed as its second argument.
Py_InitModule() returns a pointer to the module object
that it creates (which is unused here). It aborts with a fatal error
if the module could not be initialized satisfactorily, so the caller
doesn't need to check for errors.
When embedding Python, the initspam() function is not
called automatically unless there's an entry in the
_PyImport_Inittab table. The easiest way to handle this is to
statically initialize your statically-linked modules by directly
calling initspam() after the call to
Py_Initialize() or PyMac_Initialize():
```text

int main(int argc, char **argv)
{
/* Pass argv[0] to the Python interpreter */
Py_SetProgramName(argv[0]);

/* Initialize the Python interpreter. Required. */
Py_Initialize();

/* Add a static module */
initspam();
```
An example may be found in the file Demo/embed/demo.c in the
Python source distribution.
Note:
Removing entries from `sys.modules` or importing
compiled modules into multiple interpreters within a process (or
following a fork() without an intervening
exec()) can create problems for some extension modules.
Extension module authors should exercise caution when initializing
internal data structures.
Note also that the reload() function can be used with
extension modules, and will call the module initialization function
(initspam() in the example), but will not load the module
again if it was loaded from a dynamically loadable object file
(.so on Unix, .dll on Windows).
A more substantial example module is included in the Python source
distribution as Modules/xxmodule.c. This file may be used as a
template or simply read as an example. The modulator.py
script included in the source distribution or Windows install provides
a simple graphical user interface for declaring the functions and
objects which a module should implement, and can generate a template
which can be filled in. The script lives in the
Tools/modulator/ directory; see the README file there
for more information.


3.3 Example

module-defn-options.html | building-on-unix.html | distributing.html | Extending and Embedding the Python Interpreter | contents.html
---
# 3.3 Example
Here is a more complicated example from Modules/Setup.dist:
```text

GMP=/ufs/guido/src/gmp
mpz mpzmodule.c -I$(GMP) $(GMP)/libgmp.a
```
which could also be written as:
```text

mpz mpzmodule.c -I$(GMP) -L$(GMP) -lgmp
```


3.2 Module Definition Options

custom-interps.html | building-on-unix.html | module-defn-example.html | Extending and Embedding the Python Interpreter | contents.html
---
# 3.2 Module Definition Options
Several compiler options are supported:
Other compiler options can be included (snuck in) by putting them
in variables.
Source files can include files with .c, .C, .cc,
.cpp, .cxx, and .c++ extensions.
Other input files include files with .a, .o, .sl,
and .so extensions.


2.2.1 Finalization and De-allocation

dnt-type-methods.html | dnt-type-methods.html | node24.html | Extending and Embedding the Python Interpreter | contents.html
---
## 2.2.1 Finalization and De-allocation
```text

destructor tp_dealloc;
```
This function is called when the reference count of the instance of
your type is reduced to zero and the Python interpreter wants to
reclaim it. If your type has memory to free or other clean-up to
perform, put it here. The object itself needs to be freed here as
well. Here is an example of this function:
```text

static void
newdatatype_dealloc(newdatatypeobject * obj)
{
free(obj->obj_UnderlyingDatatypePtr);
PyObject_DEL(obj);
}
```
One important requirement of the deallocator function is that it
leaves any pending exceptions alone. This is important since
deallocators are frequently called as the interpreter unwinds the
Python stack; when the stack is unwound due to an exception (rather
than normal returns), nothing is done to protect the deallocators from
seeing that an exception has already been set. Any actions which a
deallocator performs which may cause additional Python code to be
executed may detect that an exception has been set. This can lead to
misleading errors from the interpreter. The proper way to protect
against this is to save a pending exception before performing the
unsafe action, and restoring it when done. This can be done using the
PyErr_Fetch()and
PyErr_Restore()functions:
```text

static void
my_dealloc(PyObject *obj)
{
MyObject *self = (MyObject *) obj;
PyObject *cbresult;

if (self->my_callback != NULL) {
PyObject *err_type, *err_value, *err_traceback;
int have_error = PyErr_Occurred() ? 1 : 0;

if (have_error)
PyErr_Fetch(&err_type, &err_value, &err_traceback);

cbresult = PyObject_CallObject(self->my_callback, NULL);
if (cbresult == NULL)
PyErr_WriteUnraisable();
else
Py_DECREF(cbresult);

if (have_error)
PyErr_Restore(err_type, err_value, err_traceback);

Py_DECREF(self->my_callback);
}
PyObject_DEL(obj);
}
```


2.2.2 Object Representation

node23.html | dnt-type-methods.html | node25.html | Extending and Embedding the Python Interpreter | contents.html
---
## 2.2.2 Object Representation
In Python, there are three ways to generate a textual representation
of an object: the repr()function (or
equivalent backtick syntax), the str()function, and the print statement. For most objects, the
print statement is equivalent to the str()
function, but it is possible to special-case printing to a
FILE* if necessary; this should only be done if efficiency is
identified as a problem and profiling suggests that creating a
temporary string object to be written to a file is too expensive.
These handlers are all optional, and most types at most need to
implement the tp_str and tp_repr handlers.
```text

reprfunc tp_repr;
reprfunc tp_str;
printfunc tp_print;
```
The tp_repr handler should return a string object containing
a representation of the instance for which it is called. Here is a
simple example:
```text

static PyObject *
newdatatype_repr(newdatatypeobject * obj)
{
return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",
obj->obj_UnderlyingDatatypePtr->size);
}
```
If no tp_repr handler is specified, the interpreter will
supply a representation that uses the type's tp_name and a
uniquely-identifying value for the object.
The tp_str handler is to str() what the
tp_repr handler described above is to repr(); that
is, it is called when Python code calls str() on an
instance of your object. It's implementation is very similar to the
tp_repr function, but the resulting string is intended for
human consumption. It tp_str is not specified, the
tp_repr handler is used instead.
Here is a simple example:
```text

static PyObject *
newdatatype_str(newdatatypeobject * obj)
{
return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
obj->obj_UnderlyingDatatypePtr->size
);
}
```
The print function will be called whenever Python needs to "print" an
instance of the type. For example, if 'node' is an instance of type
TreeNode, then the print function is called when Python code calls:
```text

print node
```
There is a flags argument and one flag, Py_PRINT_RAW, and
it suggests that you print without string quotes and possibly without
interpreting escape sequences.
The print function receives a file object as an argument. You will
likely want to write to that file object.
Here is a sampe print function:
```text

static int
newdatatype_print(newdatatypeobject *obj, FILE *fp, int flags)
{
if (flags & Py_PRINT_RAW) {
fprintf(fp, "<{newdatatype object--size: %d}>",
obj->obj_UnderlyingDatatypePtr->size);
}
else {
fprintf(fp, "\"<{newdatatype object--size: %d}>\"",
obj->obj_UnderlyingDatatypePtr->size);
}
return 0;
}
```


2.2.3 Attribute Management Functions

node24.html | dnt-type-methods.html | node26.html | Extending and Embedding the Python Interpreter | contents.html
---
## 2.2.3 Attribute Management Functions
```text

getattrfunc tp_getattr;
setattrfunc tp_setattr;
```
The tp_getattr handle is called when the object requires an
attribute look-up. It is called in the same situations where the
__getattr__() method of a class would be called.
A likely way to handle this is (1) to implement a set of functions
(such as newdatatype_getSize() and
newdatatype_setSize() in the example below), (2) provide a
method table listing these functions, and (3) provide a getattr
function that returns the result of a lookup in that table.
Here is an example:
```text

static PyMethodDef newdatatype_methods[] = {
{"getSize", (PyCFunction)newdatatype_getSize, METH_VARARGS,
"Return the current size."},
{"setSize", (PyCFunction)newdatatype_setSize, METH_VARARGS,
"Set the size."},
{NULL, NULL, 0, NULL} /* sentinel */
};

static PyObject *
newdatatype_getattr(newdatatypeobject *obj, char *name)
{
return Py_FindMethod(newdatatype_methods, (PyObject *)obj, name);
}
```
The tp_setattr handler is called when the
__setattr__() or __delattr__() method of a class
instance would be called. When an attribute should be deleted, the
third parameter will be NULL. Here is an example that simply raises
an exception; if this were really all you wanted, the
tp_setattr handler should be set to NULL.
```text

static int
newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
{
(void)PyErr_Format(PyExc_RuntimeError, "Read-only attribute: \%s", name);
return -1;
}
```


2.2.4 Object Comparison

node25.html | dnt-type-methods.html | node27.html | Extending and Embedding the Python Interpreter | contents.html
---
## 2.2.4 Object Comparison
```text

cmpfunc tp_compare;
```
The tp_compare handler is called when comparisons are needed
are the object does not implement the specific rich comparison method
which matches the requested comparison. (It is always used if defined
and the PyObject_Compare() or PyObject_Cmp()
functions are used, or if cmp() is used from Python.)
It is analogous to the __cmp__() method. This function
should return `-1` if obj1 is less than
obj2, `0` if they are equal, and `1` if
obj1 is greater than
obj2.
(It was previously allowed to return arbitrary negative or positive
integers for less than and greater than, respectively; as of Python
2.2, this is no longer allowed. In the future, other return values
may be assigned a different meaning.)
A tp_compare handler may raise an exception. In this case it
should return a negative value. The caller has to test for the
exception using PyErr_Occurred().
Here is a sample implementation:
```text

static int
newdatatype_compare(newdatatypeobject * obj1, newdatatypeobject * obj2)
{
long result;

if (obj1->obj_UnderlyingDatatypePtr->size <
obj2->obj_UnderlyingDatatypePtr->size) {
result = -1;
}
else if (obj1->obj_UnderlyingDatatypePtr->size >
obj2->obj_UnderlyingDatatypePtr->size) {
result = 1;
}
else {
result = 0;
}
return result;
}
```


2.2.5 Abstract Protocol Support

node26.html | dnt-type-methods.html | node28.html | Extending and Embedding the Python Interpreter | contents.html
---
## 2.2.5 Abstract Protocol Support
```text

tp_as_number;
tp_as_sequence;
tp_as_mapping;
```
If you wish your object to be able to act like a number, a sequence,
or a mapping object, then you place the address of a structure that
implements the C type PyNumberMethods,
PySequenceMethods, or PyMappingMethods, respectively.
It is up to you to fill in this structure with appropriate values. You
can find examples of the use of each of these in the Objects
directory of the Python source distribution.
```text

hashfunc tp_hash;
```
This function, if you choose to provide it, should return a hash
number for an instance of your datatype. Here is a moderately
pointless example:
```text

static long
newdatatype_hash(newdatatypeobject *obj)
{
long result;
result = obj->obj_UnderlyingDatatypePtr->size;
result = result * 3;
return result;
}
```
```text

ternaryfunc tp_call;
```
This function is called when an instance of your datatype is "called",
for example, if `obj1` is an instance of your datatype and the Python
script contains `obj1('hello')`, the tp_call handler is
invoked.
This function takes three arguments:
1. arg1 is the instance of the datatype which is the subject of
the call. If the call is `obj1('hello')`, then arg1 is
`obj1`.
2. arg2 is a tuple containing the arguments to the call. You
can use PyArg_ParseTuple() to extract the arguments.
3. arg3 is a dictionary of keyword arguments that were passed.
If this is non-NULL and you support keyword arguments, use
PyArg_ParseTupleAndKeywords() to extract the
arguments. If you do not want to support keyword arguments and
this is non-NULL, raise a TypeError with a message
saying that keyword arguments are not supported.
Here is a desultory example of the implementation of call function.
```text

/* Implement the call function.
* obj1 is the instance receiving the call.
* obj2 is a tuple containing the arguments to the call, in this
* case 3 strings.
*/
static PyObject *
newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *other)
{
PyObject *result;
char *arg1;
char *arg2;
char *arg3;

if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
return NULL;
}
result = PyString_FromFormat(
"Returning -- value: [\%d] arg1: [\%s] arg2: [\%s] arg3: [\%s]\n",
obj->obj_UnderlyingDatatypePtr->size,
arg1, arg2, arg3);
printf("\%s", PyString_AS_STRING(result));
return result;
}
```


2.2.6 More Suggestions

node27.html | dnt-type-methods.html | building-on-unix.html | Extending and Embedding the Python Interpreter | contents.html
---
## 2.2.6 More Suggestions
Remember that you can omit most of these functions, in which case you
provide `0` as a value.
In the Objects directory of the Python source distribution,
there is a file xxobject.c, which is intended to be used as a
template for the implementation of new types. One useful strategy
for implementing a new type is to copy and rename this file, then
read the instructions at the top of it.
There are type definitions for each of the functions you must
provide. They are in object.h in the Python include
directory that comes with the source distribution of Python.
In order to learn how to implement any specific method for your new
datatype, do the following: Download and unpack the Python source
distribution. Go the the Objects directory, then search the
C source files for `tp_` plus the function you want (for
example, `tp_print` or `tp_compare`). You will find
examples of the function you want to implement.
When you need to verify that the type of an object is indeed the
object you are implementing and if you use xxobject.c as an starting
template for your implementation, then there is a macro defined for
this purpose. The macro definition will look something like this:
```text

#define is_newdatatypeobject(v) ((v)->ob_type == &Newdatatypetype)
```
And, a sample of its use might be something like the following:


B. History and License

reporting-bugs.html | ext.html | node47.html | Extending and Embedding the Python Interpreter | contents.html
---
# B. History and License


B.1 History of the software

node46.html | node46.html | node48.html | Extending and Embedding the Python Interpreter | contents.html
---
# B.1 History of the software
Python was created in the early 1990s by Guido van Rossum at Stichting
Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands
as a successor of a language called ABC. Guido remains Python's
principal author, although it includes many contributions from others.
In 1995, Guido continued his work on Python at the Corporation for
National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/)
in Reston, Virginia where he released several versions of the
software.
In May 2000, Guido and the Python core development team moved to
BeOpen.com to form the BeOpen PythonLabs team. In October of the same
year, the PythonLabs team moved to Zope Corporation (then Digital
Creations; see http://www.zope.com/). In 2001, the Python
Software Foundation (PSF, see http://www.python.org/psf/) was
formed, a non-profit organization created specifically to own
Python-related Intellectual Property. Digital Creations is a
sponsoring member of the PSF.
All Python releases are Open Source (see
http://www.opensource.org/ for the Open Source Definition).
Historically, most, but not all, Python releases have also been
GPL-compatible; the table below summarizes the various releases.
Note:
GPL-compatible doesn't mean that we're distributing
Python under the GPL. All Python licenses, unlike the GPL, let you
distribute a modified version without making your changes open source.
The GPL-compatible licenses make it possible to combine Python with
other software that is released under the GPL; the others don't.
Thanks to the many outside volunteers who have worked under Guido's
direction to make these releases possible.


node47.html | node46.html | about.html | Extending and Embedding the Python Interpreter | contents.html
---
# B.2 Terms and conditions for accessing or otherwise using Python
PSF LICENSE AGREEMENT FOR PYTHON 2.2
1. This LICENSE AGREEMENT is between the Python Software Foundation
(``PSF''), and the Individual or Organization (``Licensee'') accessing
and otherwise using Python 2.2 software in source or binary
form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, PSF
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Python
2.2 alone or in any derivative version, provided, however, that
PSF's License Agreement and PSF's notice of copyright, i.e.,
``Copyright © 2001 Python Software Foundation; All Rights
Reserved'' are retained in Python 2.2 alone or in any
derivative version prepared by Licensee.
3. In the event Licensee prepares a derivative work that is based on
or incorporates Python 2.2 or any part thereof, and wants to
make the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Python 2.2.
4. PSF is making Python 2.2 available to Licensee on an ``AS IS''
basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.2 WILL
NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
2.2 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR
LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
2.2, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE
POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
7. Nothing in this License Agreement shall be deemed to create any
relationship of agency, partnership, or joint venture between PSF and
Licensee. This License Agreement does not grant permission to use PSF
trademarks or trade name in a trademark sense to endorse or promote
products or services of Licensee, or any third party.
8. By copying, installing or otherwise using Python 2.2, Licensee
agrees to be bound by the terms and conditions of this License
Agreement.
BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0
BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1
1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an
office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the
Individual or Organization (``Licensee'') accessing and otherwise
using this software in source or binary form and its associated
documentation (``the Software'').
2. Subject to the terms and conditions of this BeOpen Python License
Agreement, BeOpen hereby grants Licensee a non-exclusive,
royalty-free, world-wide license to reproduce, analyze, test, perform
and/or display publicly, prepare derivative works, distribute, and
otherwise use the Software alone or in any derivative version,
provided, however, that the BeOpen Python License is retained in the
Software, alone or in any derivative version prepared by Licensee.
3. BeOpen is making the Software available to Licensee on an ``AS IS''
basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT
INFRINGE ANY THIRD PARTY RIGHTS.
4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE
SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY
DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
5. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
6. This License Agreement shall be governed by and interpreted in all
respects by the law of the State of California, excluding conflict of
law provisions. Nothing in this License Agreement shall be deemed to
create any relationship of agency, partnership, or joint venture
between BeOpen and Licensee. This License Agreement does not grant
permission to use BeOpen trademarks or trade names in a trademark
sense to endorse or promote products or services of Licensee, or any
third party. As an exception, the ``BeOpen Python'' logos available
at http://www.pythonlabs.com/logos.html may be used according to the
permissions granted on that web page.
7. By copying, installing or otherwise using the software, Licensee
agrees to be bound by the terms and conditions of this License
Agreement.
CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1
1. This LICENSE AGREEMENT is between the Corporation for National
Research Initiatives, having an office at 1895 Preston White Drive,
Reston, VA 20191 (``CNRI''), and the Individual or Organization
(``Licensee'') accessing and otherwise using Python 1.6.1 software in
source or binary form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, CNRI
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Python 1.6.1
alone or in any derivative version, provided, however, that CNRI's
License Agreement and CNRI's notice of copyright, i.e., ``Copyright
© 1995-2001 Corporation for National Research Initiatives;
All Rights Reserved'' are retained in Python 1.6.1 alone or in any
derivative version prepared by Licensee. Alternately, in lieu of
CNRI's License Agreement, Licensee may substitute the following text
(omitting the quotes): ``Python 1.6.1 is made available subject to the
terms and conditions in CNRI's License Agreement. This Agreement
together with Python 1.6.1 may be located on the Internet using the
following unique, persistent identifier (known as a handle):
1895.22/1013. This Agreement may also be obtained from a proxy server
on the Internet using the following URL:
http://hdl.handle.net/1895.22/1013.''
3. In the event Licensee prepares a derivative work that is based on
or incorporates Python 1.6.1 or any part thereof, and wants to make
the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Python 1.6.1.
4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS''
basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT
INFRINGE ANY THIRD PARTY RIGHTS.
5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1,
OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
7. This License Agreement shall be governed by the federal
intellectual property law of the United States, including without
limitation the federal copyright law, and, to the extent such
U.S. federal law does not apply, by the law of the Commonwealth of
Virginia, excluding Virginia's conflict of law provisions.
Notwithstanding the foregoing, with regard to derivative works based
on Python 1.6.1 that incorporate non-separable material that was
previously distributed under the GNU General Public License (GPL), the
law of the Commonwealth of Virginia shall govern this License
Agreement only as to issues arising under or with respect to
Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this
License Agreement shall be deemed to create any relationship of
agency, partnership, or joint venture between CNRI and Licensee. This
License Agreement does not grant permission to use CNRI trademarks or
trade name in a trademark sense to endorse or promote products or
services of Licensee, or any third party.
8. By clicking on the ``ACCEPT'' button where indicated, or by copying,
installing or otherwise using Python 1.6.1, Licensee agrees to be
bound by the terms and conditions of this License Agreement.
ACCEPT
CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2
Copyright © 1991 - 1995, Stichting Mathematisch Centrum
Amsterdam, The Netherlands. All rights reserved.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.
STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.