diff options
| -rw-r--r-- | Doc/Makefile | 53 | ||||
| -rw-r--r-- | Doc/api.tex | 884 | ||||
| -rw-r--r-- | Doc/api/api.tex | 884 | ||||
| -rw-r--r-- | Doc/ext.tex | 2 | ||||
| -rw-r--r-- | Doc/ext/ext.tex | 2 | ||||
| -rw-r--r-- | Doc/extref.tex | 641 | ||||
| -rw-r--r-- | Doc/myformat.sty | 1 | ||||
| -rw-r--r-- | Doc/qua.tex | 1236 | ||||
| -rw-r--r-- | Doc/quabib.bib | 139 |
9 files changed, 1800 insertions, 2042 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index 3edd6b6..a136685 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -7,6 +7,7 @@ # tut -- Tutorial (file tut.tex) # lib -- Library Reference (file lib.tex, inputs lib*.tex) # ext -- Extending and Embedding (file ext.tex) +# api -- Python-C API Reference # # The Reference Manual is now maintained as a FrameMaker document. # See the subdirectory ref; PostScript is included as ref/ref.ps. @@ -18,9 +19,6 @@ # four. You can also do "make lib" (etc.) to process individual # documents. # -# There's also: -# qua -- Paper published in the CWI Quarterly (file qua.tex) -# # There's one local style file: myformat.sty. This defines a number # of macros that are similar in name and intent as macros in Texinfo # (e.g. \code{...} and \emph{...}), as well as a number of @@ -31,7 +29,6 @@ # latex # makeindex # dvips -# bibtex (only for formatting qua.tex) # # There's a problem with generating the index which has been solved by # a sed command applied to the index file. The shell script fix_hack @@ -43,7 +40,7 @@ # Additional targets attempt to convert selected LaTeX sources to # various other formats. These are generally site specific because # the tools used are all but universal. These targets are: -# l2h -- convert tut, lib, ext from LaTeX to HTML +# l2h -- convert tut, lib, ext, api from LaTeX to HTML # See the README file for more info on these targets. # Customizations -- you *may* have to edit these @@ -67,19 +64,17 @@ DOCDESTDIR= $LIBDEST/doc # Main target all: all-ps -all-dvi: tut.dvi lib.dvi ext.dvi -all-ps: tut.ps lib.ps ext.ps +all-dvi: tut.dvi lib.dvi ext.dvi api.dvi +all-ps: tut.ps lib.ps ext.ps api.ps # Individual document fake targets tut: tut.ps lib: lib.ps ext: ext.ps - -# CWI Quarterly document fake target -qua: qua.ps +api: api.ps # Dependencies -tut.dvi lib.dvi ext.dvi: myformat.sty fix_hack +tut.dvi lib.dvi ext.dvi api.dvi: myformat.sty fix_hack # Tutorial document tut.dvi: tut.tex @@ -129,7 +124,7 @@ lib.ps: lib.dvi $(DVIPS) lib >lib.ps # Extensions document -ext.dvi: ext.tex extref.tex +ext.dvi: ext.tex touch ext.ind $(LATEX) ext ./fix_hack ext.idx @@ -139,15 +134,16 @@ ext.dvi: ext.tex extref.tex ext.ps: ext.dvi $(DVIPS) ext >ext.ps -# Quarterly document -qua.dvi: qua.tex quabib.bib - $(LATEX) qua - $(BIBTEX) qua - $(LATEX) qua - $(BIBTEX) qua +# Python-C API document +api.dvi: api.tex + touch api.ind + $(LATEX) api + ./fix_hack api.idx + $(MAKEINDEX) api.idx + $(LATEX) api -qua.ps: qua.dvi - $(DVIPS) qua >qua.ps +api.ps: api.dvi + $(DVIPS) api >api.ps # The remaining part of the Makefile is concerned with various @@ -168,7 +164,7 @@ qua.ps: qua.dvi # of; the prominent location makes it worth the extra step. This affects the # title pages! -l2h: l2htut l2hext l2hlib +l2h: l2htut l2hext l2hlib l2htut l2htut: tut.dvi myformat.perl $(L2H) $(L2HARGS) tut.tex @@ -199,15 +195,24 @@ l2hlib: lib.dvi myformat.perl @rm -rf python-lib mv lib python-lib +l2hapi: api.dvi myformat.perl + $(L2H) $(L2HARGS) api.tex + @rm -rf python-api + sed 's/^<P CLASS=ABSTRACT>,/<P CLASS=ABSTRACT>/' \ + <api/api.html >api/xxx + ln -s api.html api/index.html + mv api/xxx api/api.html + mv api python-api + # Housekeeping targets -# Remove temporary files +# Remove temporary files; all except the following: +# - sources: .tex, .bib, .sty +# - useful results: .dvi, .ps, .texi, .info clean: rm -f @* *~ *.aux *.idx *.ilg *.ind *.log *.toc *.blg *.bbl *.pyc rm -f *.bak *.orig - # Sources: .tex, .bib, .sty - # Useful results: .dvi, .ps, .texi, .info # Remove temporaries as well as final products clobber: clean diff --git a/Doc/api.tex b/Doc/api.tex new file mode 100644 index 0000000..6c43933 --- /dev/null +++ b/Doc/api.tex @@ -0,0 +1,884 @@ +\documentstyle[twoside,11pt,myformat]{report} + +% NOTE: this file controls which chapters/sections of the library +% manual are actually printed. It is easy to customize your manual +% by commenting out sections that you're not interested in. + +\title{Python-C API Reference} + +\input{boilerplate} + +\makeindex % tell \index to actually write the .idx file + + +\begin{document} + +\pagenumbering{roman} + +\maketitle + +\input{copyright} + +\begin{abstract} + +\noindent +This manual documents the API used by C (or C++) programmers who want +to write extension modules or embed Python. It is a companion to +``Extending and Embedding the Python Interpreter'', which describes +the general principles of extension writing but does not document the +API functions in detail. + +\end{abstract} + +\pagebreak + +{ +\parskip = 0mm +\tableofcontents +} + +\pagebreak + +\pagenumbering{arabic} + + +\chapter{Introduction} + +From the viewpoint of of C access to Python services, we have: + +\begin{enumerate} + +\item "Very high level layer": two or three functions that let you +exec or eval arbitrary Python code given as a string in a module whose +name is given, passing C values in and getting C values out using +mkvalue/getargs style format strings. This does not require the user +to declare any variables of type \code{PyObject *}. This should be +enough to write a simple application that gets Python code from the +user, execs it, and returns the output or errors. + +\item "Abstract objects layer": which is the subject of this chapter. +It has many functions operating on objects, and lest you do many +things from C that you can also write in Python, without going through +the Python parser. + +\item "Concrete objects layer": This is the public type-dependent +interface provided by the standard built-in types, such as floats, +strings, and lists. This interface exists and is currently documented +by the collection of include files provides with the Python +distributions. + +\begin{enumerate} + +From the point of view of Python accessing services provided by C +modules: + +\end{enumerate} + +\item[4] "Python module interface": this interface consist of the basic +routines used to define modules and their members. Most of the +current extensions-writing guide deals with this interface. + +\item[5] "Built-in object interface": this is the interface that a new +built-in type must provide and the mechanisms and rules that a +developer of a new built-in type must use and follow. + +\end{enumerate} + +The Python C API provides four groups of operations on objects, +corresponding to the same operations in the Python language: object, +numeric, sequence, and mapping. Each protocol consists of a +collection of related operations. If an operation that is not +provided by a particular type is invoked, then the standard exception +\code{TypeError} is raised with a operation name as an argument. + +In addition, for convenience this interface defines a set of +constructors for building objects of built-in types. This is needed +so new objects can be returned from C functions that otherwise treat +objects generically. + +\section{Reference Counting} + +For most of the functions in the Python-C API, if a function retains a +reference to a Python object passed as an argument, then the function +will increase the reference count of the object. It is unnecessary +for the caller to increase the reference count of an argument in +anticipation of the object's retention. + +Usually, Python objects returned from functions should be treated as +new objects. Functions that return objects assume that the caller +will retain a reference and the reference count of the object has +already been incremented to account for this fact. A caller that does +not retain a reference to an object that is returned from a function +must decrement the reference count of the object (using +\code{Py_DECREF()}) to prevent memory leaks. + +Exceptions to these rules will be noted with the individual functions. + +\section{Include Files} + +All function, type and macro definitions needed to use the Python-C +API are included in your code by the following line: + +\code{\#include "Python.h"} + +This implies inclusion of the following standard header files: +stdio.h, string.h, errno.h, and stdlib.h (if available). + +All user visible names defined by Python.h (except those defined by +the included standard headers) have one of the prefixes \code{Py} or +\code{_Py}. Names beginning with \code{_Py} are for internal use +only. + + +\chapter{Initialization and Shutdown of an Embedded Python Interpreter} + +When embedding the Python interpreter in a C or C++ program, the +interpreter must be initialized. + +\begin{cfuncdesc}{void}{PyInitialize}{} +This function initializes the interpreter. It must be called before +any interaction with the interpreter takes place. If it is called +more than once, the second and further calls have no effect. + +The function performs the following tasks: create an environment in +which modules can be imported and Python code can be executed; +initialize the \code{__builtin__} module; initialize the \code{sys} +module; initialize \code{sys.path}; initialize signal handling; and +create the empty \code{__main__} module. + +In the current system, there is no way to undo all these +initializations or to create additional interpreter environments. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} +Register a cleanup function to be called when Python exits. The +cleanup function will be called with no arguments and should return no +value. At most 32 cleanup functions can be registered. When the +registration is successful, \code{Py_AtExit} returns 0; on failure, it +returns -1. Each cleanup function will be called t most once. The +cleanup function registered last is called first. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_Exit}{int status} +Exit the current process. This calls \code{Py_Cleanup()} (see next +item) and performs additional cleanup (under some circumstances it +will attempt to delete all modules), and then calls the standard C +library function \code{exit(status)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_Cleanup}{} +Perform some of the cleanup that \code{Py_Exit} performs, but don't +exit the process. In particular, this invokes the user's +\code{sys.exitfunc} function (if defined at all), and it invokes the +cleanup functions registered with \code{Py_AtExit()}, in reverse order +of their registration. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_FatalError}{char *message} +Print a fatal error message and die. No cleanup is performed. This +function should only be invoked when a condition is detected that +would make it dangerous to continue using the Python interpreter; +e.g., when the object administration appears to be corrupted. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyImport_Init}{} +Initialize the module table. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyImport_Cleanup}{} +Empty the module table. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyBuiltin_Init}{} +Initialize the \code{__builtin__} module. For internal use only. +\end{cfuncdesc} + + +\chapter{Reference Counting} + +The functions in this chapter are used for managing reference counts +of Python objects. + +\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o} +Increment the reference count for object \code{o}. The object must +not be \NULL{}; if you aren't sure that it isn't \NULL{}, use +\code{Py_XINCREF()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o} +Increment the reference count for object \code{o}. The object may be +\NULL{}, in which case the function has no effect. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o} +Decrement the reference count for object \code{o}. The object must +not be \NULL{}; if you aren't sure that it isn't \NULL{}, use +\code{Py_XDECREF()}. If the reference count reaches zero, the object's +type's deallocation function (which must not be \NULL{}) is invoked. + +\strong{Warning:} The deallocation function can cause arbitrary Python +code to be invoked (e.g. when a class instance with a \code{__del__()} +method is deallocated). While exceptions in such code are not +propagated, the executed code has free access to all Python global +variables. This means that any object that is reachable from a global +variable should be in a consistent state before \code{Py_DECREF()} is +invoked. For example, code to delete an object from a list should +copy a reference to the deleted object in a temporary variable, update +the list data structure, and then call \code{Py_DECREF()} for the +temporary variable. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o} +Decrement the reference count for object \code{o}.The object may be +\NULL{}, in which case the function has no effect; otherwise the +effect is the same as for \code{Py_DECREF()}, and the same warning +applies. +\end{cfuncdesc} + + +\chapter{Exception Handling} + +The functions in this chapter will let you handle and raise Python +exceptions. + +\begin{cfuncdesc}{void}{PyErr_Print}{} +\end{cfuncdesc} + + +\chapter{Utilities} + +The functions in this chapter perform various utility tasks, such as +parsing function arguments and constructing Python values from C +values. + +\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename} +Return true (nonzero) if the standard I/O file \code{fp} with name +\code{filename} is deemed interactive. This is the case for files for +which \code{isatty(fileno(fp))} is true. If the global flag +\code{Py_InteractiveFlag} is true, this function also returns true if +the \code{name} pointer is \NULL{} or if the name is equal to one of +the strings \code{"<stdin>"} or \code{"???"}. +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename} +Return the time of last modification of the file \code{filename}. +The result is encoded in the same way as the timestamp returned by +the standard C library function \code{time()}. +\end{cfuncdesc} + + +\chapter{Debugging} + +XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. + + +\chapter{The Very High Level Layer} + +The functions in this chapter will let you execute Python source code +given in a file or a buffer, but they will not let you interact in a +more detailed way with the interpreter. + + +\chapter{Abstract Objects Layer} + +The functions in this chapter interact with Python objects regardless +of their type, or with wide classes of object types (e.g. all +numerical types, or all sequence types). When used on object types +for which they do not apply, they will flag a Python exception. + +\section{Object Protocol} + +\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags} +Print an object \code{o}, on file \code{fp}. Returns -1 on error +The flags argument is used to enable certain printing +options. The only option currently supported is \code{Py_Print_RAW}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name} +Returns 1 if o has the attribute attr_name, and 0 otherwise. +This is equivalent to the Python expression: +\code{hasattr(o,attr_name)}. +This function always succeeds. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name} +Retrieve an attributed named attr_name form object o. +Returns the attribute value on success, or \NULL{} on failure. +This is the equivalent of the Python expression: \code{o.attr_name}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name} +Returns 1 if o has the attribute attr_name, and 0 otherwise. +This is equivalent to the Python expression: +\code{hasattr(o,attr_name)}. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name} +Retrieve an attributed named attr_name form object o. +Returns the attribute value on success, or \NULL{} on failure. +This is the equivalent of the Python expression: o.attr_name. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v} +Set the value of the attribute named \code{attr_name}, for object \code{o}, +to the value \code{v}. Returns -1 on failure. This is +the equivalent of the Python statement: \code{o.attr_name=v}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v} +Set the value of the attribute named \code{attr_name}, for +object \code{o}, +to the value \code{v}. Returns -1 on failure. This is +the equivalent of the Python statement: \code{o.attr_name=v}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name} +Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on +failure. This is the equivalent of the Python +statement: \code{del o.attr_name}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name} +Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on +failure. This is the equivalent of the Python +statement: \code{del o.attr_name}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result} +Compare the values of \code{o1} and \code{o2} using a routine provided by +\code{o1}, if one exists, otherwise with a routine provided by \code{o2}. +The result of the comparison is returned in \code{result}. Returns +-1 on failure. This is the equivalent of the Python +statement: \code{result=cmp(o1,o2)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2} +Compare the values of \code{o1} and \code{o2} using a routine provided by +\code{o1}, if one exists, otherwise with a routine provided by \code{o2}. +Returns the result of the comparison on success. On error, +the value returned is undefined. This is equivalent to the +Python expression: \code{cmp(o1,o2)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o} +Compute the string representation of object, \code{o}. Returns the +string representation on success, \NULL{} on failure. This is +the equivalent of the Python expression: \code{repr(o)}. +Called by the \code{repr()} built-in function and by reverse quotes. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o} +Compute the string representation of object, \code{o}. Returns the +string representation on success, \NULL{} on failure. This is +the equivalent of the Python expression: \code{str(o)}. +Called by the \code{str()} built-in function and by the \code{print} +statement. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o} +Determine if the object \code{o}, is callable. Return 1 if the +object is callable and 0 otherwise. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, PyObject *args} +Call a callable Python object \code{callable_object}, with +arguments given by the tuple \code{args}. If no arguments are +needed, then args may be \NULL{}. Returns the result of the +call on success, or \NULL{} on failure. This is the equivalent +of the Python expression: \code{apply(o, args)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...} +Call a callable Python object \code{callable_object}, with a +variable number of C arguments. The C arguments are described +using a mkvalue-style format string. The format may be \NULL{}, +indicating that no arguments are provided. Returns the +result of the call on success, or \NULL{} on failure. This is +the equivalent of the Python expression: \code{apply(o,args)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...} +Call the method named \code{m} of object \code{o} with a variable number of +C arguments. The C arguments are described by a mkvalue +format string. The format may be \NULL{}, indicating that no +arguments are provided. Returns the result of the call on +success, or \NULL{} on failure. This is the equivalent of the +Python expression: \code{o.method(args)}. +Note that Special method names, such as "\code{__add__}", +"\code{__getitem__}", and so on are not supported. The specific +abstract-object routines for these must be used. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o} +Compute and return the hash value of an object \code{o}. On +failure, return -1. This is the equivalent of the Python +expression: \code{hash(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o} +Returns 1 if the object \code{o} is considered to be true, and +0 otherwise. This is equivalent to the Python expression: +\code{not not o}. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o} +On success, returns a type object corresponding to the object +type of object \code{o}. On failure, returns \NULL{}. This is +equivalent to the Python expression: \code{type(o)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o} +Return the length of object \code{o}. If the object \code{o} provides +both sequence and mapping protocols, the sequence length is +returned. On error, -1 is returned. This is the equivalent +to the Python expression: \code{len(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key} +Return element of \code{o} corresponding to the object \code{key} or \NULL{} +on failure. This is the equivalent of the Python expression: +\code{o[key]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v} +Map the object \code{key} to the value \code{v}. +Returns -1 on failure. This is the equivalent +of the Python statement: \code{o[key]=v}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key, PyObject *v} +Delete the mapping for \code{key} from \code{*o}. Returns -1 +on failure. +This is the equivalent of the Python statement: del o[key]. +\end{cfuncdesc} + + +\section{Number Protocol} + +\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o} +Returns 1 if the object \code{o} provides numeric protocols, and +false otherwise. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2} +Returns the result of adding \code{o1} and \code{o2}, or null on failure. +This is the equivalent of the Python expression: \code{o1+o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2} +Returns the result of subtracting \code{o2} from \code{o1}, or null on +failure. This is the equivalent of the Python expression: +\code{o1-o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2} +Returns the result of multiplying \code{o1} and \code{o2}, or null on +failure. This is the equivalent of the Python expression: +\code{o1*o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2} +Returns the result of dividing \code{o1} by \code{o2}, or null on failure. +This is the equivalent of the Python expression: \code{o1/o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2} +Returns the remainder of dividing \code{o1} by \code{o2}, or null on +failure. This is the equivalent of the Python expression: +\code{o1\%o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2} +See the built-in function divmod. Returns \NULL{} on failure. +This is the equivalent of the Python expression: +\code{divmod(o1,o2)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3} +See the built-in function pow. Returns \NULL{} on failure. +This is the equivalent of the Python expression: +\code{pow(o1,o2,o3)}, where \code{o3} is optional. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o} +Returns the negation of \code{o} on success, or null on failure. +This is the equivalent of the Python expression: \code{-o}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o} +Returns \code{o} on success, or \NULL{} on failure. +This is the equivalent of the Python expression: \code{+o}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o} +Returns the absolute value of \code{o}, or null on failure. This is +the equivalent of the Python expression: \code{abs(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o} +Returns the bitwise negation of \code{o} on success, or \NULL{} on +failure. This is the equivalent of the Python expression: +\code{~o}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2} +Returns the result of left shifting \code{o1} by \code{o2} on success, or +\NULL{} on failure. This is the equivalent of the Python +expression: \code{o1 << o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2} +Returns the result of right shifting \code{o1} by \code{o2} on success, or +\NULL{} on failure. This is the equivalent of the Python +expression: \code{o1 >> o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2} +Returns the result of "anding" \code{o2} and \code{o2} on success and \NULL{} +on failure. This is the equivalent of the Python +expression: \code{o1 and o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2} +Returns the bitwise exclusive or of \code{o1} by \code{o2} on success, or +\NULL{} on failure. This is the equivalent of the Python +expression: \code{o1\^{ }o2}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2} +Returns the result or \code{o1} and \code{o2} on success, or \NULL{} on +failure. This is the equivalent of the Python expression: +\code{o1 or o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Coerce}{PyObject *o1, PyObject *o2} +This function takes the addresses of two variables of type +\code{PyObject*}. + +If the objects pointed to by \code{*p1} and \code{*p2} have the same type, +increment their reference count and return 0 (success). +If the objects can be converted to a common numeric type, +replace \code{*p1} and \code{*p2} by their converted value (with 'new' +reference counts), and return 0. +If no conversion is possible, or if some other error occurs, +return -1 (failure) and don't increment the reference counts. +The call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python +statement \code{o1, o2 = coerce(o1, o2)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o} +Returns the \code{o} converted to an integer object on success, or +\NULL{} on failure. This is the equivalent of the Python +expression: \code{int(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o} +Returns the \code{o} converted to a long integer object on success, +or \NULL{} on failure. This is the equivalent of the Python +expression: \code{long(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o} +Returns the \code{o} converted to a float object on success, or \NULL{} +on failure. This is the equivalent of the Python expression: +\code{float(o)}. +\end{cfuncdesc} + + +\section{Sequence protocol} + +\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o} +Return 1 if the object provides sequence protocol, and 0 +otherwise. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2} +Return the concatination of \code{o1} and \code{o2} on success, and \NULL{} on +failure. This is the equivalent of the Python +expression: \code{o1+o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count} +Return the result of repeating sequence object \code{o} count times, +or \NULL{} on failure. This is the equivalent of the Python +expression: \code{o*count}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i} +Return the ith element of \code{o}, or \NULL{} on failure. This is the +equivalent of the Python expression: \code{o[i]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2} +Return the slice of sequence object \code{o} between \code{i1} and \code{i2}, or +\NULL{} on failure. This is the equivalent of the Python +expression, \code{o[i1:i2]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v} +Assign object \code{v} to the \code{i}th element of \code{o}. +Returns -1 on failure. This is the equivalent of the Python +statement, \code{o[i]=v}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i} +Delete the \code{i}th element of object \code{v}. Returns +-1 on failure. This is the equivalent of the Python +statement: \code{del o[i]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, int i2, PyObject *v} +Assign the sequence object \code{v} to the slice in sequence +object \code{o} from \code{i1} to \code{i2}. This is the equivalent of the Python +statement, \code{o[i1:i2]=v}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2} +Delete the slice in sequence object, \code{o}, from \code{i1} to \code{i2}. +Returns -1 on failure. This is the equivalent of the Python +statement: \code{del o[i1:i2]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} +Returns the \code{o} as a tuple on success, and \NULL{} on failure. +This is equivalent to the Python expression: \code{tuple(o)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value} +Return the number of occurrences of \code{value} on \code{o}, that is, +return the number of keys for which \code{o[key]==value}. On +failure, return -1. This is equivalent to the Python +expression: \code{o.count(value)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_In}{PyObject *o, PyObject *value} +Determine if \code{o} contains \code{value}. If an item in \code{o} is equal to +\code{value}, return 1, otherwise return 0. On error, return -1. This +is equivalent to the Python expression: \code{value in o}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value} +Return the first index for which \code{o[i]=value}. On error, +return -1. This is equivalent to the Python +expression: \code{o.index(value)}. +\end{cfuncdesc} + +\section{Mapping protocol} + +\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o} +Return 1 if the object provides mapping protocol, and 0 +otherwise. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o} +Returns the number of keys in object \code{o} on success, and -1 on +failure. For objects that do not provide sequence protocol, +this is equivalent to the Python expression: \code{len(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key} +Remove the mapping for object \code{key} from the object \code{o}. +Return -1 on failure. This is equivalent to +the Python statement: \code{del o[key]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key} +Remove the mapping for object \code{key} from the object \code{o}. +Return -1 on failure. This is equivalent to +the Python statement: \code{del o[key]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key} +On success, return 1 if the mapping object has the key \code{key} +and 0 otherwise. This is equivalent to the Python expression: +\code{o.has_key(key)}. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key} +Return 1 if the mapping object has the key \code{key} +and 0 otherwise. This is equivalent to the Python expression: +\code{o.has_key(key)}. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o} +On success, return a list of the keys in object \code{o}. On +failure, return \NULL{}. This is equivalent to the Python +expression: \code{o.keys()}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o} +On success, return a list of the values in object \code{o}. On +failure, return \NULL{}. This is equivalent to the Python +expression: \code{o.values()}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o} +On success, return a list of the items in object \code{o}, where +each item is a tuple containing a key-value pair. On +failure, return \NULL{}. This is equivalent to the Python +expression: \code{o.items()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyMapping_Clear}{PyObject *o} +Make object \code{o} empty. Returns 1 on success and 0 on failure. +This is equivalent to the Python statement: +\code{for key in o.keys(): del o[key]} +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key} +Return element of \code{o} corresponding to the object \code{key} or \NULL{} +on failure. This is the equivalent of the Python expression: +\code{o[key]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v} +Map the object \code{key} to the value \code{v} in object \code{o}. Returns +-1 on failure. This is the equivalent of the Python +statement: \code{o[key]=v}. +\end{cfuncdesc} + + +\section{Constructors} + +\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *file_name, char *mode} +On success, returns a new file object that is opened on the +file given by \code{file_name}, with a file mode given by \code{mode}, +where \code{mode} has the same semantics as the standard C routine, +fopen. On failure, return -1. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, char *file_name, char *mode, int close_on_del} +Return a new file object for an already opened standard C +file pointer, \code{fp}. A file name, \code{file_name}, and open mode, +\code{mode}, must be provided as well as a flag, \code{close_on_del}, that +indicates whether the file is to be closed when the file +object is destroyed. On failure, return -1. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v} +Returns a new float object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long v} +Returns a new int object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyList_New}{int l} +Returns a new list of length \code{l} on success, and \NULL{} on +failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v} +Returns a new long object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v} +Returns a new long object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDict_New}{} +Returns a new empty dictionary on success, and \NULL{} on +failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_FromString}{char *v} +Returns a new string object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{char *v, int l} +Returns a new string object with the value \code{v} and length \code{l} +on success, and \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int l} +Returns a new tuple of length \code{l} on success, and \NULL{} on +failure. +\end{cfuncdesc} + + +\chapter{Concrete Objects Layer} + +The functions in this chapter are specific to certain Python object +types. Passing them an object of the wrong type is not a good idea; +if you receive an object from a Python program and you are not sure +that it has the right type, you must perform a type check first; +e.g. to check that an object is a dictionary, use +\code{PyDict_Check()}. + + +\chapter{Defining New Object Types} + +\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type} +\end{cfuncdesc} + +\input{api.ind} % Index -- must be last + +\end{document} diff --git a/Doc/api/api.tex b/Doc/api/api.tex new file mode 100644 index 0000000..6c43933 --- /dev/null +++ b/Doc/api/api.tex @@ -0,0 +1,884 @@ +\documentstyle[twoside,11pt,myformat]{report} + +% NOTE: this file controls which chapters/sections of the library +% manual are actually printed. It is easy to customize your manual +% by commenting out sections that you're not interested in. + +\title{Python-C API Reference} + +\input{boilerplate} + +\makeindex % tell \index to actually write the .idx file + + +\begin{document} + +\pagenumbering{roman} + +\maketitle + +\input{copyright} + +\begin{abstract} + +\noindent +This manual documents the API used by C (or C++) programmers who want +to write extension modules or embed Python. It is a companion to +``Extending and Embedding the Python Interpreter'', which describes +the general principles of extension writing but does not document the +API functions in detail. + +\end{abstract} + +\pagebreak + +{ +\parskip = 0mm +\tableofcontents +} + +\pagebreak + +\pagenumbering{arabic} + + +\chapter{Introduction} + +From the viewpoint of of C access to Python services, we have: + +\begin{enumerate} + +\item "Very high level layer": two or three functions that let you +exec or eval arbitrary Python code given as a string in a module whose +name is given, passing C values in and getting C values out using +mkvalue/getargs style format strings. This does not require the user +to declare any variables of type \code{PyObject *}. This should be +enough to write a simple application that gets Python code from the +user, execs it, and returns the output or errors. + +\item "Abstract objects layer": which is the subject of this chapter. +It has many functions operating on objects, and lest you do many +things from C that you can also write in Python, without going through +the Python parser. + +\item "Concrete objects layer": This is the public type-dependent +interface provided by the standard built-in types, such as floats, +strings, and lists. This interface exists and is currently documented +by the collection of include files provides with the Python +distributions. + +\begin{enumerate} + +From the point of view of Python accessing services provided by C +modules: + +\end{enumerate} + +\item[4] "Python module interface": this interface consist of the basic +routines used to define modules and their members. Most of the +current extensions-writing guide deals with this interface. + +\item[5] "Built-in object interface": this is the interface that a new +built-in type must provide and the mechanisms and rules that a +developer of a new built-in type must use and follow. + +\end{enumerate} + +The Python C API provides four groups of operations on objects, +corresponding to the same operations in the Python language: object, +numeric, sequence, and mapping. Each protocol consists of a +collection of related operations. If an operation that is not +provided by a particular type is invoked, then the standard exception +\code{TypeError} is raised with a operation name as an argument. + +In addition, for convenience this interface defines a set of +constructors for building objects of built-in types. This is needed +so new objects can be returned from C functions that otherwise treat +objects generically. + +\section{Reference Counting} + +For most of the functions in the Python-C API, if a function retains a +reference to a Python object passed as an argument, then the function +will increase the reference count of the object. It is unnecessary +for the caller to increase the reference count of an argument in +anticipation of the object's retention. + +Usually, Python objects returned from functions should be treated as +new objects. Functions that return objects assume that the caller +will retain a reference and the reference count of the object has +already been incremented to account for this fact. A caller that does +not retain a reference to an object that is returned from a function +must decrement the reference count of the object (using +\code{Py_DECREF()}) to prevent memory leaks. + +Exceptions to these rules will be noted with the individual functions. + +\section{Include Files} + +All function, type and macro definitions needed to use the Python-C +API are included in your code by the following line: + +\code{\#include "Python.h"} + +This implies inclusion of the following standard header files: +stdio.h, string.h, errno.h, and stdlib.h (if available). + +All user visible names defined by Python.h (except those defined by +the included standard headers) have one of the prefixes \code{Py} or +\code{_Py}. Names beginning with \code{_Py} are for internal use +only. + + +\chapter{Initialization and Shutdown of an Embedded Python Interpreter} + +When embedding the Python interpreter in a C or C++ program, the +interpreter must be initialized. + +\begin{cfuncdesc}{void}{PyInitialize}{} +This function initializes the interpreter. It must be called before +any interaction with the interpreter takes place. If it is called +more than once, the second and further calls have no effect. + +The function performs the following tasks: create an environment in +which modules can be imported and Python code can be executed; +initialize the \code{__builtin__} module; initialize the \code{sys} +module; initialize \code{sys.path}; initialize signal handling; and +create the empty \code{__main__} module. + +In the current system, there is no way to undo all these +initializations or to create additional interpreter environments. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} +Register a cleanup function to be called when Python exits. The +cleanup function will be called with no arguments and should return no +value. At most 32 cleanup functions can be registered. When the +registration is successful, \code{Py_AtExit} returns 0; on failure, it +returns -1. Each cleanup function will be called t most once. The +cleanup function registered last is called first. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_Exit}{int status} +Exit the current process. This calls \code{Py_Cleanup()} (see next +item) and performs additional cleanup (under some circumstances it +will attempt to delete all modules), and then calls the standard C +library function \code{exit(status)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_Cleanup}{} +Perform some of the cleanup that \code{Py_Exit} performs, but don't +exit the process. In particular, this invokes the user's +\code{sys.exitfunc} function (if defined at all), and it invokes the +cleanup functions registered with \code{Py_AtExit()}, in reverse order +of their registration. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_FatalError}{char *message} +Print a fatal error message and die. No cleanup is performed. This +function should only be invoked when a condition is detected that +would make it dangerous to continue using the Python interpreter; +e.g., when the object administration appears to be corrupted. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyImport_Init}{} +Initialize the module table. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyImport_Cleanup}{} +Empty the module table. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyBuiltin_Init}{} +Initialize the \code{__builtin__} module. For internal use only. +\end{cfuncdesc} + + +\chapter{Reference Counting} + +The functions in this chapter are used for managing reference counts +of Python objects. + +\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o} +Increment the reference count for object \code{o}. The object must +not be \NULL{}; if you aren't sure that it isn't \NULL{}, use +\code{Py_XINCREF()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o} +Increment the reference count for object \code{o}. The object may be +\NULL{}, in which case the function has no effect. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o} +Decrement the reference count for object \code{o}. The object must +not be \NULL{}; if you aren't sure that it isn't \NULL{}, use +\code{Py_XDECREF()}. If the reference count reaches zero, the object's +type's deallocation function (which must not be \NULL{}) is invoked. + +\strong{Warning:} The deallocation function can cause arbitrary Python +code to be invoked (e.g. when a class instance with a \code{__del__()} +method is deallocated). While exceptions in such code are not +propagated, the executed code has free access to all Python global +variables. This means that any object that is reachable from a global +variable should be in a consistent state before \code{Py_DECREF()} is +invoked. For example, code to delete an object from a list should +copy a reference to the deleted object in a temporary variable, update +the list data structure, and then call \code{Py_DECREF()} for the +temporary variable. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o} +Decrement the reference count for object \code{o}.The object may be +\NULL{}, in which case the function has no effect; otherwise the +effect is the same as for \code{Py_DECREF()}, and the same warning +applies. +\end{cfuncdesc} + + +\chapter{Exception Handling} + +The functions in this chapter will let you handle and raise Python +exceptions. + +\begin{cfuncdesc}{void}{PyErr_Print}{} +\end{cfuncdesc} + + +\chapter{Utilities} + +The functions in this chapter perform various utility tasks, such as +parsing function arguments and constructing Python values from C +values. + +\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename} +Return true (nonzero) if the standard I/O file \code{fp} with name +\code{filename} is deemed interactive. This is the case for files for +which \code{isatty(fileno(fp))} is true. If the global flag +\code{Py_InteractiveFlag} is true, this function also returns true if +the \code{name} pointer is \NULL{} or if the name is equal to one of +the strings \code{"<stdin>"} or \code{"???"}. +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename} +Return the time of last modification of the file \code{filename}. +The result is encoded in the same way as the timestamp returned by +the standard C library function \code{time()}. +\end{cfuncdesc} + + +\chapter{Debugging} + +XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. + + +\chapter{The Very High Level Layer} + +The functions in this chapter will let you execute Python source code +given in a file or a buffer, but they will not let you interact in a +more detailed way with the interpreter. + + +\chapter{Abstract Objects Layer} + +The functions in this chapter interact with Python objects regardless +of their type, or with wide classes of object types (e.g. all +numerical types, or all sequence types). When used on object types +for which they do not apply, they will flag a Python exception. + +\section{Object Protocol} + +\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags} +Print an object \code{o}, on file \code{fp}. Returns -1 on error +The flags argument is used to enable certain printing +options. The only option currently supported is \code{Py_Print_RAW}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name} +Returns 1 if o has the attribute attr_name, and 0 otherwise. +This is equivalent to the Python expression: +\code{hasattr(o,attr_name)}. +This function always succeeds. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name} +Retrieve an attributed named attr_name form object o. +Returns the attribute value on success, or \NULL{} on failure. +This is the equivalent of the Python expression: \code{o.attr_name}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name} +Returns 1 if o has the attribute attr_name, and 0 otherwise. +This is equivalent to the Python expression: +\code{hasattr(o,attr_name)}. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name} +Retrieve an attributed named attr_name form object o. +Returns the attribute value on success, or \NULL{} on failure. +This is the equivalent of the Python expression: o.attr_name. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v} +Set the value of the attribute named \code{attr_name}, for object \code{o}, +to the value \code{v}. Returns -1 on failure. This is +the equivalent of the Python statement: \code{o.attr_name=v}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v} +Set the value of the attribute named \code{attr_name}, for +object \code{o}, +to the value \code{v}. Returns -1 on failure. This is +the equivalent of the Python statement: \code{o.attr_name=v}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name} +Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on +failure. This is the equivalent of the Python +statement: \code{del o.attr_name}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name} +Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on +failure. This is the equivalent of the Python +statement: \code{del o.attr_name}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result} +Compare the values of \code{o1} and \code{o2} using a routine provided by +\code{o1}, if one exists, otherwise with a routine provided by \code{o2}. +The result of the comparison is returned in \code{result}. Returns +-1 on failure. This is the equivalent of the Python +statement: \code{result=cmp(o1,o2)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2} +Compare the values of \code{o1} and \code{o2} using a routine provided by +\code{o1}, if one exists, otherwise with a routine provided by \code{o2}. +Returns the result of the comparison on success. On error, +the value returned is undefined. This is equivalent to the +Python expression: \code{cmp(o1,o2)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o} +Compute the string representation of object, \code{o}. Returns the +string representation on success, \NULL{} on failure. This is +the equivalent of the Python expression: \code{repr(o)}. +Called by the \code{repr()} built-in function and by reverse quotes. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o} +Compute the string representation of object, \code{o}. Returns the +string representation on success, \NULL{} on failure. This is +the equivalent of the Python expression: \code{str(o)}. +Called by the \code{str()} built-in function and by the \code{print} +statement. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o} +Determine if the object \code{o}, is callable. Return 1 if the +object is callable and 0 otherwise. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, PyObject *args} +Call a callable Python object \code{callable_object}, with +arguments given by the tuple \code{args}. If no arguments are +needed, then args may be \NULL{}. Returns the result of the +call on success, or \NULL{} on failure. This is the equivalent +of the Python expression: \code{apply(o, args)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...} +Call a callable Python object \code{callable_object}, with a +variable number of C arguments. The C arguments are described +using a mkvalue-style format string. The format may be \NULL{}, +indicating that no arguments are provided. Returns the +result of the call on success, or \NULL{} on failure. This is +the equivalent of the Python expression: \code{apply(o,args)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...} +Call the method named \code{m} of object \code{o} with a variable number of +C arguments. The C arguments are described by a mkvalue +format string. The format may be \NULL{}, indicating that no +arguments are provided. Returns the result of the call on +success, or \NULL{} on failure. This is the equivalent of the +Python expression: \code{o.method(args)}. +Note that Special method names, such as "\code{__add__}", +"\code{__getitem__}", and so on are not supported. The specific +abstract-object routines for these must be used. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o} +Compute and return the hash value of an object \code{o}. On +failure, return -1. This is the equivalent of the Python +expression: \code{hash(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o} +Returns 1 if the object \code{o} is considered to be true, and +0 otherwise. This is equivalent to the Python expression: +\code{not not o}. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o} +On success, returns a type object corresponding to the object +type of object \code{o}. On failure, returns \NULL{}. This is +equivalent to the Python expression: \code{type(o)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o} +Return the length of object \code{o}. If the object \code{o} provides +both sequence and mapping protocols, the sequence length is +returned. On error, -1 is returned. This is the equivalent +to the Python expression: \code{len(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key} +Return element of \code{o} corresponding to the object \code{key} or \NULL{} +on failure. This is the equivalent of the Python expression: +\code{o[key]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v} +Map the object \code{key} to the value \code{v}. +Returns -1 on failure. This is the equivalent +of the Python statement: \code{o[key]=v}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key, PyObject *v} +Delete the mapping for \code{key} from \code{*o}. Returns -1 +on failure. +This is the equivalent of the Python statement: del o[key]. +\end{cfuncdesc} + + +\section{Number Protocol} + +\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o} +Returns 1 if the object \code{o} provides numeric protocols, and +false otherwise. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2} +Returns the result of adding \code{o1} and \code{o2}, or null on failure. +This is the equivalent of the Python expression: \code{o1+o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2} +Returns the result of subtracting \code{o2} from \code{o1}, or null on +failure. This is the equivalent of the Python expression: +\code{o1-o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2} +Returns the result of multiplying \code{o1} and \code{o2}, or null on +failure. This is the equivalent of the Python expression: +\code{o1*o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2} +Returns the result of dividing \code{o1} by \code{o2}, or null on failure. +This is the equivalent of the Python expression: \code{o1/o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2} +Returns the remainder of dividing \code{o1} by \code{o2}, or null on +failure. This is the equivalent of the Python expression: +\code{o1\%o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2} +See the built-in function divmod. Returns \NULL{} on failure. +This is the equivalent of the Python expression: +\code{divmod(o1,o2)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3} +See the built-in function pow. Returns \NULL{} on failure. +This is the equivalent of the Python expression: +\code{pow(o1,o2,o3)}, where \code{o3} is optional. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o} +Returns the negation of \code{o} on success, or null on failure. +This is the equivalent of the Python expression: \code{-o}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o} +Returns \code{o} on success, or \NULL{} on failure. +This is the equivalent of the Python expression: \code{+o}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o} +Returns the absolute value of \code{o}, or null on failure. This is +the equivalent of the Python expression: \code{abs(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o} +Returns the bitwise negation of \code{o} on success, or \NULL{} on +failure. This is the equivalent of the Python expression: +\code{~o}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2} +Returns the result of left shifting \code{o1} by \code{o2} on success, or +\NULL{} on failure. This is the equivalent of the Python +expression: \code{o1 << o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2} +Returns the result of right shifting \code{o1} by \code{o2} on success, or +\NULL{} on failure. This is the equivalent of the Python +expression: \code{o1 >> o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2} +Returns the result of "anding" \code{o2} and \code{o2} on success and \NULL{} +on failure. This is the equivalent of the Python +expression: \code{o1 and o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2} +Returns the bitwise exclusive or of \code{o1} by \code{o2} on success, or +\NULL{} on failure. This is the equivalent of the Python +expression: \code{o1\^{ }o2}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2} +Returns the result or \code{o1} and \code{o2} on success, or \NULL{} on +failure. This is the equivalent of the Python expression: +\code{o1 or o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Coerce}{PyObject *o1, PyObject *o2} +This function takes the addresses of two variables of type +\code{PyObject*}. + +If the objects pointed to by \code{*p1} and \code{*p2} have the same type, +increment their reference count and return 0 (success). +If the objects can be converted to a common numeric type, +replace \code{*p1} and \code{*p2} by their converted value (with 'new' +reference counts), and return 0. +If no conversion is possible, or if some other error occurs, +return -1 (failure) and don't increment the reference counts. +The call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python +statement \code{o1, o2 = coerce(o1, o2)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o} +Returns the \code{o} converted to an integer object on success, or +\NULL{} on failure. This is the equivalent of the Python +expression: \code{int(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o} +Returns the \code{o} converted to a long integer object on success, +or \NULL{} on failure. This is the equivalent of the Python +expression: \code{long(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o} +Returns the \code{o} converted to a float object on success, or \NULL{} +on failure. This is the equivalent of the Python expression: +\code{float(o)}. +\end{cfuncdesc} + + +\section{Sequence protocol} + +\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o} +Return 1 if the object provides sequence protocol, and 0 +otherwise. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2} +Return the concatination of \code{o1} and \code{o2} on success, and \NULL{} on +failure. This is the equivalent of the Python +expression: \code{o1+o2}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count} +Return the result of repeating sequence object \code{o} count times, +or \NULL{} on failure. This is the equivalent of the Python +expression: \code{o*count}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i} +Return the ith element of \code{o}, or \NULL{} on failure. This is the +equivalent of the Python expression: \code{o[i]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2} +Return the slice of sequence object \code{o} between \code{i1} and \code{i2}, or +\NULL{} on failure. This is the equivalent of the Python +expression, \code{o[i1:i2]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v} +Assign object \code{v} to the \code{i}th element of \code{o}. +Returns -1 on failure. This is the equivalent of the Python +statement, \code{o[i]=v}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i} +Delete the \code{i}th element of object \code{v}. Returns +-1 on failure. This is the equivalent of the Python +statement: \code{del o[i]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, int i2, PyObject *v} +Assign the sequence object \code{v} to the slice in sequence +object \code{o} from \code{i1} to \code{i2}. This is the equivalent of the Python +statement, \code{o[i1:i2]=v}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2} +Delete the slice in sequence object, \code{o}, from \code{i1} to \code{i2}. +Returns -1 on failure. This is the equivalent of the Python +statement: \code{del o[i1:i2]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} +Returns the \code{o} as a tuple on success, and \NULL{} on failure. +This is equivalent to the Python expression: \code{tuple(o)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value} +Return the number of occurrences of \code{value} on \code{o}, that is, +return the number of keys for which \code{o[key]==value}. On +failure, return -1. This is equivalent to the Python +expression: \code{o.count(value)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_In}{PyObject *o, PyObject *value} +Determine if \code{o} contains \code{value}. If an item in \code{o} is equal to +\code{value}, return 1, otherwise return 0. On error, return -1. This +is equivalent to the Python expression: \code{value in o}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value} +Return the first index for which \code{o[i]=value}. On error, +return -1. This is equivalent to the Python +expression: \code{o.index(value)}. +\end{cfuncdesc} + +\section{Mapping protocol} + +\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o} +Return 1 if the object provides mapping protocol, and 0 +otherwise. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o} +Returns the number of keys in object \code{o} on success, and -1 on +failure. For objects that do not provide sequence protocol, +this is equivalent to the Python expression: \code{len(o)}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key} +Remove the mapping for object \code{key} from the object \code{o}. +Return -1 on failure. This is equivalent to +the Python statement: \code{del o[key]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key} +Remove the mapping for object \code{key} from the object \code{o}. +Return -1 on failure. This is equivalent to +the Python statement: \code{del o[key]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key} +On success, return 1 if the mapping object has the key \code{key} +and 0 otherwise. This is equivalent to the Python expression: +\code{o.has_key(key)}. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key} +Return 1 if the mapping object has the key \code{key} +and 0 otherwise. This is equivalent to the Python expression: +\code{o.has_key(key)}. +This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o} +On success, return a list of the keys in object \code{o}. On +failure, return \NULL{}. This is equivalent to the Python +expression: \code{o.keys()}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o} +On success, return a list of the values in object \code{o}. On +failure, return \NULL{}. This is equivalent to the Python +expression: \code{o.values()}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o} +On success, return a list of the items in object \code{o}, where +each item is a tuple containing a key-value pair. On +failure, return \NULL{}. This is equivalent to the Python +expression: \code{o.items()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyMapping_Clear}{PyObject *o} +Make object \code{o} empty. Returns 1 on success and 0 on failure. +This is equivalent to the Python statement: +\code{for key in o.keys(): del o[key]} +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key} +Return element of \code{o} corresponding to the object \code{key} or \NULL{} +on failure. This is the equivalent of the Python expression: +\code{o[key]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v} +Map the object \code{key} to the value \code{v} in object \code{o}. Returns +-1 on failure. This is the equivalent of the Python +statement: \code{o[key]=v}. +\end{cfuncdesc} + + +\section{Constructors} + +\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *file_name, char *mode} +On success, returns a new file object that is opened on the +file given by \code{file_name}, with a file mode given by \code{mode}, +where \code{mode} has the same semantics as the standard C routine, +fopen. On failure, return -1. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, char *file_name, char *mode, int close_on_del} +Return a new file object for an already opened standard C +file pointer, \code{fp}. A file name, \code{file_name}, and open mode, +\code{mode}, must be provided as well as a flag, \code{close_on_del}, that +indicates whether the file is to be closed when the file +object is destroyed. On failure, return -1. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v} +Returns a new float object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long v} +Returns a new int object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyList_New}{int l} +Returns a new list of length \code{l} on success, and \NULL{} on +failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v} +Returns a new long object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v} +Returns a new long object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDict_New}{} +Returns a new empty dictionary on success, and \NULL{} on +failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_FromString}{char *v} +Returns a new string object with the value \code{v} on success, and +\NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{char *v, int l} +Returns a new string object with the value \code{v} and length \code{l} +on success, and \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int l} +Returns a new tuple of length \code{l} on success, and \NULL{} on +failure. +\end{cfuncdesc} + + +\chapter{Concrete Objects Layer} + +The functions in this chapter are specific to certain Python object +types. Passing them an object of the wrong type is not a good idea; +if you receive an object from a Python program and you are not sure +that it has the right type, you must perform a type check first; +e.g. to check that an object is a dictionary, use +\code{PyDict_Check()}. + + +\chapter{Defining New Object Types} + +\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type} +\end{cfuncdesc} + +\input{api.ind} % Index -- must be last + +\end{document} diff --git a/Doc/ext.tex b/Doc/ext.tex index cf39f39..b32702e 100644 --- a/Doc/ext.tex +++ b/Doc/ext.tex @@ -1366,7 +1366,7 @@ whitespace-separated absolute pathnames of libraries (\samp{.a} files). No \samp{-l} options can be used. -\input{extref} +%\input{extref} \input{ext.ind} diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex index cf39f39..b32702e 100644 --- a/Doc/ext/ext.tex +++ b/Doc/ext/ext.tex @@ -1366,7 +1366,7 @@ whitespace-separated absolute pathnames of libraries (\samp{.a} files). No \samp{-l} options can be used. -\input{extref} +%\input{extref} \input{ext.ind} diff --git a/Doc/extref.tex b/Doc/extref.tex deleted file mode 100644 index fed1262..0000000 --- a/Doc/extref.tex +++ /dev/null @@ -1,641 +0,0 @@ -\newcommand{\NULL}{\code{NULL}} - -\chapter{Extension Reference} - -\section{Introduction} - -From the viewpoint of of C access to Python services, we have: - -\begin{enumerate} - \item "Very high level layer": two or three functions that let you exec or - eval arbitrary Python code given as a string in a module whose name is - given, passing C values in and getting C values out using - mkvalue/getargs style format strings. This does not require the user - to declare any variables of type "PyObject *". This should be enough - to write a simple application that gets Python code from the user, - execs it, and returns the output or errors. - - \item "Abstract objects layer": which is the subject of this chapter. - It has many functions operating on objects, and lest you do many - things from C that you can also write in Python, without going - through the Python parser. - - \item "Concrete objects layer": This is the public type-dependent - interface provided by the standard built-in types, such as floats, - strings, and lists. This interface exists and is currently - documented by the collection of include files provides with the - Python distributions. - - From the point of view of Python accessing services provided by C - modules: - - \item "Python module interface": this interface consist of the basic - routines used to define modules and their members. Most of the - current extensions-writing guide deals with this interface. - - \item "Built-in object interface": this is the interface that a new - built-in type must provide and the mechanisms and rules that a - developer of a new built-in type must use and follow. -\end{enumerate} - - The Python C object interface provides four protocols: object, - numeric, sequence, and mapping. Each protocol consists of a - collection of related operations. If an operation that is not - provided by a particular type is invoked, then a standard exception, - NotImplementedError is raised with a operation name as an argument. - In addition, for convenience this interface defines a set of - constructors for building objects of built-in types. This is needed - so new objects can be returned from C functions that otherwise treat - objects generically. - -\subsection{Memory Management} - - For all of the functions described in this chapter, if a function - retains a reference to a Python object passed as an argument, then the - function will increase the reference count of the object. It is - unnecessary for the caller to increase the reference count of an - argument in anticipation of the object's retention. - - All Python objects returned from functions should be treated as new - objects. Functions that return objects assume that the caller will - retain a reference and the reference count of the object has already - been incremented to account for this fact. A caller that does not - retain a reference to an object that is returned from a function - must decrement the reference count of the object (using - DECREF(object)) to prevent memory leaks. - - -\section{Object Protocol} - - \begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags} - Print an object \code{o}, on file \code{fp}. Returns -1 on error - The flags argument is used to enable certain printing - options. The only option currently supported is \code{Py_Print_RAW}. - \end{cfuncdesc} - - \begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name} - Returns 1 if o has the attribute attr_name, and 0 otherwise. - This is equivalent to the Python expression: - \code{hasattr(o,attr_name)}. - This function always succeeds. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name} - Retrieve an attributed named attr_name form object o. - Returns the attribute value on success, or {\NULL} on failure. - This is the equivalent of the Python expression: \code{o.attr_name}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name} - Returns 1 if o has the attribute attr_name, and 0 otherwise. - This is equivalent to the Python expression: - \code{hasattr(o,attr_name)}. - This function always succeeds. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name} - Retrieve an attributed named attr_name form object o. - Returns the attribute value on success, or {\NULL} on failure. - This is the equivalent of the Python expression: o.attr_name. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v} - Set the value of the attribute named \code{attr_name}, for object \code{o}, - to the value \code{v}. Returns -1 on failure. This is - the equivalent of the Python statement: \code{o.attr_name=v}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v} - Set the value of the attribute named \code{attr_name}, for - object \code{o}, - to the value \code{v}. Returns -1 on failure. This is - the equivalent of the Python statement: \code{o.attr_name=v}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name} - Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on - failure. This is the equivalent of the Python - statement: \code{del o.attr_name}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name} - Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on - failure. This is the equivalent of the Python - statement: \code{del o.attr_name}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result} - Compare the values of \code{o1} and \code{o2} using a routine provided by - \code{o1}, if one exists, otherwise with a routine provided by \code{o2}. - The result of the comparison is returned in \code{result}. Returns - -1 on failure. This is the equivalent of the Python - statement: \code{result=cmp(o1,o2)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2} - Compare the values of \code{o1} and \code{o2} using a routine provided by - \code{o1}, if one exists, otherwise with a routine provided by \code{o2}. - Returns the result of the comparison on success. On error, - the value returned is undefined. This is equivalent to the - Python expression: \code{cmp(o1,o2)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o} - Compute the string representation of object, \code{o}. Returns the - string representation on success, {\NULL} on failure. This is - the equivalent of the Python expression: \code{repr(o)}. - Called by the \code{repr()} built-in function and by reverse quotes. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o} - Compute the string representation of object, \code{o}. Returns the - string representation on success, {\NULL} on failure. This is - the equivalent of the Python expression: \code{str(o)}. - Called by the \code{str()} built-in function and by the \code{print} - statement. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o} - Determine if the object \code{o}, is callable. Return 1 if the - object is callable and 0 otherwise. - This function always succeeds. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, PyObject *args} - Call a callable Python object \code{callable_object}, with - arguments given by the tuple \code{args}. If no arguments are - needed, then args may be {\NULL}. Returns the result of the - call on success, or {\NULL} on failure. This is the equivalent - of the Python expression: \code{apply(o, args)}. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...} - Call a callable Python object \code{callable_object}, with a - variable number of C arguments. The C arguments are described - using a mkvalue-style format string. The format may be {\NULL}, - indicating that no arguments are provided. Returns the - result of the call on success, or {\NULL} on failure. This is - the equivalent of the Python expression: \code{apply(o,args)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...} - Call the method named \code{m} of object \code{o} with a variable number of - C arguments. The C arguments are described by a mkvalue - format string. The format may be {\NULL}, indicating that no - arguments are provided. Returns the result of the call on - success, or {\NULL} on failure. This is the equivalent of the - Python expression: \code{o.method(args)}. - Note that Special method names, such as "\code{__add__}", - "\code{__getitem__}", and so on are not supported. The specific - abstract-object routines for these must be used. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o} - Compute and return the hash value of an object \code{o}. On - failure, return -1. This is the equivalent of the Python - expression: \code{hash(o)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o} - Returns 1 if the object \code{o} is considered to be true, and - 0 otherwise. This is equivalent to the Python expression: - \code{not not o}. - This function always succeeds. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o} - On success, returns a type object corresponding to the object - type of object \code{o}. On failure, returns {\NULL}. This is - equivalent to the Python expression: \code{type(o)}. - \end{cfuncdesc} - - \begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o} - Return the length of object \code{o}. If the object \code{o} provides - both sequence and mapping protocols, the sequence length is - returned. On error, -1 is returned. This is the equivalent - to the Python expression: \code{len(o)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key} - Return element of \code{o} corresponding to the object \code{key} or {\NULL} - on failure. This is the equivalent of the Python expression: - \code{o[key]}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v} - Map the object \code{key} to the value \code{v}. - Returns -1 on failure. This is the equivalent - of the Python statement: \code{o[key]=v}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key, PyObject *v} - Delete the mapping for \code{key} from \code{*o}. Returns -1 - on failure. - This is the equivalent of the Python statement: del o[key]. - \end{cfuncdesc} - - -\section{Number Protocol} - - \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o} - Returns 1 if the object \code{o} provides numeric protocols, and - false otherwise. - This function always succeeds. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2} - Returns the result of adding \code{o1} and \code{o2}, or null on failure. - This is the equivalent of the Python expression: \code{o1+o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2} - Returns the result of subtracting \code{o2} from \code{o1}, or null on - failure. This is the equivalent of the Python expression: - \code{o1-o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2} - Returns the result of multiplying \code{o1} and \code{o2}, or null on - failure. This is the equivalent of the Python expression: - \code{o1*o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2} - Returns the result of dividing \code{o1} by \code{o2}, or null on failure. - This is the equivalent of the Python expression: \code{o1/o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2} - Returns the remainder of dividing \code{o1} by \code{o2}, or null on - failure. This is the equivalent of the Python expression: - \code{o1\%o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2} - See the built-in function divmod. Returns {\NULL} on failure. - This is the equivalent of the Python expression: - \code{divmod(o1,o2)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3} - See the built-in function pow. Returns {\NULL} on failure. - This is the equivalent of the Python expression: - \code{pow(o1,o2,o3)}, where \code{o3} is optional. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o} - Returns the negation of \code{o} on success, or null on failure. - This is the equivalent of the Python expression: \code{-o}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o} - Returns \code{o} on success, or {\NULL} on failure. - This is the equivalent of the Python expression: \code{+o}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o} - Returns the absolute value of \code{o}, or null on failure. This is - the equivalent of the Python expression: \code{abs(o)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o} - Returns the bitwise negation of \code{o} on success, or {\NULL} on - failure. This is the equivalent of the Python expression: - \code{~o}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2} - Returns the result of left shifting \code{o1} by \code{o2} on success, or - {\NULL} on failure. This is the equivalent of the Python - expression: \code{o1 << o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2} - Returns the result of right shifting \code{o1} by \code{o2} on success, or - {\NULL} on failure. This is the equivalent of the Python - expression: \code{o1 >> o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2} - Returns the result of "anding" \code{o2} and \code{o2} on success and {\NULL} - on failure. This is the equivalent of the Python - expression: \code{o1 and o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2} - Returns the bitwise exclusive or of \code{o1} by \code{o2} on success, or - {\NULL} on failure. This is the equivalent of the Python - expression: \code{o1\^{ }o2}. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2} - Returns the result or \code{o1} and \code{o2} on success, or {\NULL} on - failure. This is the equivalent of the Python expression: - \code{o1 or o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Coerce}{PyObject *o1, PyObject *o2} - This function takes the addresses of two variables of type - \code{PyObject*}. - - If the objects pointed to by \code{*p1} and \code{*p2} have the same type, - increment their reference count and return 0 (success). - If the objects can be converted to a common numeric type, - replace \code{*p1} and \code{*p2} by their converted value (with 'new' - reference counts), and return 0. - If no conversion is possible, or if some other error occurs, - return -1 (failure) and don't increment the reference counts. - The call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python - statement \code{o1, o2 = coerce(o1, o2)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o} - Returns the \code{o} converted to an integer object on success, or - {\NULL} on failure. This is the equivalent of the Python - expression: \code{int(o)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o} - Returns the \code{o} converted to a long integer object on success, - or {\NULL} on failure. This is the equivalent of the Python - expression: \code{long(o)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o} - Returns the \code{o} converted to a float object on success, or {\NULL} - on failure. This is the equivalent of the Python expression: - \code{float(o)}. - \end{cfuncdesc} - - -\section{Sequence protocol} - - \begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o} - Return 1 if the object provides sequence protocol, and 0 - otherwise. - This function always succeeds. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2} - Return the concatination of \code{o1} and \code{o2} on success, and {\NULL} on - failure. This is the equivalent of the Python - expression: \code{o1+o2}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count} - Return the result of repeating sequence object \code{o} count times, - or {\NULL} on failure. This is the equivalent of the Python - expression: \code{o*count}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i} - Return the ith element of \code{o}, or {\NULL} on failure. This is the - equivalent of the Python expression: \code{o[i]}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2} - Return the slice of sequence object \code{o} between \code{i1} and \code{i2}, or - {\NULL} on failure. This is the equivalent of the Python - expression, \code{o[i1:i2]}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v} - Assign object \code{v} to the \code{i}th element of \code{o}. -Returns -1 on failure. This is the equivalent of the Python - statement, \code{o[i]=v}. - \end{cfuncdesc} - - \begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i} - Delete the \code{i}th element of object \code{v}. Returns - -1 on failure. This is the equivalent of the Python - statement: \code{del o[i]}. - \end{cfuncdesc} - - \begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, int i2, PyObject *v} - Assign the sequence object \code{v} to the slice in sequence - object \code{o} from \code{i1} to \code{i2}. This is the equivalent of the Python - statement, \code{o[i1:i2]=v}. - \end{cfuncdesc} - - \begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2} - Delete the slice in sequence object, \code{o}, from \code{i1} to \code{i2}. - Returns -1 on failure. This is the equivalent of the Python - statement: \code{del o[i1:i2]}. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} - Returns the \code{o} as a tuple on success, and {\NULL} on failure. - This is equivalent to the Python expression: \code{tuple(o)}. - \end{cfuncdesc} - - \begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value} - Return the number of occurrences of \code{value} on \code{o}, that is, - return the number of keys for which \code{o[key]==value}. On - failure, return -1. This is equivalent to the Python - expression: \code{o.count(value)}. - \end{cfuncdesc} - - \begin{cfuncdesc}{int}{PySequence_In}{PyObject *o, PyObject *value} - Determine if \code{o} contains \code{value}. If an item in \code{o} is equal to - \code{value}, return 1, otherwise return 0. On error, return -1. This - is equivalent to the Python expression: \code{value in o}. - \end{cfuncdesc} - - \begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value} - Return the first index for which \code{o[i]=value}. On error, - return -1. This is equivalent to the Python - expression: \code{o.index(value)}. - \end{cfuncdesc} - -\section{Mapping protocol} - - \begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o} - Return 1 if the object provides mapping protocol, and 0 - otherwise. - This function always succeeds. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o} - Returns the number of keys in object \code{o} on success, and -1 on - failure. For objects that do not provide sequence protocol, - this is equivalent to the Python expression: \code{len(o)}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key} - Remove the mapping for object \code{key} from the object \code{o}. - Return -1 on failure. This is equivalent to - the Python statement: \code{del o[key]}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key} - Remove the mapping for object \code{key} from the object \code{o}. - Return -1 on failure. This is equivalent to - the Python statement: \code{del o[key]}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key} - On success, return 1 if the mapping object has the key \code{key} - and 0 otherwise. This is equivalent to the Python expression: - \code{o.has_key(key)}. - This function always succeeds. - \end{cfuncdesc} - - - \begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key} - Return 1 if the mapping object has the key \code{key} - and 0 otherwise. This is equivalent to the Python expression: - \code{o.has_key(key)}. - This function always succeeds. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o} - On success, return a list of the keys in object \code{o}. On - failure, return {\NULL}. This is equivalent to the Python - expression: \code{o.keys()}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o} - On success, return a list of the values in object \code{o}. On - failure, return {\NULL}. This is equivalent to the Python - expression: \code{o.values()}. - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o} - On success, return a list of the items in object \code{o}, where - each item is a tuple containing a key-value pair. On - failure, return {\NULL}. This is equivalent to the Python - expression: \code{o.items()}. - \end{cfuncdesc} - - \begin{cfuncdesc}{int}{PyMapping_Clear}{PyObject *o} - Make object \code{o} empty. Returns 1 on success and 0 on failure. - This is equivalent to the Python statement: - \code{for key in o.keys(): del o[key]} - \end{cfuncdesc} - - - \begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key} - Return element of \code{o} corresponding to the object \code{key} or {\NULL} - on failure. This is the equivalent of the Python expression: - \code{o[key]}. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v} - Map the object \code{key} to the value \code{v} in object \code{o}. Returns - -1 on failure. This is the equivalent of the Python - statement: \code{o[key]=v}. - \end{cfuncdesc} - - -\section{Constructors} - - \begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *file_name, char *mode} - On success, returns a new file object that is opened on the - file given by \code{file_name}, with a file mode given by \code{mode}, - where \code{mode} has the same semantics as the standard C routine, - fopen. On failure, return -1. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, char *file_name, char *mode, int close_on_del} - Return a new file object for an already opened standard C - file pointer, \code{fp}. A file name, \code{file_name}, and open mode, - \code{mode}, must be provided as well as a flag, \code{close_on_del}, that - indicates whether the file is to be closed when the file - object is destroyed. On failure, return -1. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v} - Returns a new float object with the value \code{v} on success, and - {\NULL} on failure. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long v} - Returns a new int object with the value \code{v} on success, and - {\NULL} on failure. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyList_New}{int l} - Returns a new list of length \code{l} on success, and {\NULL} on - failure. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v} - Returns a new long object with the value \code{v} on success, and - {\NULL} on failure. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v} - Returns a new long object with the value \code{v} on success, and - {\NULL} on failure. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyDict_New}{} - Returns a new empty dictionary on success, and {\NULL} on - failure. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyString_FromString}{char *v} - Returns a new string object with the value \code{v} on success, and - {\NULL} on failure. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{char *v, int l} - Returns a new string object with the value \code{v} and length \code{l} - on success, and {\NULL} on failure. - \end{cfuncdesc} - - \begin{cfuncdesc}{PyObject*}{PyTuple_New}{int l} - Returns a new tuple of length \code{l} on success, and {\NULL} on - failure. - \end{cfuncdesc} - diff --git a/Doc/myformat.sty b/Doc/myformat.sty index dc72768..b117478 100644 --- a/Doc/myformat.sty +++ b/Doc/myformat.sty @@ -161,6 +161,7 @@ \newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}} \newcommand{\C}{C} \newcommand{\EOF}{{\sc eof}} +\newcommand{\NULL}{\code{NULL}} % code is the most difficult one... \newcommand{\code}[1]{{\@vobeyspaces\@noligs\def\{{\char`\{}\def\}{\char`\}}\def\~{\char`\~}\def\^{\char`\^}\def\e{\char`\\}\def\${\char`\$}\def\#{\char`\#}\def\&{\char`\&}\def\%{\char`\%}% diff --git a/Doc/qua.tex b/Doc/qua.tex deleted file mode 100644 index 88f5778..0000000 --- a/Doc/qua.tex +++ /dev/null @@ -1,1236 +0,0 @@ -\documentstyle[11pt]{article} -\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}} - -\title{ -Interactively Testing Remote Servers Using the Python Programming Language -} - -\author{ - Guido van Rossum \\ - Dept. AA, CWI, P.O. Box 94079 \\ - 1090 GB Amsterdam, The Netherlands \\ - E-mail: {\tt guido@cwi.nl} -\and - Jelke de Boer \\ - HIO Enschede; P.O.Box 1326 \\ - 7500 BH Enschede, The Netherlands -} - -\begin{document} - -\maketitle - -\begin{abstract} -This paper describes how two tools that were developed quite -independently gained in power by a well-designed connection between -them. The tools are Python, an interpreted prototyping language, and -AIL, a Remote Procedure Call stub generator. The context is Amoeba, a -well-known distributed operating system developed jointly by the Free -University and CWI in Amsterdam. - -As a consequence of their integration, both tools have profited: -Python gained usability when used with Amoeba --- for which it was not -specifically developed --- and AIL users now have a powerful -interactive tool to test servers and to experiment with new -client/server interfaces.% -\footnote{ -An earlier version of this paper was presented at the Spring 1991 -EurOpen Conference in Troms{\o} under the title ``Linking a Stub -Generator (AIL) to a Prototyping Language (Python).'' -} -\end{abstract} - -\section{Introduction} - -Remote Procedure Call (RPC) interfaces, used in distributed systems -like Amoeba -\cite{Amoeba:IEEE,Amoeba:CACM}, -have a much more concrete character than local procedure call -interfaces in traditional systems. Because clients and servers may -run on different machines, with possibly different word size, byte -order, etc., much care is needed to describe interfaces exactly and to -implement them in such a way that they continue to work when a client -or server is moved to a different machine. Since machines may fail -independently, error handling must also be treated more carefully. - -A common approach to such problems is to use a {\em stub generator}. -This is a program that takes an interface description and transforms -it into functions that must be compiled and linked with client and -server applications. These functions are called by the application -code to take care of details of interfacing to the system's RPC layer, -to implement transformations between data representations of different -machines, to check for errors, etc. They are called `stubs' because -they don't actually perform the action that they are called for but -only relay the parameters to the server -\cite{RPC}. - -Amoeba's stub generator is called AIL, which stands for Amoeba -Interface Language -\cite{AIL}. -The first version of AIL generated only C functions, but an explicit -goal of AIL's design was {\em retargetability}: it should be possible -to add back-ends that generate stubs for different languages from the -same interface descriptions. Moreover, the stubs generated by -different back-ends must be {\em interoperable}: a client written in -Modula-3, say, should be able to use a server written in C, and vice -versa. - -This interoperability is the key to the success of the marriage -between AIL and Python. Python is a versatile interpreted language -developed by the first author. Originally intended as an alternative -for the kind of odd jobs that are traditionally solved by a mixture of -shell scripts, manually given shell commands, and an occasional ad hoc -C program, Python has evolved into a general interactive prototyping -language. It has been applied to a wide range of problems, from -replacements for large shell scripts to fancy graphics demos and -multimedia applications. - -One of Python's strengths is the ability for the user to type in some -code and immediately run it: no compilation or linking is necessary. -Interactive performance is further enhanced by Python's concise, clear -syntax, its very-high-level data types, and its lack of declarations -(which is compensated by run-time type checking). All this makes -programming in Python feel like a leisure trip compared to the hard -work involved in writing and debugging even a smallish C program. - -It should be clear by now that Python will be the ideal tool to test -servers and their interfaces. Especially during the development of a -complex server, one often needs to generate test requests on an ad hoc -basis, to answer questions like ``what happens if request X arrives -when the server is in state Y,'' to test the behavior of the server -with requests that touch its limitations, to check server responses to -all sorts of wrong requests, etc. Python's ability to immediately -execute `improvised' code makes it a much better tool for this -situation than C. - -The link to AIL extends Python with the necessary functionality to -connect to arbitrary servers, making the server testbed sketched above -a reality. Python's high-level data types, general programming -features, and system interface ensure that it has all the power and -flexibility needed for the job. - -One could go even further than this. Current distributed operating -systems, based on client-server interaction, all lack a good command -language or `shell' to give adequate access to available services. -Python has considerable potential for becoming such a shell. - -\subsection{Overview of this Paper} - -The rest of this paper contains three major sections and a conclusion. -First an overview of the Python programming language is given. Next -comes a short description of AIL, together with some relevant details -about Amoeba. Finally, the design and construction of the link -between Python and AIL is described in much detail. The conclusion -looks back at the work and points out weaknesses and strengths of -Python and AIL that were discovered in the process. - -\section{An Overview of Python} - -Python% -\footnote{ -Named after the funny TV show, not the nasty reptile. -} -owes much to ABC -\cite{ABC}, -a language developed at CWI as a programming language for non-expert -computer users. Python borrows freely from ABC's syntax and data -types, but adds modules, exceptions and classes, extensibility, and -the ability to call system functions. The concepts of modules, -exceptions and (to some extent) classes are influenced strongly by -their occurrence in Modula-3 -\cite{Modula-3}. - -Although Python resembles ABC in many ways, there is a a clear -difference in application domain. ABC is intended to be the only -programming language for those who use a computer as a tool, but -occasionally need to write a program. For this reason, ABC is not -just a programming language but also a programming environment, which -comes with an integrated syntax-directed editor and some source -manipulation commands. Python, on the other hand, aims to be a tool -for professional (system) programmers, for whom having a choice of -languages with different feature sets makes it possible to choose `the -right tool for the job.' The features added to Python make it more -useful than ABC in an environment where access to system functions -(such as file and directory manipulations) are common. They also -support the building of larger systems and libraries. The Python -implementation offers little in the way of a programming environment, -but is designed to integrate seamlessly with existing programming -environments (e.g. UNIX and Emacs). - -Perhaps the best introduction to Python is a short example. The -following is a complete Python program to list the contents of a UNIX -directory. -\begin{verbatim} -import sys, posix - -def ls(dirname): # Print sorted directory contents - names = posix.listdir(dirname) - names.sort() - for name in names: - if name[0] != '.': print name - -ls(sys.argv[1]) -\end{verbatim} -The largest part of this program, in the middle starting with {\tt -def}, is a function definition. It defines a function named {\tt ls} -with a single parameter called {\tt dirname}. (Comments in Python -start with `\#' and extend to the end of the line.) The function body -is indented: Python uses indentation for statement grouping instead of -braces or begin/end keywords. This is shorter to type and avoids -frustrating mismatches between the perception of grouping by the user -and the parser. Python accepts one statement per line; long -statements may be broken in pieces using the standard backslash -convention. If the body of a compound statement is a single, simple -statement, it may be placed on the same line as the head. - -The first statement of the function body calls the function {\tt -listdir} defined in the module {\tt posix}. This function returns a -list of strings representing the contents of the directory name passed -as a string argument, here the argument {\tt dirname}. If {\tt -dirname} were not a valid directory name, or perhaps not even a -string, {\tt listdir} would raise an exception and the next statement -would never be reached. (Exceptions can be caught in Python; see -later.) Assuming {\tt listdir} returns normally, its result is -assigned to the local variable {\tt names}. - -The second statement calls the method {\tt sort} of the variable {\tt -names}. This method is defined for all lists in Python and does the -obvious thing: the elements of the list are reordered according to -their natural ordering relationship. Since in our example the list -contains strings, they are sorted in ascending \ASCII{} order. - -The last two lines of the function contain a loop that prints all -elements of the list whose first character isn't a period. In each -iteration, the {\tt for} statement assigns an element of the list to -the local variable {\tt name}. The {\tt print} statement is intended -for simple-minded output; more elaborate formatting is possible with -Python's string handling functions. - -The other two parts of the program are easily explained. The first -line is an {\tt import} statement that tells the interpreter to import -the modules {\tt sys} and {\tt posix}. As it happens these are both -built into the interpreter. Importing a module (built-in or -otherwise) only makes the module name available in the current scope; -functions and data defined in the module are accessed through the dot -notation as in {\tt posix.listdir}. The scope rules of Python are -such that the imported module name {\tt posix} is also available in -the function {\tt ls} (this will be discussed in more detail later). - -Finally, the last line of the program calls the {\tt ls} function with -a definite argument. It must be last since Python objects must be -defined before they can be used; in particular, the function {\tt ls} -must be defined before it can be called. The argument to {\tt ls} is -{\tt sys.argv[1]}, which happens to be the Python equivalent of {\tt -\$1} in a shell script or {\tt argv[1]} in a C program's {\tt main} -function. - -\subsection{Python Data Types} - -(This and the following subsections describe Python in quite a lot of -detail. If you are more interested in AIL, Amoeba and how they are -linked with Python, you can skip to section 3 now.) - -Python's syntax may not have big surprises (which is exactly as it -should be), but its data types are quite different from what is found -in languages like C, Ada or Modula-3. All data types in Python, even -integers, are `objects'. All objects participate in a common garbage -collection scheme (currently implemented using reference counting). -Assignment is cheap, independent of object size and type: only a -pointer to the assigned object is stored in the assigned-to variable. -No type checking is performed on assignment; only specific operations -like addition test for particular operand types. - -The basic object types in Python are numbers, strings, tuples, lists -and dictionaries. Some other object types are open files, functions, -modules, classes, and class instances; even types themselves are -represented as objects. Extension modules written in C can define -additional object types; examples are objects representing windows and -Amoeba capabilities. Finally, the implementation itself makes heavy -use of objects, and defines some private object types that aren't -normally visible to the user. There is no explicit pointer type in -Python. - -{\em Numbers}, both integers and floating point, are pretty -straightforward. The notation for numeric literals is the same as in -C, including octal and hexadecimal integers; precision is the same as -{\tt long} or {\tt double} in C\@. A third numeric type, `long -integer', written with an `L' suffix, can be used for arbitrary -precision calculations. All arithmetic, shifting and masking -operations from C are supported. - -{\em Strings} are `primitive' objects just like numbers. String -literals are written between single quotes, using similar escape -sequences as in C\@. Operations are built into the language to -concatenate and to replicate strings, to extract substrings, etc. -There is no limit to the length of the strings created by a program. -There is no separate character data type; strings of length one do -nicely. - -{\em Tuples} are a way to `pack' small amounts of heterogeneous data -together and carry them around as a unit. Unlike structure members in -C, tuple items are nameless. Packing and unpacking assignments allow -access to the items, for example: -\begin{verbatim} -x = 'Hi', (1, 2), 'World' # x is a 3-item tuple, - # its middle item is (1, 2) -p, q, r = x # unpack x into p, q and r -a, b = q # unpack q into a and b -\end{verbatim} -A combination of packing and unpacking assignment can be used as -parallel assignment, and is idiom for permutations, e.g.: -\begin{verbatim} -p, q = q, p # swap without temporary -a, b, c = b, c, a # cyclic permutation -\end{verbatim} -Tuples are also used for function argument lists if there is more than -one argument. A tuple object, once created, cannot be modified; but -it is easy enough to unpack it and create a new, modified tuple from -the unpacked items and assign this to the variable that held the -original tuple object (which will then be garbage-collected). - -{\em Lists} are array-like objects. List items may be arbitrary -objects and can be accessed and changed using standard subscription -notation. Lists support item insertion and deletion, and can -therefore be used as queues, stacks etc.; there is no limit to their -size. - -Strings, tuples and lists together are {\em sequence} types. These -share a common notation for generic operations on sequences such as -subscription, concatenation, slicing (taking subsequences) and -membership tests. As in C, subscripts start at 0. - -{\em Dictionaries} are `mappings' from one domain to another. The -basic operations on dictionaries are item insertion, extraction and -deletion, using subscript notation with the key as subscript. (The -current implementation allows only strings in the key domain, but a -future version of the language may remove this restriction.) - -\subsection{Statements} - -Python has various kinds of simple statements, such as assignments -and {\tt print} statements, and several kinds of compound statements, -like {\tt if} and {\tt for} statements. Formally, function -definitions and {\tt import} statements are also statements, and there -are no restrictions on the ordering of statements or their nesting: -{\tt import} may be used inside a function, functions may be defined -conditionally using an {\tt if} statement, etc. The effect of a -declaration-like statement takes place only when it is executed. - -All statements except assignments and expression statements begin with -a keyword: this makes the language easy to parse. An overview of the -most common statement forms in Python follows. - -An {\em assignment} has the general form -\vspace{\itemsep} - -\noindent -{\em variable $=$ variable $= ... =$ variable $=$ expression} -\vspace{\itemsep} - -It assigns the value of the expression to all listed variables. (As -shown in the section on tuples, variables and expressions can in fact -be comma-separated lists.) The assignment operator is not an -expression operator; there are no horrible things in Python like -\begin{verbatim} -while (p = p->next) { ... } -\end{verbatim} -Expression syntax is mostly straightforward and will not be explained -in detail here. - -An {\em expression statement} is just an expression on a line by -itself. This writes the value of the expression to standard output, -in a suitably unambiguous way, unless it is a `procedure call' (a -function call that returns no value). Writing the value is useful -when Python is used in `calculator mode', and reminds the programmer -not to ignore function results. - -The {\tt if} statement allows conditional execution. It has optional -{\tt elif} and {\tt else} parts; a construct like {\tt -if...elif...elif...elif...else} can be used to compensate for the -absence of a {\em switch} or {\em case} statement. - -Looping is done with {\tt while} and {\tt for} statements. The latter -(demonstrated in the `ls' example earlier) iterates over the elements -of a `sequence' (see the discussion of data types below). It is -possible to terminate a loop with a {\tt break} statement or to start -the next iteration with {\tt continue}. Both looping statements have -an optional {\tt else} clause which is executed after the loop is -terminated normally, but skipped when it is terminated by {\tt break}. -This can be handy for searches, to handle the case that the item is -not found. - -Python's {\em exception} mechanism is modelled after that of Modula-3. -Exceptions are raised by the interpreter when an illegal operation is -tried. It is also possible to explicitly raise an exception with the -{\tt raise} statement: -\vspace{\itemsep} - -\noindent -{\tt raise {\em expression}, {\em expression}} -\vspace{\itemsep} - -The first expression identifies which exception should be raised; -there are several built-in exceptions and the user may define -additional ones. The second, optional expression is passed to the -handler, e.g. as a detailed error message. - -Exceptions may be handled (caught) with the {\tt try} statement, which -has the following general form: -\vspace{\itemsep} - -\noindent -{\tt -\begin{tabular}{l} -try: {\em block} \\ -except {\em expression}, {\em variable}: {\em block} \\ -except {\em expression}, {\em variable}: {\em block} \\ -... \\ -except: {\em block} -\end{tabular} -} -\vspace{\itemsep} - -When an exception is raised during execution of the first block, a -search for an exception handler starts. The first {\tt except} clause -whose {\em expression} matches the exception is executed. The -expression may specify a list of exceptions to match against. A -handler without an expression serves as a `catch-all'. If there is no -match, the search for a handler continues with outer {\tt try} -statements; if no match is found on the entire invocation stack, an -error message and stack trace are printed, and the program is -terminated (interactively, the interpreter returns to its main loop). - -Note that the form of the {\tt except} clauses encourages a style of -programming whereby only selected exceptions are caught, passing -unanticipated exceptions on to the caller and ultimately to the user. -This is preferable over a simpler `catch-all' error handling -mechanism, where a simplistic handler intended to catch a single type -of error like `file not found' can easily mask genuine programming -errors --- especially in a language like Python which relies strongly -on run-time checking and allows the catching of almost any type of -error. - -Other common statement forms, which we have already encountered, are -function definitions, {\tt import} statements and {\tt print} -statements. There is also a {\tt del} statement to delete one or more -variables, a {\tt return} statement to return from a function, and a -{\tt global} statement to allow assignments to global variables. -Finally, the {\tt pass} statement is a no-op. - -\subsection{Execution Model} - -A Python program is executed by a stack-based interpreter. - -When a function is called, a new `execution environment' for it is -pushed onto the stack. An execution environment contains (among other -data) pointers to two `symbol tables' that are used to hold variables: -the local and the global symbol table. The local symbol table -contains local variables of the current function invocation (including -the function arguments); the global symbol table contains variables -defined in the module containing the current function. - -The `global' symbol table is thus only global with respect to the -current function. There are no system-wide global variables; using -the {\tt import} statement it is easy enough to reference variables -that are defined in other modules. A system-wide read-only symbol -table is used for built-in functions and constants though. - -On assignment to a variable, by default an entry for it is made in the -local symbol table of the current execution environment. The {\tt -global} command can override this (it is not enough that a global -variable by the same name already exists). When a variable's value is -needed, it is searched first in the local symbol table, then in the -global one, and finally in the symbol table containing built-in -functions and constants. - -The term `variable' in this context refers to any name: functions and -imported modules are searched in exactly the same way. - -Names defined in a module's symbol table survive until the end of the -program. This approximates the semantics of file-static global -variables in C or module variables in Modula-3. A module is -initialized the first time it is imported, by executing the text of -the module as a parameterless function whose local and global symbol -tables are the same, so names are defined in module's symbol table. -(Modules implemented in C have another way to define symbols.) - -A Python main program is read from standard input or from a script -file passed as an argument to the interpreter. It is executed as if -an anonymous module was imported. Since {\tt import} statements are -executed like all other statements, the initialization order of the -modules used in a program is defined by the flow of control through -the program. - -The `attribute' notation {\em m.name}, where {\em m} is a module, -accesses the symbol {\em name} in that module's symbol table. It can -be assigned to as well. This is in fact a special case of the -construct {\em x.name} where {\em x} denotes an arbitrary object; the -type of {\em x} determines how this is to be interpreted, and what -assignment to it means. - -For instance, when {\tt a} is a list object, {\tt a.append} yields a -built-in `method' object which, when called, appends an item to {\tt a}. -(If {\tt a} and {\tt b} are distinct list objects, {\tt a.append} and -{\tt b.append} are distinguishable method objects.) Normally, in -statements like {\tt a.append(x)}, the method object {\tt a.append} is -called and then discarded, but this is a matter of convention. - -List attributes are read-only --- the user cannot define new list -methods. Some objects, like numbers and strings, have no attributes -at all. Like all type checking in Python, the meaning of an attribute -is determined at run-time --- when the parser sees {\em x.name}, it -has no idea of the type of {\em x}. Note that {\em x} here does not -have to be a variable --- it can be an arbitrary (perhaps -parenthesized) expression. - -Given the flexibility of the attribute notation, one is tempted to use -methods to replace all standard operations. Yet, Python has kept a -small repertoire of built-in functions like {\tt len()} and {\tt -abs()}. The reason is that in some cases the function notation is -more familiar than the method notation; just like programs would -become less readable if all infix operators were replaced by function -calls, they would become less readable if all function calls had to be -replaced by method calls (and vice versa!). - -The choice whether to make something a built-in function or a method -is a matter of taste. For arithmetic and string operations, function -notation is preferred, since frequently the argument to such an -operation is an expression using infix notation, as in {\tt abs(a+b)}; -this definitely looks better than {\tt (a+b).abs()}. The choice -between make something a built-in function or a function defined in a -built-in method (requiring {\tt import}) is similarly guided by -intuition; all in all, only functions needed by `general' programming -techniques are built-in functions. - -\subsection{Classes} - -Python has a class mechanism distinct from the object-orientation -already explained. A class in Python is not much more than a -collection of methods and a way to create class instances. Class -methods are ordinary functions whose first parameter is the class -instance; they are called using the method notation. - -For instance, a class can be defined as follows: -\begin{verbatim} -class Foo: - def meth1(self, arg): ... - def meth2(self): ... -\end{verbatim} -A class instance is created by -{\tt x = Foo()} -and its methods can be called thus: -\begin{verbatim} -x.meth1('Hi There!') -x.meth2() -\end{verbatim} -The functions used as methods are also available as attributes of the -class object, and the above method calls could also have been written -as follows: -\begin{verbatim} -Foo.meth1(x, 'Hi There!') -Foo.meth2(x) -\end{verbatim} -Class methods can store instance data by assigning to instance data -attributes, e.g.: -\begin{verbatim} -self.size = 100 -self.title = 'Dear John' -\end{verbatim} -Data attributes do not have to be declared; as with local variables, -they spring into existence when assigned to. It is a matter of -discretion to avoid name conflicts with method names. This facility -is also available to class users; instances of a method-less class can -be used as records with named fields. - -There is no built-in mechanism for instance initialization. Classes -by convention provide an {\tt init()} method which initializes the -instance and then returns it, so the user can write -\begin{verbatim} -x = Foo().init('Dr. Strangelove') -\end{verbatim} - -Any user-defined class can be used as a base class to derive other -classes. However, built-in types like lists cannot be used as base -classes. (Incidentally, the same is true in \Cpp{} and Modula-3.) A -class may override any method of its base classes. Instance methods -are first searched in the method list of their class, and then, -recursively, in the method lists of their base class. Initialization -methods of derived classes should explicitly call the initialization -methods of their base class. - -A simple form of multiple inheritance is also supported: a class can -have multiple base classes, but the language rules for resolving name -conflicts are somewhat simplistic, and consequently the feature has so -far found little usage. - -\subsection{The Python Library} - -Python comes with an extensive library, structured as a collection of -modules. A few modules are built into the interpreter: these -generally provide access to system libraries implemented in C such as -mathematical functions or operating system calls. Two built-in -modules provide access to internals of the interpreter and its -environment. Even abusing these internals will at most cause an -exception in the Python program; the interpreter will not dump core -because of errors in Python code. - -Most modules however are written in Python and distributed with the -interpreter; they provide general programming tools like string -operations and random number generators, provide more convenient -interfaces to some built-in modules, or provide specialized services -like a {\em getopt}-style command line option processor for -stand-alone scripts. - -There are also some modules written in Python that dig deep in the -internals of the interpreter; there is a module to browse the stack -backtrace when an unhandled exception has occurred, one to disassemble -the internal representation of Python code, and even an interactive -source code debugger which can trace Python code, set breakpoints, -etc. - -\subsection{Extensibility} - -It is easy to add new built-in modules written in C to the Python -interpreter. Extensions appear to the Python user as built-in -modules. Using a built-in module is no different from using a module -written in Python, but obviously the author of a built-in module can -do things that cannot be implemented purely in Python. - -In particular, built-in modules can contain Python-callable functions -that call functions from particular system libraries (`wrapper -functions'), and they can define new object types. In general, if a -built-in module defines a new object type, it should also provide at -least one function that creates such objects. Attributes of such -object types are also implemented in C; they can return data -associated with the object or methods, implemented as C functions. - -For instance, an extension was created for Amoeba: it provides wrapper -functions for the basic Amoeba name server functions, and defines a -`capability' object type, whose methods are file server operations. -Another extension is a built-in module called {\tt posix}; it provides -wrappers around post UNIX system calls. Extension modules also -provide access to two different windowing/graphics interfaces: STDWIN -\cite{STDWIN} -(which connects to X11 on UNIX and to the Mac Toolbox on the -Macintosh), and the Graphics Library (GL) for Silicon Graphics -machines. - -Any function in an extension module is supposed to type-check its -arguments; the interpreter contains a convenience function to -facilitate extracting C values from arguments and type-checking them -at the same time. Returning values is also painless, using standard -functions to create Python objects from C values. - -On some systems extension modules may be dynamically loaded, thus -avoiding the need to maintain a private copy of the Python interpreter -in order to use a private extension. - -\section{A Short Description of AIL and Amoeba} - -An RPC stub generator takes an interface description as input. The -designer of a stub generator has at least two choices for the input -language: use a suitably restricted version of the target language, or -design a new language. The first solution was chosen, for instance, -by the designers of Flume, the stub generator for the Topaz -distributed operating system built at DEC SRC -\cite{Flume,Evolving}. - -Flume's one and only target language is Modula-2+ (the predecessor of -Modula-3). Modula-2+, like Modula-N for any N, has an interface -syntax that is well suited as a stub generator input language: an -interface module declares the functions that are `exported' by a -module implementation, with their parameter and return types, plus the -types and constants used for the parameters. Therefore, the input to -Flume is simply a Modula-2+ interface module. But even in this ideal -situation, an RPC stub generator needs to know things about functions -that are not stated explicitly in the interface module: for instance, -the transfer direction of VAR parameters (IN, OUT or both) is not -given. Flume solves this and other problems by a mixture of -directives hidden in comments and a convention for the names of -objects. Thus, one could say that the designers of Flume really -created a new language, even though it looks remarkably like their -target language. - -\subsection{The AIL Input Language} - -Amoeba uses C as its primary programming language. C function -declarations (at least in `Classic' C) don't specify the types of -the parameters, let alone their transfer direction. Using this as -input for a stub generator would require almost all information for -the stub generator to be hidden inside comments, which would require a -rather contorted scanner. Therefore we decided to design the input -syntax for Amoeba's stub generator `from scratch'. This gave us the -liberty to invent proper syntax not only for the transfer direction of -parameters, but also for variable-length arrays. - -On the other hand we decided not to abuse our freedom, and borrowed as -much from C as we could. For instance, AIL runs its input through the -C preprocessor, so we get macros, include files and conditional -compilation for free. AIL's type declaration syntax is a superset of -C's, so the user can include C header files to use the types declared -there as function parameter types --- which are declared using -function prototypes as in \Cpp{} or Standard C\@. It should be clear by -now that AIL's lexical conventions are also identical to C's. The -same is true for its expression syntax. - -Where does AIL differ from C, then? Function declarations in AIL are -grouped in {\em classes}. Classes in AIL are mostly intended as a -grouping mechanism: all functions implemented by a server are grouped -together in a class. Inheritance is used to form new groups by adding -elements to existing groups; multiple inheritance is supported to join -groups together. Classes can also contain constant and type -definitions, and one form of output that AIL can generate is a header -file for use by C programmers who wish to use functions from a -particular AIL class. - -Let's have a look at some (unrealistically simple) class definitions: -\begin{verbatim} -#include <amoeba.h> /* Defines `capability', etc. */ - -class standard_ops [1000 .. 1999] { - /* Operations supported by most interfaces */ - std_info(*, out char buf[size:100], out int size); - std_destroy(*); -}; -\end{verbatim} -This defines a class called `standard\_ops' whose request codes are -chosen by AIL from the range 1000-1999. Request codes are small -integers used to identify remote operations. The author of the class -must specify a range from which AIL chooses, and class authors must -make sure they avoid conflicts, e.g. by using an `assigned number -administration office'. In the example, `std\_info' will be assigned -request code 1000 and `std\_destroy' will get code 1001. There is -also an option to explicitly assign request codes, for compatibility -with servers with manually written interfaces. - -The class `standard\_ops' defines two operations, `std\_info' and -`std\_destroy'. The first parameter of each operation is a star -(`*'); this is a placeholder for a capability that must be passed when -the operation is called. The description of Amoeba below explains the -meaning and usage of capabilities; for now, it is sufficient to know -that a capability is a small structure that uniquely identifies an -object and a server or service. - -The standard operation `std\_info' has two output parameters: a -variable-size character buffer (which will be filled with a short -descriptive string of the object to which the operation is applied) -and an integer giving the length of this string. The standard -operation `std\_destroy' has no further parameters --- it just -destroys the object, if the caller has the right to do so. - -The next class is called `tty': -\begin{verbatim} -class tty [2000 .. 2099] { - inherit standard_ops; - const TTY_MAXBUF = 1000; - tty_write(*, char buf[size:TTY_MAXBUF], int size); - tty_read(*, out char buf[size:TTY_MAXBUF], out int size); -}; -\end{verbatim} -The request codes for operations defined in this class lie in the -range 2000-2099; inherited operations use the request codes already -assigned to them. The operations defined by this class are -`tty\_read' and `tty\_write', which pass variable-sized data buffers -between client and server. Class `tty' inherits class -`standard\_ops', so tty objects also support the operations -`std\_info' and `std\_destroy'. - -Only the {\em interface} for `std\_info' and `std\_destroy' is shared -between tty objects and other objects whose interface inherits -`standard\_ops'; the implementation may differ. Even multiple -implementations of the `tty' interface may exist, e.g. a driver for a -console terminal and a terminal emulator in a window. To expand on -the latter example, consider: -\begin{verbatim} -class window [2100 .. 2199] { - inherit standard_ops; - win_create(*, int x, int y, int width, int height, - out capability win_cap); - win_reconfigure(*, int x, int y, int width, int height); -}; - -class tty_emulator [2200 .. 2299] { - inherit tty, window; -}; -\end{verbatim} -Here two new interface classes are defined. -Class `window' could be used for creating and manipulating windows. -Note that `win\_create' returns a capability for the new window. -This request should probably should be sent to a generic window -server capability, or it might create a subwindow when applied to a -window object. - -Class `tty\_emulator' demonstrates the essence of multiple inheritance. -It is presumably the interface to a window-based terminal emulator. -Inheritance is transitive, so `tty\_emulator' also implicitly inherits -`standard\_ops'. -In fact, it inherits it twice: once via `tty' and once via `window'. -Since AIL class inheritance only means interface sharing, not -implementation sharing, inheriting the same class multiple times is -never a problem and has the same effect as inheriting it once. - -Note that the power of AIL classes doesn't go as far as \Cpp{}. -AIL classes cannot have data members, and there is -no mechanism for a server that implements a derived class -to inherit the implementation of the base -class --- other than copying the source code. -The syntax for class definitions and inheritance is also different. - -\subsection{Amoeba} - -The smell of `object-orientedness' that the use of classes in AIL -creates matches nicely with Amoeba's object-oriented approach to -RPC\@. In Amoeba, almost all operating system entities (files, -directories, processes, devices etc.) are implemented as {\em -objects}. Objects are managed by {\em services} and represented by -{\em capabilities}. A capability gives its holder access to the -object it represents. Capabilities are protected cryptographically -against forgery and can thus be kept in user space. A capability is a -128-bit binary string, subdivided as follows: - -% XXX Need a better version of this picture! -\begin{verbatim} - 48 24 8 48 Bits -+----------------+------------+--------+---------------+ -| Service | Object | Perm. | Check | -| port | number | bits | word | -+----------------+------------+--------+---------------+ -\end{verbatim} - -The service port is used by the RPC implementation in the Amoeba -kernel to locate a server implementing the service that manages the -object. In many cases there is a one-to-one correspondence between -servers and services (each service is implemented by exactly one -server process), but some services are replicated. For instance, -Amoeba's directory service, which is crucial for gaining access to most -other services, is implemented by two servers that listen on the same -port and know about exactly the same objects. - -The object number in the capability is used by the server receiving -the request for identifying the object to which the operation applies. -The permission bits specify which operations the holder of the capability -may apply. The last part of a capability is a 48-bit long `check -word', which is used to prevent forgery. The check word is computed -by the server based upon the permission bits and a random key per object -that it keeps secret. If you change the permission bits you must compute -the proper check word or else the server will refuse the capability. -Due to the size of the check word and the nature of the cryptographic -`one-way function' used to compute it, inverting this function is -impractical, so forging capabilities is impossible.% -\footnote{ -As computers become faster, inverting the one-way function becomes -less impractical. -Therefore, a next version of Amoeba will have 64-bit check words. -} - -A working Amoeba system is a collection of diverse servers, managing -files, directories, processes, devices etc. While most servers have -their own interface, there are some requests that make sense for some -or all object types. For instance, the {\em std\_info()} request, -which returns a short descriptive string, applies to all object types. -Likewise, {\em std\_destroy()} applies to files, directories and -processes, but not to devices. - -Similarly, different file server implementations may want to offer the -same interface for operations like {\em read()} and {\em write()} to -their clients. AIL's grouping of requests into classes is ideally -suited to describe this kind of interface sharing, and a class -hierarchy results which clearly shows the similarities between server -interfaces (not necessarily their implementations!). - -The base class of all classes defines the {\em std\_info()} request. -Most server interfaces actually inherit a derived class that also -defines {\em std\_destroy().} File servers inherit a class that -defines the common operations on files, etc. - -\subsection{How AIL Works} - -The AIL stub generator functions in three phases: -\begin{itemize} -\item -parsing, -\item -strategy determination, -\item -code generation. -\end{itemize} - -{\bf Phase one} parses the input and builds a symbol table containing -everything it knows about the classes and other definitions found in -the input. - -{\bf Phase two} determines the strategy to use for each function -declaration in turn and decides upon the request and reply message -formats. This is not a simple matter, because of various optimization -attempts. Amoeba's kernel interface for RPC requests takes a -fixed-size header and one arbitrary-size buffer. A large part of the -header holds the capability of the object to which the request is -directed, but there is some space left for a few integer parameters -whose interpretation is left up to the server. AIL tries to use these -slots for simple integer parameters, for two reasons. - -First, unlike the buffer, header fields are byte-swapped by the RPC -layer in the kernel if necessary, so it saves a few byte swapping -instructions in the user code. Second, and more important, a common -form of request transfers a few integers and one large buffer to or -from a server. The {\em read()} and {\em write()} requests of most -file servers have this form, for instance. If it is possible to place -all integer parameters in the header, the address of the buffer -parameter can be passed directly to the kernel RPC layer. While AIL -is perfectly capable of handling requests that do not fit this format, -the resulting code involves allocating a new buffer and copying all -parameters into it. It is a top priority to avoid this copying -(`marshalling') if at all possible, in order to maintain Amoeba's -famous RPC performance. - -When AIL resorts to copying parameters into a buffer, it reorders them -so that integers indicating the lengths of variable-size arrays are -placed in the buffer before the arrays they describe, since otherwise -decoding the request would be impossible. It also adds occasional -padding bytes to ensure integers are aligned properly in the buffer --- -this can speed up (un)marshalling. - -{\bf Phase three} is the code generator, or back-end. There are in -fact many different back-ends that may be called in a single run to -generate different types of output. The most important output types -are header files (for inclusion by the clients of an interface), -client stubs, and `server main loop' code. The latter decodes -incoming requests in the server. The generated code depends on the -programming language requested, and there are separate back-ends for -each supported language. - -It is important that the strategy chosen by phase two is independent -of the language requested for phase three --- otherwise the -interoperability of servers and clients written in different languages -would be compromised. - -\section{Linking AIL to Python} - -From the previous section it can be concluded that linking AIL to -Python is a matter of writing a back-end for Python. This is indeed -what we did. - -Considerable time went into the design of the back-end in order to -make the resulting RPC interface for Python fit as smoothly as -possible in Python's programming style. For instance, the issues of -parameter transfer, variable-size arrays, error handling, and call -syntax were all solved in a manner that favors ease of use in Python -rather than strict correspondence with the stubs generated for C, -without compromising network-level compatibility. - -\subsection{Mapping AIL Entities to Python} - -For each programming language that AIL is to support, a mapping must -be designed between the data types in AIL and those in that language. -Other aspects of the programming languages, such as differences in -function call semantics, must also be taken care of. - -While the mapping for C is mostly straightforward, the mapping for -Python requires a little thinking to get the best results for Python -programmers. - -\subsubsection{Parameter Transfer Direction} - -Perhaps the simplest issue is that of parameter transfer direction. -Parameters of functions declared in AIL are categorized as being of -type {\tt in}, {\tt out} or {\tt in} {\tt out} (the same distinction -as made in Ada). Python only has call-by-value parameter semantics; -functions can return multiple values as a tuple. This means that, -unlike the C back-end, the Python back-end cannot always generate -Python functions with exactly the same parameter list as the AIL -functions. - -Instead, the Python parameter list consists of all {\tt in} and {\tt -in} {\tt out} parameters, in the order in which they occur in the AIL -parameter list; similarly, the Python function returns a tuple -containing all {\tt in} {\tt out} and {\tt out} parameters. In fact -Python packs function parameters into a tuple as well, stressing the -symmetry between parameters and return value. For example, a stub -with this AIL parameter list: -\begin{verbatim} -(*, in int p1, in out int p2, in int p3, out int p4) -\end{verbatim} -will have the following parameter list and return values in Python: -\begin{verbatim} -(p1, p2, p3) -> (p2, p4) -\end{verbatim} - -\subsubsection{Variable-size Entities} - -The support for variable-size objects in AIL is strongly guided by the -limitations of C in this matter. Basically, AIL allows what is -feasible in C: functions may have variable-size arrays as parameters -(both input or output), provided their length is passed separately. -In practice this is narrowed to the following rule: for each -variable-size array parameter, there must be an integer parameter -giving its length. (An exception for null-terminated strings is -planned but not yet realized.) - -Variable-size arrays in AIL or C correspond to {\em sequences} in -Python: lists, tuples or strings. These are much easier to use than -their C counterparts. Given a sequence object in Python, it is always -possible to determine its size: the built-in function {\tt len()} -returns it. It would be annoying to require the caller of an RPC stub -with a variable-size parameter to also pass a parameter that -explicitly gives its size. Therefore we eliminate all parameters from -the Python parameter list whose value is used as the size of a -variable-size array. Such parameters are easily found: the array -bound expression contains the name of the parameter giving its size. -This requires the stub code to work harder (it has to recover the -value for size parameters from the corresponding sequence parameter), -but at least part of this work would otherwise be needed as well, to -check that the given and actual sizes match. - -Because of the symmetry in Python between the parameter list and the -return value of a function, the same elimination is performed on -return values containing variable-size arrays: integers returned -solely to tell the client the size of a returned array are not -returned explicitly to the caller in Python. - -\subsubsection{Error Handling} - -Another point where Python is really better than C is the issue of -error handling. It is a fact of life that everything involving RPC -may fail, for a variety of reasons outside the user's control: the -network may be disconnected, the server may be down, etc. Clients -must be prepared to handle such failures and recover from them, or at -least print an error message and die. In C this means that every -function returns an error status that must be checked by the caller, -causing programs to be cluttered with error checks --- or worse, -programs that ignore errors and carry on working with garbage data. - -In Python, errors are generally indicated by exceptions, which can be -handled out of line from the main flow of control if necessary, and -cause immediate program termination (with a stack trace) if ignored. -To profit from this feature, all RPC errors that may be encountered by -AIL-generated stubs in Python are turned into exceptions. An extra -value passed together with the exception is used to relay the error -code returned by the server to the handler. Since in general RPC -failures are rare, Python test programs can usually ignore exceptions ---- making the program simpler --- without the risk of occasional -errors going undetected. (I still remember the embarrassment of a -hundredfold speed improvement reported, long, long, ago, about a new -version of a certain program, which later had to be attributed to a -benchmark that silently dumped core...) - -\subsubsection{Function Call Syntax} - -Amoeba RPC operations always need a capability parameter (this is what -the `*' in the AIL function templates stands for); the service is -identified by the port field of the capability. In C, the capability -must always be the first parameter of the stub function, but in Python -we can do better. - -A Python capability is an opaque object type in its own right, which -is used, for instance, as parameter to and return value from Amoeba's -name server functions. Python objects can have methods, so it is -convenient to make all AIL-generated stubs methods of capabilities -instead of just functions. Therefore, instead of writing -\begin{verbatim} -some_stub(cap, other_parameters) -\end{verbatim} -as in C, Python programmers can write -\begin{verbatim} -cap.some_stub(other_parameters) -\end{verbatim} -This is better because it reduces name conflicts: in Python, no -confusion is possible between a stub and a local or global variable or -user-defined function with the same name. - -\subsubsection{Example} - -All the preceding principles can be seen at work in the following -example. Suppose a function is declared in AIL as follows: -\begin{verbatim} -some_stub(*, in char buf[size:1000], in int size, - out int n_done, out int status); -\end{verbatim} -In C it might be called by the following code (including declarations, -for clarity, but not initializations): -\begin{verbatim} -int err, n_done, status; -capability cap; -char buf[500]; -... -err = some_stub(&cap, buf, sizeof buf, &n_done, &status); -if (err != 0) return err; -printf("%d done; status = %d\n", n_done, status); -\end{verbatim} -Equivalent code in Python might be the following: -\begin{verbatim} -cap = ... -buf = ... -n_done, status = cap.some_stub(buf) -print n_done, 'done;', 'status =', status -\end{verbatim} -No explicit error check is required in Python: if the RPC fails, an -exception is raised so the {\tt print} statement is never reached. - -\subsection{The Implementation} - -More or less orthogonal to the issue of how to map AIL operations to -the Python language is the question of how they should be implemented. - -In principle it would be possible to use the same strategy that is -used for C: add an interface to Amoeba's low-level RPC primitives to -Python and generate Python code to marshal parameters into and out of -a buffer. However, Python's high-level data types are not well suited -for marshalling: byte-level operations are clumsy and expensive, with -the result that marshalling a single byte of data can take several -Python statements. This would mean that a large amount of code would -be needed to implement a stub, which would cost a lot of time to parse -and take up a lot of space in `compiled' form (as parse tree or pseudo -code). Execution of the marshalling code would be sluggish as well. - -We therefore chose an alternate approach, writing the marshalling in -C, which is efficient at such byte-level operations. While it is easy -enough to generate C code that can be linked with the Python -interpreter, it would obviously not stimulate the use of Python for -server testing if each change to an interface required relinking the -interpreter (dynamic loading of C code is not yet available on -Amoeba). This is circumvented by the following solution: the -marshalling is handled by a simple {\em virtual machine}, and AIL -generates instructions for this machine. An interpreter for the -machine is linked into the Python interpreter and reads its -instructions from a file written by AIL. - -The machine language for our virtual machine is dubbed {\em Stubcode}. -Stubcode is a super-specialized language. There are two sets of of -about a dozen instructions each: one set marshals Python objects -representing parameters into a buffer, the other set (similar but not -quite symmetric) unmarshals results from a buffer into Python objects. -The Stubcode interpreter uses a stack to hold Python intermediate -results. Other state elements are an Amoeba header and buffer, a -pointer indicating the current position in the buffer, and of course a -program counter. Besides (un)marshalling, the virtual machine must -also implement type checking, and raise a Python exception when a -parameter does not have the expected type. - -The Stubcode interpreter marshals Python data types very efficiently, -since each instruction can marshal a large amount of data. For -instance, a whole Python string is marshalled by a single Stubcode -instruction, which (after some checking) executes the most efficient -byte-copying loop possible --- it calls {\tt memcpy()}. - - -Construction details of the Stubcode interpreter are straightforward. -Most complications are caused by the peculiarities of AIL's strategy -module and Python's type system. By far the most complex single -instruction is the `loop' instruction, which is used to marshal -arrays. - -As an example, here is the complete Stubcode program (with spaces and -comments added for clarity) generated for the function {\tt -some\_stub()} of the example above. The stack contains pointers to -Python objects, and its initial contents is the parameter to the -function, the string {\tt buf}. The final stack contents will be the -function return value, the tuple {\tt (n\_done, status)}. The name -{\tt header} refers to the fixed size Amoeba RPC header structure. -\vspace{1em} - -{\tt -\begin{tabular}{l l l} -BufSize & 1000 & {\em Allocate RPC buffer of 1000 bytes} \\ -Dup & 1 & {\em Duplicate stack top} \\ -StringS & & {\em Replace stack top by its string size} \\ -PutI & h\_extra int32 & {\em Store top element in }header.h\_extra \\ -TStringSlt & 1000 & {\em Assert string size less than 1000} \\ -PutVS & & {\em Marshal variable-size string} \\ - & & \\ -Trans & 1234 & {\em Execute the RPC (request code 1234)} \\ - & & \\ -GetI & h\_extra int32 & {\em Push integer from} header.h\_extra \\ -GetI & h\_size int32 & {\em Push integer from} header.h\_size \\ -Pack & 2 & {\em Pack top 2 elements into a tuple} \\ -\end{tabular} -} -\vspace{1em} - -As much work as possible is done by the Python back-end in AIL, rather -than in the Stubcode interpreter, to make the latter both simple and -fast. For instance, the decision to eliminate an array size parameter -from the Python parameter list is taken by AIL, and Stubcode -instructions are generated to recover the size from the actual -parameter and to marshal it properly. Similarly, there is a special -alignment instruction (not used in the example) to meet alignment -requirements. - -Communication between AIL and the Stubcode generator is via the file -system. For each stub function, AIL creates a file in its output -directory, named after the stub with a specific suffix. This file -contains a machine-readable version of the Stubcode program for the -stub. The Python user can specify a search path containing -directories which the interpreter searches for a Stubcode file the -first time the definition for a particular stub is needed. - -The transformations on the parameter list and data types needed to map -AIL data types to Python data types make it necessary to help the -Python programmer a bit in figuring out the parameters to a call. -Although in most cases the rules are simple enough, it is sometimes -hard to figure out exactly what the parameter and return values of a -particular stub are. There are two sources of help in this case: -first, the exception contains enough information so that the user can -figure what type was expected; second, AIL's Python back-end -optionally generates a human-readable `interface specification' file. - -\section{Conclusion} - -We have succeeded in creating a useful extension to Python that -enables Amoeba server writers to test and experiment with their server -in a much more interactive manner. We hope that this facility will -add to the popularity of AIL amongst Amoeba programmers. - -Python's extensibility was proven convincingly by the exercise -(performed by the second author) of adding the Stubcode interpreter to -Python. Standard data abstraction techniques are used to insulate -extension modules from details of the rest of the Python interpreter. -In the case of the Stubcode interpreter this worked well enough that -it survived a major overhaul of the main Python interpreter virtually -unchanged. - -On the other hand, adding a new back-end to AIL turned out to be quite -a bit of work. One problem, specific to Python, was to be expected: -Python's variable-size data types differ considerably from the -C-derived data model that AIL favors. Two additional problems we -encountered were the complexity of the interface between AIL's second -and third phases, and a number of remaining bugs in the second phase -that surfaced when the implementation of the Python back-end was -tested. The bugs have been tracked down and fixed, but nothing -has been done about the complexity of the interface. - -\subsection{Future Plans} - -AIL's C back-end generates server main loop code as well as client -stubs. The Python back-end currently only generates client stubs, so -it is not yet possible to write servers in Python. While it is -clearly more important to be able to use Python as a client than as a -server, the ability to write server prototypes in Python would be a -valuable addition: it allows server designers to experiment with -interfaces in a much earlier stage of the design, with a much smaller -programming effort. This makes it possible to concentrate on concepts -first, before worrying about efficient implementation. - -The unmarshalling done in the server is almost symmetric with the -marshalling in the client, and vice versa, so relative small -extensions to the Stubcode virtual machine will allow its use in a -server main loop. We hope to find the time to add this feature to a -future version of Python. - -\section{Availability} - -The Python source distribution is available to Internet users by -anonymous ftp to site {\tt ftp.cwi.nl} [IP address 192.16.184.180] -from directory {\tt /pub}, file name {\tt python*.tar.Z} (where the -{\tt *} stands for a version number). This is a compressed UNIX tar -file containing the C source and \LaTeX documentation for the Python -interpreter. It includes the Python library modules and the {\em -Stubcode} interpreter, as well as many example Python programs. Total -disk space occupied by the distribution is about 3 Mb; compilation -requires 1-3 Mb depending on the configuration built, the compile -options, etc. - -\bibliographystyle{plain} - -\bibliography{quabib} - -\end{document} diff --git a/Doc/quabib.bib b/Doc/quabib.bib deleted file mode 100644 index 97b93f6..0000000 --- a/Doc/quabib.bib +++ /dev/null @@ -1,139 +0,0 @@ -@inproceedings{bult:usenix91, - title = "A Structure for Transportable, Dynamic Multimedia Documents", - author = "Dick C.A. Bulterman - and Guido van Rossum - and Robert van Liere", - booktitle = "Proceedings of the 1991 Summer USENIX Conference", - publisher = "The USENIX Association", - year = "1991", -} - -@techreport{bult:gogh90, - title = "The {CWI} van {G}ogh Multimedia Research Project: Goals - and Objectives", - author = "Dick C.A. Bulterman", - institution = "CWI", - year = "1990", - number = "CST-90.1004", -} - -@article{Amoeba:IEEE, - title = "{A}moeba: A Distributed Operating System for the 1990s", - author = "S.J. Mullender - and G. van Rossum - and A.S. Tanenbaum - and R. van Renesse - and J.M. van Staveren", - journal = "IEEE Computer Magazine", - volume = "23", - number = "5", - month = "May", - year = "1990", - pages = "44-53", -} - -@article{Amoeba:CACM, - title = "Experiences with the {A}moeba Distributed Operating System", - author = "A.S. Tanenbaum -and R. van Renesse -and J.M. van Staveren -and G.J. Sharp -and S.J. Mullender -and A.J. Jansen -and G. van Rossum", -journal = "Communications of the ACM", -volume = "33", -number = "12", -month = "December", -year ="1990", -pages = "46-63", -} - -@inproceedings{AIL, -title = "{AIL} --- A Class-Oriented Stub Generator for {A}moeba", -author = "G. van Rossum", -editor = {E W. Schr\"{o}der-Preikschat -and E. W. Zimmer}, -booktitle = "Workshop on Progress in Distributed Operating Systems and Distributed Systems Management", -publisher = "Springer Verlag", -series = "Lecture Notes in Computer Science", -volume = "433", -year = "1990", -pages = "13-21", -} - -@techreport{STDWIN, -title = "{STDWIN} --- A Standard Window System Interface", -author = "G. van Rossum", -number = "CS-R8817", -institution = "CWI", -address = "Amsterdam", -month = "April", -year = "1988", -} - -@book{ABC, -title = "{ABC} Programmer's Handbook", -author = "Leo Geurts -and Lambert Meertens -and Steven Pemberton", -publisher = "Prentice-Hall", -address = "London", -year = "1990", -note = "ISBN 0-13-000027-2", -} - -@manual{Flume, -title = "{F}lume --- Remote Procedure Call Stub Generator for {M}odula-2+", -author = "A.D. Birrell -and E.D. Lazowska -and E. Wobber", -organization = "DEC SRC", -address = "Palo Alto, CA", -year = "1987", -note = "(Topaz manual page)", -} - -@techreport{Evolving, -title = "Evolving the {UNIX} System Interface to Support Multithreaded Programs", -author = "P.R. McJones -and G.F. Swart", -number = "21", -institution = "DEC SRC", -address = "Palo Alto, CA", -month = "September", -year = "1987", -} - -@inproceedings{Tcl, -title = "{T}cl: an Embeddable Command Language", -author = "John K. Ousterhout", -booktitle = "Proceedings of the Winter 1990 USENIX Conference", -publisher = "USENIX Association", -address = "Washington, DC", -month = "January", -year = "1990", -pages = "133-146", -} - -@article{RPC, -title = "Implementing Remote Procedure Calls", -author = "A. D. Birrell -and B. J. Nelson", -journal = "ACM Transactions on Computer Systems", -volume = "2", -number = "1", -month = "February", -year = "1984", -pages = "39-59", -} - -@techreport{Modula-3, -title = "{M}odula-3 Report (revised)", -author = "Luca Cardelli et al.", -number = "52", -institution = "DEC SRC", -address = "Palo Alto, CA", -month = "November", -year = "1989", -} |