--- rest25/extending/newtypes.rst	2008-12-19 16:58:05.000000000 +0900
+++ rest262/extending/newtypes.rst	2009-04-05 05:01:41.000000000 +0900
@@ -38,27 +38,26 @@
 just contains the refcount and a pointer to the object's "type object".  This is
 where the action is; the type object determines which (C) functions get called
 when, for instance, an attribute gets looked up on an object or it is multiplied
 by another object.  These C functions are called "type methods" to distinguish
 them from things like ``[].append`` (which we call "object methods").
 
 So, if you want to define a new object type, you need to create a new type
 object.
 
 This sort of thing can only be explained by example, so here's a minimal, but
 complete, module that defines a new type:
 
+.. literalinclude:: ../includes/noddy.c
 
-.. include:: ../includes/noddy.c
-   :literal:
 
 Now that's quite a bit to take in at once, but hopefully bits will seem familiar
 from the last chapter.
 
 The first bit that will be new is::
 
    typedef struct {
        PyObject_HEAD
    } noddy_NoddyObject;
 
 This is what a Noddy object will contain---in this case, nothing more than every
 Python object contains, namely a refcount and a pointer to a type object.  These
@@ -224,42 +223,39 @@
    from distutils.core import setup, Extension
    setup(name="noddy", version="1.0",
          ext_modules=[Extension("noddy", ["noddy.c"])])
 
 in a file called :file:`setup.py`; then typing ::
 
    $ python setup.py build
 
 at a shell should produce a file :file:`noddy.so` in a subdirectory; move to
 that directory and fire up Python --- you should be able to ``import noddy`` and
 play around with Noddy objects.
 
-.. % $ <-- bow to font-lock  ;-(
-
 That wasn't so hard, was it?
 
 Of course, the current Noddy type is pretty uninteresting. It has no data and
 doesn't do anything. It can't even be subclassed.
 
 
 Adding data and methods to the Basic example
 --------------------------------------------
 
 Let's expend the basic example to add some data and methods.  Let's also make
 the type usable as a base class. We'll create a new module, :mod:`noddy2` that
 adds these capabilities:
 
+.. literalinclude:: ../includes/noddy2.c
 
-.. include:: ../includes/noddy2.c
-   :literal:
 
 This version of the module has a number of changes.
 
 We've added an extra include::
 
    #include "structmember.h"
 
 This include provides declarations that we use to handle attributes, as
 described a bit later.
 
 The name of the :class:`Noddy` object structure has been shortened to
 :class:`Noddy`.  The type object name has been shortened to :class:`NoddyType`.
@@ -423,27 +419,25 @@
 :attr:`first` member.  To be paranoid and protect ourselves against this
 possibility, we almost always reassign members before decrementing their
 reference counts.  When don't we have to do this?
 
 * when we absolutely know that the reference count is greater than 1
 
 * when we know that deallocation of the object [#]_ will not cause any calls
   back into our type's code
 
 * when decrementing a reference count in a :attr:`tp_dealloc` handler when
   garbage-collections is not supported [#]_
 
-*
-
-We want to want to expose our instance variables as attributes. There are a
+We want to expose our instance variables as attributes. There are a
 number of ways to do that. The simplest way is to define member definitions::
 
    static PyMemberDef Noddy_members[] = {
        {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
         "first name"},
        {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
         "last name"},
        {"number", T_INT, offsetof(Noddy, number), 0,
         "noddy number"},
        {NULL}  /* Sentinel */
    };
 
@@ -550,27 +544,26 @@
             ])
 
 
 Providing finer control over data attributes
 --------------------------------------------
 
 In this section, we'll provide finer control over how the :attr:`first` and
 :attr:`last` attributes are set in the :class:`Noddy` example. In the previous
 version of our module, the instance variables :attr:`first` and :attr:`last`
 could be set to non-string values or even deleted. We want to make sure that
 these attributes always contain strings.
 
+.. literalinclude:: ../includes/noddy3.c
 
-.. include:: ../includes/noddy3.c
-   :literal:
 
 To provide greater control, over the :attr:`first` and :attr:`last` attributes,
 we'll use custom getter and setter functions.  Here are the functions for
 getting and setting the :attr:`first` attribute::
 
    Noddy_getfirst(Noddy *self, void *closure)
    {
        Py_INCREF(self->first);
        return self->first;
    }
 
    static int
@@ -614,25 +607,25 @@
         NULL},
        {"last",
         (getter)Noddy_getlast, (setter)Noddy_setlast,
         "last name",
         NULL},
        {NULL}  /* Sentinel */
    };
 
 and register it in the :attr:`tp_getset` slot::
 
    Noddy_getseters,           /* tp_getset */
 
-to register out attribute getters and setters.
+to register our attribute getters and setters.
 
 The last item in a :ctype:`PyGetSetDef` structure is the closure mentioned
 above. In this case, we aren't using the closure, so we just pass *NULL*.
 
 We also remove the member definitions for these attributes::
 
    static PyMemberDef Noddy_members[] = {
        {"number", T_INT, offsetof(Noddy, number), 0,
         "noddy number"},
        {NULL}  /* Sentinel */
    };
 
@@ -696,32 +689,31 @@
 Fortunately, Python's cyclic-garbage collector will eventually figure out that
 the list is garbage and free it.
 
 In the second version of the :class:`Noddy` example, we allowed any kind of
 object to be stored in the :attr:`first` or :attr:`last` attributes. [#]_ This
 means that :class:`Noddy` objects can participate in cycles::
 
    >>> import noddy2
    >>> n = noddy2.Noddy()
    >>> l = [n]
    >>> n.first = l
 
-This is pretty silly, but it gives us an excuse to add support for the cyclic-
-garbage collector to the :class:`Noddy` example.  To support cyclic garbage
-collection, types need to fill two slots and set a class flag that enables these
-slots:
+This is pretty silly, but it gives us an excuse to add support for the
+cyclic-garbage collector to the :class:`Noddy` example.  To support cyclic
+garbage collection, types need to fill two slots and set a class flag that
+enables these slots:
 
+.. literalinclude:: ../includes/noddy4.c
 
-.. include:: ../includes/noddy4.c
-   :literal:
 
 The traversal method provides access to subobjects that could participate in
 cycles::
 
    static int
    Noddy_traverse(Noddy *self, visitproc visit, void *arg)
    {
        int vret;
 
        if (self->first) {
            vret = visit(self->first, arg);
            if (vret != 0)
@@ -809,38 +801,126 @@
        return 0;
    }
 
 Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
 
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
 
 That's pretty much it.  If we had written custom :attr:`tp_alloc` or
 :attr:`tp_free` slots, we'd need to modify them for cyclic-garbage collection.
 Most extensions will use the versions automatically provided.
 
 
+Subclassing other types
+-----------------------
+
+It is possible to create new extension types that are derived from existing
+types. It is easiest to inherit from the built in types, since an extension can
+easily use the :class:`PyTypeObject` it needs. It can be difficult to share
+these :class:`PyTypeObject` structures between extension modules.
+
+In this example we will create a :class:`Shoddy` type that inherits from the
+builtin :class:`list` type. The new type will be completely compatible with
+regular lists, but will have an additional :meth:`increment` method that
+increases an internal counter. ::
+
+   >>> import shoddy
+   >>> s = shoddy.Shoddy(range(3))
+   >>> s.extend(s)
+   >>> print len(s)
+   6
+   >>> print s.increment()
+   1
+   >>> print s.increment()
+   2
+
+.. literalinclude:: ../includes/shoddy.c
+
+
+As you can see, the source code closely resembles the :class:`Noddy` examples in
+previous sections. We will break down the main differences between them. ::
+
+   typedef struct {
+       PyListObject list;
+       int state;
+   } Shoddy;
+
+The primary difference for derived type objects is that the base type's object
+structure must be the first value. The base type will already include the
+:cfunc:`PyObject_HEAD` at the beginning of its structure.
+
+When a Python object is a :class:`Shoddy` instance, its *PyObject\** pointer can
+be safely cast to both *PyListObject\** and *Shoddy\**. ::
+
+   static int
+   Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
+   {
+       if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
+          return -1;
+       self->state = 0;
+       return 0;
+   }
+
+In the :attr:`__init__` method for our type, we can see how to call through to
+the :attr:`__init__` method of the base type.
+
+This pattern is important when writing a type with custom :attr:`new` and
+:attr:`dealloc` methods. The :attr:`new` method should not actually create the
+memory for the object with :attr:`tp_alloc`, that will be handled by the base
+class when calling its :attr:`tp_new`.
+
+When filling out the :cfunc:`PyTypeObject` for the :class:`Shoddy` type, you see
+a slot for :cfunc:`tp_base`. Due to cross platform compiler issues, you can't
+fill that field directly with the :cfunc:`PyList_Type`; it can be done later in
+the module's :cfunc:`init` function. ::
+
+   PyMODINIT_FUNC
+   initshoddy(void)
+   {
+       PyObject *m;
+
+       ShoddyType.tp_base = &PyList_Type;
+       if (PyType_Ready(&ShoddyType) < 0)
+           return;
+
+       m = Py_InitModule3("shoddy", NULL, "Shoddy module");
+       if (m == NULL)
+           return;
+
+       Py_INCREF(&ShoddyType);
+       PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
+   }
+
+Before calling :cfunc:`PyType_Ready`, the type structure must have the
+:attr:`tp_base` slot filled in. When we are deriving a new type, it is not
+necessary to fill out the :attr:`tp_alloc` slot with :cfunc:`PyType_GenericNew`
+-- the allocate function from the base type will be inherited.
+
+After that, calling :cfunc:`PyType_Ready` and adding the type object to the
+module is the same as with the basic :class:`Noddy` examples.
+
+
 .. _dnt-type-methods:
 
 Type Methods
 ============
 
 This section aims to give a quick fly-by on the various type methods you can
 implement and what they do.
 
 Here is the definition of :ctype:`PyTypeObject`, with some fields only used in
 debug builds omitted:
 
+.. literalinclude:: ../includes/typestruct.h
 
-.. include:: ../includes/typestruct.h
-   :literal:
 
 Now that's a *lot* of methods.  Don't worry too much though - if you have a type
 you want to define, the chances are very good that you will only implement a
 handful of these.
 
 As you probably expect by now, we're going to go over this and give more
 information about the various handlers.  We won't go in the order they are
 defined in the structure, because there is a lot of historical baggage that
 impacts the ordering of the fields; be sure your type initialization keeps the
 fields in the right order!  It's often easiest to find an example that includes
 all the fields you need (even if they're initialized to ``0``) and then change
 the values to suit your new type. ::
@@ -1058,69 +1138,69 @@
 attributes simple?  There are only a couple of conditions that must be met:
 
 #. The name of the attributes must be known when :cfunc:`PyType_Ready` is
    called.
 
 #. No special processing is needed to record that an attribute was looked up or
    set, nor do actions need to be taken based on the value.
 
 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 :cfunc:`PyType_Ready` is called, it uses three tables referenced by the
-type object to create *descriptors* which are placed in the dictionary of the
+type object to create :term:`descriptor`\s 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 :attr:`tp_getattro` and :attr:`tp_setattro` fields *NULL* as
 well, allowing the base type to handle attributes.
 
 The tables are declared as three fields of the type object::
 
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
 
 If :attr:`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::
 
    typedef struct PyMethodDef {
        char        *ml_name;       /* method name */
        PyCFunction  ml_meth;       /* implementation function */
-       int	         ml_flags;      /* flags */
+       int          ml_flags;      /* flags */
        char        *ml_doc;        /* docstring */
    } PyMethodDef;
 
 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
 :attr:`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::
 
    typedef struct PyMemberDef {
        char *name;
        int   type;
        int   offset;
        int   flags;
        char *doc;
    } PyMemberDef;
 
-For each entry in the table, a descriptor will be constructed and added to the
+For each entry in the table, a :term:`descriptor` will be constructed and added to the
 type which will be able to extract a value from the instance structure.  The
 :attr:`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 :attr:`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.
 
 +---------------------------+----------------------------------------------+
@@ -1144,34 +1224,32 @@
    single: WRITE_RESTRICTED
    single: RESTRICTED
 
 An interesting advantage of using the :attr:`tp_members` table to build
 descriptors that are used at runtime is that any attribute defined this way can
 have an associated doc string 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 doc string using its :attr:`__doc__` attribute.
 
 As with the :attr:`tp_methods` table, a sentinel entry with a :attr:`name` value
 of *NULL* is required.
 
-.. % XXX Descriptors need to be explained in more detail somewhere, but
-.. % not here.
-.. % 
-.. % Descriptor objects have two handler functions which correspond to
-.. % the \member{tp_getattro} and \member{tp_setattro} handlers.  The
-.. % \method{__get__()} handler is a function which is passed the
-.. % descriptor, instance, and type objects, and returns the value of the
-.. % attribute, or it returns \NULL{} and sets an exception.  The
-.. % \method{__set__()} handler is passed the descriptor, instance, type,
-.. % and new value;
+.. XXX Descriptors need to be explained in more detail somewhere, but not here.
+
+   Descriptor objects have two handler functions which correspond to the
+   \member{tp_getattro} and \member{tp_setattro} handlers.  The
+   \method{__get__()} handler is a function which is passed the descriptor,
+   instance, and type objects, and returns the value of the attribute, or it
+   returns \NULL{} and sets an exception.  The \method{__set__()} handler is
+   passed the descriptor, instance, type, and new value;
 
 
 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
@@ -1258,27 +1336,26 @@
        }
        else {
            result = 0;
        }
        return result;
    }
 
 
 Abstract Protocol Support
 -------------------------
 
 Python supports a variety of *abstract* 'protocols;' the specific interfaces
-provided to use these interfaces are documented in the Python/C API Reference
-Manual (XXX reference: ../api/api.html) in the chapter "Abstract Objects Layer
-(XXX reference: ../api/abstract.html)."
+provided to use these interfaces are documented in :ref:`abstract`.
+
 
 A number of these abstract interfaces were defined early in the development of
 the Python implementation.  In particular, the number, mapping, and sequence
 protocols have been part of Python since the beginning.  Other protocols have
 been added over time.  For protocols which depend on several handler routines
 from the type implementation, the older protocols have been defined as optional
 blocks of handlers referenced by the type object.  For newer protocols there are
 additional slots in the main type object, with a flag bit being set to indicate
 that the slots are present and should be checked by the interpreter.  (The flag
 bit does not indicate that the slot values are non-*NULL*. The flag may be set
 to indicate the presence of a slot, but a slot may still be unfilled.) ::
 
@@ -1489,18 +1566,18 @@
 .. [#] This is true when we know that the object is a basic type, like a string or a
    float.
 
 .. [#] We relied on this in the :attr:`tp_dealloc` handler in this example, because our
    type doesn't support garbage collection. Even if a type supports garbage
    collection, there are calls that can be made to "untrack" the object from
    garbage collection, however, these calls are advanced and not covered here.
 
 .. [#] We now know that the first and last members are strings, so perhaps we could be
    less careful about decrementing their reference counts, however, we accept
    instances of string subclasses. Even though deallocating normal strings won't
    call back into our objects, we can't guarantee that deallocating an instance of
-   a string subclass won't. call back into out objects.
+   a string subclass won't call back into our objects.
 
 .. [#] Even in the third version, we aren't guaranteed to avoid cycles.  Instances of
    string subclasses are allowed and string subclasses could allow cycles even if
    normal strings don't.
 
