abstract.h: remove long outdated comment
Issue #28838: The documentation is of the Python C API is more complete and more up to date than this old comment. Removal suggested by Antoine Pitrou.
This commit is contained in:
Victor Stinner
parent
af324157c6
commit
b6522d0f77
|
|
@ -1,127 +1,11 @@
|
|||
/* Abstract Object Interface (many thanks to Jim Fulton) */
|
||||
|
||||
#ifndef Py_ABSTRACTOBJECT_H
|
||||
#define Py_ABSTRACTOBJECT_H
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/* Abstract Object Interface (many thanks to Jim Fulton) */
|
||||
|
||||
/*
|
||||
PROPOSAL: A Generic Python Object Interface for Python C Modules
|
||||
|
||||
Problem
|
||||
|
||||
Python modules written in C that must access Python objects must do
|
||||
so through routines whose interfaces are described by a set of
|
||||
include files. Unfortunately, these routines vary according to the
|
||||
object accessed. To use these routines, the C programmer must check
|
||||
the type of the object being used and must call a routine based on
|
||||
the object type. For example, to access an element of a sequence,
|
||||
the programmer must determine whether the sequence is a list or a
|
||||
tuple:
|
||||
|
||||
if (is_tupleobject(o))
|
||||
e = gettupleitem(o, i)
|
||||
else if (is_listitem(o))
|
||||
e = getlistitem(o, i)
|
||||
|
||||
If the programmer wants to get an item from another type of object
|
||||
that provides sequence behavior, there is no clear way to do it
|
||||
correctly.
|
||||
|
||||
The persistent programmer may peruse object.h and find that the
|
||||
_typeobject structure provides a means of invoking up to (currently
|
||||
about) 41 special operators. So, for example, a routine can get an
|
||||
item from any object that provides sequence behavior. However, to
|
||||
use this mechanism, the programmer must make their code dependent on
|
||||
the current Python implementation.
|
||||
|
||||
Also, certain semantics, especially memory management semantics, may
|
||||
differ by the type of object being used. Unfortunately, these
|
||||
semantics are not clearly described in the current include files.
|
||||
An abstract interface providing more consistent semantics is needed.
|
||||
|
||||
Proposal
|
||||
|
||||
I propose the creation of a standard interface (with an associated
|
||||
library of routines and/or macros) for generically obtaining the
|
||||
services of Python objects. This proposal can be viewed as one
|
||||
components of a Python C interface consisting of several components.
|
||||
|
||||
From the viewpoint of C access to Python services, we have (as
|
||||
suggested by Guido in off-line discussions):
|
||||
|
||||
- "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. (Error handling must also
|
||||
be part of this API.)
|
||||
|
||||
- "Abstract objects layer": which is the subject of this proposal.
|
||||
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.
|
||||
|
||||
- "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 provided with the
|
||||
Python distributions.
|
||||
|
||||
From the point of view of Python accessing services provided by C
|
||||
modules:
|
||||
|
||||
- "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.
|
||||
|
||||
- "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.
|
||||
|
||||
This proposal is a "first-cut" that is intended to spur
|
||||
discussion. See especially the lists of notes.
|
||||
|
||||
The Python C object interface will provide 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 an 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.
|
||||
|
||||
Memory Management
|
||||
|
||||
For all of the functions described in this proposal, 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.
|
||||
|
||||
Note that the behavior mentioned here is different from the current
|
||||
behavior for some objects (e.g. lists and tuples) when certain
|
||||
type-specific routines are called directly (e.g. setlistitem). The
|
||||
proposed abstraction layer will provide a consistent memory
|
||||
management interface, correcting for inconsistent behavior for some
|
||||
built-in types.
|
||||
|
||||
Protocols
|
||||
*/
|
||||
|
||||
|
||||
/* === Object Protocol ================================================== */
|
||||
|
||||
/* Implemented elsewhere:
|
||||
|
|
|
|||
Loading…
Reference in New Issue