For every object which can support attributes, the corresponding type

must provide the functions that control how the attributes are

resolved. There needs to be a function which can retrieve attributes

(if any are defined), and another to set attributes (if setting

attributes is allowed). Removing an attribute is a special case, for

which the new value passed to the handler is \NULL.

Python supports two pairs of attribute handlers; a type that supports

attributes only needs to implement the functions for one pair. The

difference is that one pair takes the name of the attribute as a

\ctype{char*}, while the other accepts a \ctype{PyObject*}. Each type

can use whichever pair makes more sense for the implementation's

convenience.

If accessing attributes of an object is always a simple operation

(this will be explained shortly), there are generic implementations

which can be used to provide the \ctype{PyObject*} version of the

attribute management functions. The actual need for type-specific

attribute handlers almost completely disappeared starting with Python

2.2, though there are many examples which have not been updated to use

some of the new generic mechanism that is available.

\subsubsection{Generic Attribute Management}

\versionadded{2.2}

Most extension types only use \emph{simple} attributes. So, what

makes the attributes simple? There are only a couple of conditions

that must be met:

\begin{enumerate}

\item The name of the attributes must be known when

\cfunction{PyType_Ready()} is called.

\item No special processing is need to record that an attribute

was looked up or set, nor do actions need to be taken based

on the value.

\end{enumerate}

Note that this list does not place any restrictions on the values of

the attributes, when the values are computed, or how relevant data is

stored.

When \cfunction{PyType_Ready()} is called, it uses three tables

referenced by the type object to create \emph{descriptors} which are

placed in the dictionary of the type object. Each descriptor controls

access to one attribute of the instance object. Each of the tables is

optional; if all three are \NULL, instances of the type will only have

attributes that are inherited from their base type, and should leave

the \member{tp_getattro} and \member{tp_setattro} fields \NULL{} as

well, allowing the base type to handle attributes.

The tables are declared as three fields of the type object:

\begin{verbatim}

\end{verbatim}

If \member{tp_methods} is not \NULL, it must refer to an array of

\ctype{PyMethodDef} structures. Each entry in the table is an

instance of this structure:

\begin{verbatim}

\end{verbatim}

One entry should be defined for each method provided by the type; no

entries are needed for methods inherited from a base type. One

additional entry is needed at the end; it is a sentinel that marks the

end of the array. The \member{ml_name} field of the sentinel must be

\NULL.

XXX Need to refer to some unified discussion of the structure fields,

shared with the next section.

The second table is used to define attributes which map directly to

data stored in the instance. A variety of primitive C types are

supported, and access may be read-only or read-write. The structures

in the table are defined as:

\begin{verbatim}

\end{verbatim}

For each entry in the table, a descriptor will be constructed and

added to the type which will be able to extract a value from the

instance structure. The \member{type} field should contain one of the

type codes defined in the \file{structmember.h} header; the value will

be used to determine how to convert Python values to and from C

values. The \member{flags} field is used to store flags which control

how the attribute can be accessed.

XXX Need to move some of this to a shared section!

The following flag constants are defined in \file{structmember.h};

they may be combined using bitwise-OR.

\begin{tableii}{l|l}{constant}{Constant}{Meaning}

\lineii{READONLY \ttindex{READONLY}}

{Never writable.}

\lineii{RO \ttindex{RO}}

{Shorthand for \constant{READONLY}.}

\lineii{READ_RESTRICTED \ttindex{READ_RESTRICTED}}

{Not readable in restricted mode.}

\lineii{WRITE_RESTRICTED \ttindex{WRITE_RESTRICTED}}

{Not writable in restricted mode.}

\lineii{RESTRICTED \ttindex{RESTRICTED}}

{Not readable or writable in restricted mode.}

\end{tableii}

An interesting advantage of using the \member{tp_members} table to

build descriptors that are used at runtime is that any attribute

defined this way can have an associated docstring simply by providing

the text in the table. An application can use the introspection API

to retrieve the descriptor from the class object, and get the

docstring using its \member{__doc__} attribute.

As with the \member{tp_methods} table, a sentinel entry with a

\member{name} value of \NULL{} is required.

\subsubsection{Type-specific Attribute Management}

For simplicity, only the \ctype{char*} version will be demonstrated

here; the type of the name parameter is the only difference between

the \ctype{char*} and \ctype{PyObject*} flavors of the interface.

This example effectively does the same thing as the generic example

above, but does not use the generic support added in Python 2.2. The

value in showing this is two-fold: it demonstrates how basic attribute

management can be done in a way that is portable to older versions of

Python, and explains how the handler functions are called, so that if

you do need to extend their functionality, you'll understand what

needs to be done.

The \member{tp_getattr} handler is called when the object requires an

function that returns the result of a lookup in that table. The

method table uses the same structure as the \member{tp_methods} field

of the type object.