Skip to content

Z
Zope
Commit 89994a14 authored by Andreas Jung's avatar Andreas Jung
Browse files
Options

updated HTML reference files to STXNG

parent 5021daee
Show whitespace changes
Inline Side-by-side
Showing with 392 additions and 618 deletions
lib/python/StructuredText/regressions/Acquisition.ref
View file @ 89994a14
<html>
<head>
<title>Acquisition</title>
</head>
<body>
<h1>Acquisition</h1> <h1>Acquisition</h1>
<p> <a href="COPYRIGHT.html">Copyright (C) 1996-1998, Digital Creations</a>.</p> <p> <a href="COPYRIGHT.html">Copyright (C) 1996-1998, Digital Creations</a>.</p>
<p> Acquisition <a href="#1">[1]</a> is a mechanism that allows objects to obtain <p> Acquisition <a href="#1">[1]</a> is a mechanism that allows objects to obtain
attributes from their environment. It is similar to inheritence, attributes from their environment. It is similar to inheritence,
except that, rather than traversing an inheritence hierarchy except that, rather than traversing an inheritence hierarchy
to obtain attributes, a containment hierarchy is traversed.</p> to obtain attributes, a containment hierarchy is traversed.</p>
<p> The <a href="ExtensionClass.html">ExtensionClass</a>. release includes mix-in <p> The <a href="ExtensionClass.html">ExtensionClass</a>. release includes mix-in
extension base classes that can be used to add acquisition as a extension base classes that can be used to add acquisition as a
feature to extension subclasses. These mix-in classes use the feature to extension subclasses. These mix-in classes use the
context-wrapping feature of ExtensionClasses to implement context-wrapping feature of ExtensionClasses to implement
acquisition. Consider the following example:</p> acquisition. Consider the following example:
<PRE> <pre>
import ExtensionClass, Acquisition import ExtensionClass, Acquisition
class C(ExtensionClass.Base): class C(ExtensionClass.Base):
...@@ -35,17 +38,15 @@ ...@@ -35,17 +38,15 @@
d.a.report() # prints 'green' d.a.report() # prints 'green'
a.report() # raises an attribute error a.report() # raises an attribute error
</pre>
</PRE> </p>
<p> The class <code>A</code> inherits acquisition behavior from <p> The class <code>A</code> inherits acquisition behavior from
<code>Acquisition.Implicit</code>. The object, <code>a</code>, "has" the color of <code>Acquisition.Implicit</code>. The object, <code>a</code>, "has" the color of
objects <code>c</code> and <code>d</code> when it is accessed through them, but it objects <code>c</code> and <code>d</code> when it is accessed through them, but it
has no color by itself. The object <code>a</code> obtains attributes has no color by itself. The object <code>a</code> obtains attributes
from it's environment, where it's environment is defined by from it's environment, where it's environment is defined by
the access path used to reach <code>a</code>.</p> the access path used to reach <code>a</code>.</p>
<h2> Acquisition wrappers</h2>
<h2>Acquisition wrappers</h2>
<p> When an object that supports acquisition is accessed through <p> When an object that supports acquisition is accessed through
an extension class instance, a special object, called an an extension class instance, a special object, called an
acquisition wrapper, is returned. In the example above, the acquisition wrapper, is returned. In the example above, the
...@@ -53,133 +54,105 @@ ...@@ -53,133 +54,105 @@
contains references to both <code>c</code> and <code>a</code>. It is this wrapper contains references to both <code>c</code> and <code>a</code>. It is this wrapper
that performs attribute lookup in <code>c</code> when an attribute that performs attribute lookup in <code>c</code> when an attribute
cannot be found in <code>a</code>.</p> cannot be found in <code>a</code>.</p>
<p> Aquisition wrappers provide access to the wrapped objects <p> Aquisition wrappers provide access to the wrapped objects
through the attributes <code>aq_parent</code>, <code>aq_self</code>, <code>aq_base</code>. through the attributes 'aq<u>parent', 'aq</u>self', <code>aq_base</code>.
In the example above, the expressions:</p> In the example above, the expressions:
<PRE> <pre>
'c.a.aq_parent is c' 'c.a.aq_parent is c'
</pre>
</PRE> </p>
<p> and:
<p> and:</p> <pre>
<PRE>
'c.a.aq_self is a' 'c.a.aq_self is a'
</pre>
</PRE> </p>
<p> both evaluate to true, but the expression:
<p> both evaluate to true, but the expression:</p> <pre>
<PRE>
'c.a is a' 'c.a is a'
</pre>
</PRE> </p>
<p> evaluates to false, because the expression <code>c.a</code> evaluates <p> evaluates to false, because the expression <code>c.a</code> evaluates
to an acquisition wrapper around <code>c</code> and <code>a</code>, not <code>a</code> itself.</p> to an acquisition wrapper around <code>c</code> and <code>a</code>, not <code>a</code> itself.</p>
<p> The attribute 'aq<u>base' is similar to 'aq</u>self'. Wrappers may be
<p> The attribute <code>aq_base</code> is similar to <code>aq_self</code>. Wrappers may be nested and 'aq<u>self' may be a wrapped object. The 'aq</u>base'
nested and <code>aq_self</code> may be a wrapped object. The <code>aq_base</code>
attribute is the underlying object with all wrappers removed.</p> attribute is the underlying object with all wrappers removed.</p>
<h2> Acquisition Control</h2>
<h2>Acquisition Control</h2>
<p> Two styles of acquisition are supported in the current <p> Two styles of acquisition are supported in the current
ExtensionClass release, implicit and explicit aquisition.</p> ExtensionClass release, implicit and explicit aquisition.</p>
<h3> Implicit acquisition</h3>
<h3>Implicit acquisition</h3>
<p> Implicit acquisition is so named because it searches for <p> Implicit acquisition is so named because it searches for
attributes from the environment automatically whenever an attributes from the environment automatically whenever an
attribute cannot be obtained directly from an object or attribute cannot be obtained directly from an object or
through inheritence.</p> through inheritence.</p>
<p> An attribute may be implicitly acquired if it's name does <p> An attribute may be implicitly acquired if it's name does
not begin with an underscore, <code>_</code>.</p> not begin with an underscore, <code>_</code>.</p>
<p> To support implicit acquisition, an object should inherit <p> To support implicit acquisition, an object should inherit
from the mix-in class <code>Acquisition.Implicit</code>.</p> from the mix-in class <code>Acquisition.Implicit</code>.</p>
<h3> Explicit Acquisition</h3>
<h3>Explicit Acquisition</h3>
<p> When explicit acquisition is used, attributes are not <p> When explicit acquisition is used, attributes are not
automatically obtained from the environment. Instead, the automatically obtained from the environment. Instead, the
method <code>aq_aquire</code> must be used, as in:</p> method <code>aq_aquire</code> must be used, as in:
<PRE> <pre>
print c.a.aq_acquire('color') print c.a.aq_acquire('color')
</pre>
</PRE> </p>
<p> To support explicit acquisition, an object should inherit <p> To support explicit acquisition, an object should inherit
from the mix-in class <code>Acquisition.Explicit</code>.</p> from the mix-in class <code>Acquisition.Explicit</code>.</p>
<h3> Controlled Acquisition</h3>
<h3>Controlled Acquisition</h3>
<p> A class (or instance) can provide attribute by attribute control <p> A class (or instance) can provide attribute by attribute control
over acquisition. This is done by:</p> over acquisition. This is done by:</p>
<ul><li><p>subclassing from <code>Acquisition.Explicit</code>, and</p> <ul>
<li><p>subclassing from <code>Acquisition.Explicit</code>, and</p></li>
<li><p>setting all attributes that should be acquired to the special <li><p>setting all attributes that should be acquired to the special
value: <code>Acquisition.Acquired</code>. Setting an attribute to this value: <code>Acquisition.Acquired</code>. Setting an attribute to this
value also allows inherited attributes to be overridden with value also allows inherited attributes to be overridden with
acquired ones.</p> acquired ones.<p> For example, in:
<p> For example, in:</p> <pre>
<PRE>
class C(Acquisition.Explicit): class C(Acquisition.Explicit):
id=1 id=1
secret=2 secret=2
color=Acquisition.Acquired color=Acquisition.Acquired
__roles__=Acquisition.Acquired __roles__=Acquisition.Acquired
</pre>
</PRE> </p>
<p> The <em>only</em> attributes that are automatically acquired from <p> The <em>only</em> attributes that are automatically acquired from
containing objects are <code>color</code>, and <code>__roles__</code>. Note also containing objects are <code>color</code>, and '_<u>roles</u><u><code>. Note also
that the <code>__roles__</code> attribute is acquired even though it's that the </code></u><u>roles</u>_' attribute is acquired even though it's
name begins with an underscore. In fact, the special name begins with an underscore. In fact, the special
<code>Acquisition.Acquired</code> value can be used in <code>Acquisition.Acquired</code> value can be used in
<code>Acquisition.Implicit</code> objects to implicitly acquire selected <code>Acquisition.Implicit</code> objects to implicitly acquire selected
objects that smell like private objects.</p> objects that smell like private objects.</p>
</p></li>
</ul> </ul>
<h3> Filtered Acquisition</h3>
<h3>Filtered Acquisition</h3>
<p> The acquisition method, <code>aq_acquire</code>, accepts two optional <p> The acquisition method, <code>aq_acquire</code>, accepts two optional
arguments. The first of the additional arguments is a arguments. The first of the additional arguments is a
"filtering" function that is used when considering whether to "filtering" function that is used when considering whether to
acquire an object. The second of the additional arguments is an acquire an object. The second of the additional arguments is an
object that is passed as extra data when calling the filtering object that is passed as extra data when calling the filtering
function and which defaults to <code>None</code>.</p> function and which defaults to <code>None</code>.</p>
<p> The filter function is called with five arguments:</p> <p> The filter function is called with five arguments:</p>
<ul><li><p>The object that the <code>aq_acquire</code> method was called on,</p> <ul>
<li><p>The object that the <code>aq_acquire</code> method was called on,</p></li>
<li><p>The object where an object was found,</p></li>
<li><p>The object where an object was found,</p> <li><p>The name of the object, as passed to <code>aq_acquire</code>,</p></li>
<li><p>The object found, and</p></li>
<li><p>The extra data passed to <code>aq_acquire</code>.</p></li>
<li><p>The name of the object, as passed to <code>aq_acquire</code>,</p>
<li><p>The object found, and</p>
<li><p>The extra data passed to <code>aq_acquire</code>.</p>
</ul> </ul>
<p> If the filter returns a true object that the object found is <p> If the filter returns a true object that the object found is
returned, otherwise, the acquisition search continues.</p> returned, otherwise, the acquisition search continues.</p>
<p> For example, in:
<p> For example, in:</p> <pre>
<PRE>
from Acquisition import Explicit from Acquisition import Explicit
class HandyForTesting: class HandyForTesting:
def __init__(self, name): self.name=name def __init__(self, name): self.name=name
def __str__(self): def __str__(self):
return &quot;%s(%s)&quot; % (self.name, self.__class__.__name__) return "%s(%s)" % (self.name, self.__class__.__name__)
__repr__=__str__ __repr__=__str__
class E(Explicit, HandyForTesting): pass class E(Explicit, HandyForTesting): pass
...@@ -200,21 +173,17 @@ ...@@ -200,21 +173,17 @@
return hasattr(object,'isNice') and object.isNice return hasattr(object,'isNice') and object.isNice
print a.b.c.aq_acquire('p', find_nice) print a.b.c.aq_acquire('p', find_nice)
</pre>
</PRE> </p>
<p> The filtered acquisition in the last line skips over the first <p> The filtered acquisition in the last line skips over the first
attribute it finds with the name <code>p</code>, because the attribute attribute it finds with the name <code>p</code>, because the attribute
doesn't satisfy the condition given in the filter. The output of doesn't satisfy the condition given in the filter. The output of
the last line is:</p> the last line is:
<PRE> <pre>
spam(Nice) and I am nice! spam(Nice) and I am nice!
</pre>
</PRE> </p>
<h2> Acquisition and methods</h2>
<h2>Acquisition and methods</h2>
<p> Python methods of objects that support acquisition can use <p> Python methods of objects that support acquisition can use
acquired attributes as in the <code>report</code> method of the first example acquired attributes as in the <code>report</code> method of the first example
above. When a Python method is called on an object that is above. When a Python method is called on an object that is
...@@ -222,89 +191,71 @@ ...@@ -222,89 +191,71 @@
method as the first argument. This rule also applies to method as the first argument. This rule also applies to
user-defined method types and to C methods defined in pure mix-in user-defined method types and to C methods defined in pure mix-in
classes.</p> classes.</p>
<p> Unfortunately, C methods defined in extension base classes that <p> Unfortunately, C methods defined in extension base classes that
define their own data structures, cannot use aquired attributes at define their own data structures, cannot use aquired attributes at
this time. This is because wrapper objects do not conform to the this time. This is because wrapper objects do not conform to the
data structures expected by these methods.</p> data structures expected by these methods.</p>
<h2> Acquiring Acquiring objects</h2>
<p> Consider the following example:
<h2>Acquiring Acquiring objects</h2> <pre>
<p> Consider the following example:</p>
<PRE>
from Acquisition import Implicit from Acquisition import Implicit
class C(Implicit): class C(Implicit):
def __init__(self, name): self.name=name def __init__(self, name): self.name=name
def __str__(self): def __str__(self):
return &quot;%s(%s)&quot; % (self.name, self.__class__.__name__) return "%s(%s)" % (self.name, self.__class__.__name__)
__repr__=__str__ __repr__=__str__
a=C(&quot;a&quot;) a=C("a")
a.b=C(&quot;b&quot;) a.b=C("b")
a.b.pref=&quot;spam&quot; a.b.pref="spam"
a.b.c=C(&quot;c&quot;) a.b.c=C("c")
a.b.c.color=&quot;red&quot; a.b.c.color="red"
a.b.c.pref=&quot;eggs&quot; a.b.c.pref="eggs"
a.x=C(&quot;x&quot;) a.x=C("x")
o=a.b.c.x o=a.b.c.x
</pre>
</PRE> </p>
<p> The expression <code>o.color</code> might be expected to return <code>"red"</code>. In <p> The expression <code>o.color</code> might be expected to return <code>"red"</code>. In
earlier versions of ExtensionClass, however, this expression earlier versions of ExtensionClass, however, this expression
failed. Acquired acquiring objects did not acquire from the failed. Acquired acquiring objects did not acquire from the
environment they were accessed in, because objects were only environment they were accessed in, because objects were only
wrapped when they were first found, and were not rewrapped as they wrapped when they were first found, and were not rewrapped as they
were passed down the acquisition tree.</p> were passed down the acquisition tree.</p>
<p> In the current release of ExtensionClass, the expression "o.color" <p> In the current release of ExtensionClass, the expression "o.color"
does indeed return <code>"red"</code>.</p> does indeed return <code>"red"</code>.</p>
<p> When searching for an attribute in <code>o</code>, objects are searched in <p> When searching for an attribute in <code>o</code>, objects are searched in
the order <code>x</code>, <code>a</code>, <code>b</code>, <code>c</code>. So, for example, the expression, the order <code>x</code>, <code>a</code>, <code>b</code>, <code>c</code>. So, for example, the expression,
<code>o.pref</code> returns <code>"spam"</code>, not <code>"eggs"</code>. In earlier releases of <code>o.pref</code> returns <code>"spam"</code>, not <code>"eggs"</code>. In earlier releases of
ExtensionClass, the attempt to get the <code>pref</code> attribute from <code>o</code> ExtensionClass, the attempt to get the <code>pref</code> attribute from <code>o</code>
would have failed.</p> would have failed.</p>
<p> If desired, the current rules for looking up attributes in complex <p> If desired, the current rules for looking up attributes in complex
expressions can best be understood through repeated application of expressions can best be understood through repeated application of
the <code>__of__</code> method:</p> the '_<u>of</u>_' method:</p>
<dl>
<dl><dt> <code>a.x</code><dd><p><code>x.__of__(a)</code></p> <dt> <code>a.x</code></dt>
<dd>'x._<u>of</u>_(a)'</dd>
<dt> <code>a.b</code></dt>
<dt> <code>a.b</code><dd><p><code>b.__of__(a)</code></p> <dd>'b._<u>of</u>_(a)'</dd>
<dt> <code>a.b.x</code></dt>
<dd>'x._<u>of</u><u>(a).</u><u>of</u><u>(b.</u><u>of</u>_(a))'</dd>
<dt> <code>a.b.x</code><dd><p><code>x.__of__(a).__of__(b.__of__(a))</code></p> <dt> <code>a.b.c</code></dt>
<dd>'c._<u>of</u><u>(b.</u><u>of</u>_(a))'</dd>
<dt> <code>a.b.c.x</code></dt>
<dt> <code>a.b.c</code><dd><p><code>c.__of__(b.__of__(a))</code></p> <dd>'x._<u>of</u><u>(a).</u><u>of</u><u>(b.</u><u>of</u><u>(a)).</u><u>of</u><u>(c.</u><u>of</u><u>(b.</u><u>of</u>_(a)))'</dd>
<dt> <code>a.b.c.x</code><dd><p><code>x.__of__(a).__of__(b.__of__(a)).__of__(c.__of__(b.__of__(a)))</code></p>
</dl> </dl>
<p> and by keeping in mind that attribute lookup in a wrapper <p> and by keeping in mind that attribute lookup in a wrapper
is done by trying to lookup the attribute in the wrapped object is done by trying to lookup the attribute in the wrapped object
first and then in the parent object. In the expressions above first and then in the parent object. In the expressions above
involving the <code>__of__</code> method, lookup proceeds from left to right.</p> involving the '_<u>of</u>_' method, lookup proceeds from left to right.</p>
<p> Note that heuristics are used to avoid most of the repeated <p> Note that heuristics are used to avoid most of the repeated
lookups. For example, in the expression: <code>a.b.c.x.foo</code>, the object lookups. For example, in the expression: <code>a.b.c.x.foo</code>, the object
<code>a</code> is searched no more than once, even though it is wrapped three <code>a</code> is searched no more than once, even though it is wrapped three
times.</p> times.</p>
<p>.. <a href="#1">[1]</a> Gil, J., Lorenz, D.,
<a href="http://www.bell-labs.com/people/cope/oopsla/Oopsla96TechnicalProgramAbstracts.html#GilLorenz">Environmental Acquisition--A New Inheritance-Like Abstraction Mechanism</a>,
<p> <a name="1">[1]</a> Gil, J., Lorenz, D.,
<a href="http://www.bell-labs.com/people/cope/oopsla/Oopsla96TechnicalProgramAbstracts.html#GilLorenz">Environmental Acquisition--A New Inheritance-Like Abstraction Mechanism</a>
OOPSLA '96 Proceedings, ACM SIG-PLAN, October, 1996</p> OOPSLA '96 Proceedings, ACM SIG-PLAN, October, 1996</p>
</body>
<p> </html>
<TABLE BORDER=1 CELLPADDING=2>
</TABLE></p>
lib/python/StructuredText/regressions/ExtensionClass.ref
View file @ 89994a14
<html>
<head>
<title>Extension Classes, Python Extension Types Become Classes</title>
</head>
<body>
<h1>Extension Classes, Python Extension Types Become Classes</h1> <h1>Extension Classes, Python Extension Types Become Classes</h1>
<p> Jim Fulton, Digital Creations, Inc. <p> Jim Fulton, Digital Creations, Inc.
jim@digicool.com</p> jim@digicool.com</p>
<p> <a href="COPYRIGHT.html">Copyright (C) 1996-1998, Digital Creations</a>.</p> <p> <a href="COPYRIGHT.html">Copyright (C) 1996-1998, Digital Creations</a>.</p>
<h2> Abstract</h2>
<h2>Abstract</h2>
<p> A lightweight mechanism has been developed for making Python <p> A lightweight mechanism has been developed for making Python
extension types more class-like. Classes can be developed in an extension types more class-like. Classes can be developed in an
extension language, such as C or C++, and these classes can be extension language, such as C or C++, and these classes can be
treated like other python classes:</p> treated like other python classes:</p>
<ul><li><p>They can be sub-classed in python,</p> <ul>
<li><p>They can be sub-classed in python,</p></li>
<li><p>They provide access to method documentation strings, and</p></li>
<li><p>They provide access to method documentation strings, and</p> <li><p>They can be used to directly create new instances.</p></li>
<li><p>They can be used to directly create new instances.</p>
</ul> </ul>
<p> An example class shows how extension classes are implemented and how <p> An example class shows how extension classes are implemented and how
they differ from extension types.</p> they differ from extension types.</p>
<p> Extension classes provide additional extensions to class and <p> Extension classes provide additional extensions to class and
instance semantics, including:</p> instance semantics, including:</p>
<ul><li><p>A protocol for accessing subobjects "in the context of" their <ul>
<li><p>A protocol for accessing subobjects "in the context of" their
containers. This is used to implement custom method types containers. This is used to implement custom method types
and <a href="Acquisition.html">environmental acquisition</a>.</p> and <a href="Acquisition.html">environmental acquisition</a>.</p></li>
<li><p>A protocol for overriding method call semantics. This is used <li><p>A protocol for overriding method call semantics. This is used
to implement "synchonized" classes and could be used to to implement "synchonized" classes and could be used to
implement argument type checking.</p> implement argument type checking.</p></li>
<li><p>A protocol for class initialization that supports execution of a <li><p>A protocol for class initialization that supports execution of a
special <code>__class_init__</code> method after a class has been special '_<u>class</u>init__' method after a class has been
initialized.</p> initialized. </p></li>
</ul> </ul>
<p> Extension classes illustrate how the Python class mechanism can be <p> Extension classes illustrate how the Python class mechanism can be
extended and may provide a basis for improved or specialized class extended and may provide a basis for improved or specialized class
models. </p> models. </p>
<h2> Releases</h2>
<h2>Releases</h2>
<p> To find out what's changed in this release, <p> To find out what's changed in this release,
see the <a href="release.html">release notes</a>.</p> see the <a href="release.html">release notes</a>.</p>
<h2> Problem</h2>
<h2>Problem</h2>
<p> Currently, Python provides two ways of defining new kinds of objects:</p> <p> Currently, Python provides two ways of defining new kinds of objects:</p>
<ul><li><p>Python classes</p> <ul>
<li><p>Python classes</p></li>
<li><p>Extension types</p></li>
<li><p>Extension types</p>
</ul> </ul>
<p> Each approach has it's strengths. Extension types provide much greater <p> Each approach has it's strengths. Extension types provide much greater
...@@ -64,7 +55,6 @@ ...@@ -64,7 +55,6 @@
extension types are written in C, the programmer has greater access to extension types are written in C, the programmer has greater access to
external resources. (Note that Python's use of the term type has external resources. (Note that Python's use of the term type has
little to do with the notion of type as a formal specification.)</p> little to do with the notion of type as a formal specification.)</p>
<p> Classes provide a higher level of abstraction and are generally much <p> Classes provide a higher level of abstraction and are generally much
easier to develop. Classes provide full inheritance support, while easier to develop. Classes provide full inheritance support, while
support for inheritance when developing extension types is very support for inheritance when developing extension types is very
...@@ -72,13 +62,11 @@ ...@@ -72,13 +62,11 @@
strings, that are useful for documentation and discovery. Classes strings, that are useful for documentation and discovery. Classes
act as factories for creating instances, while separate functions act as factories for creating instances, while separate functions
must be provided to create instances of types.</p> must be provided to create instances of types.</p>
<p> It would be useful to combine the features of the two approaches. It <p> It would be useful to combine the features of the two approaches. It
would be useful to be able to have better support for inheritance for would be useful to be able to have better support for inheritance for
types, or to be able to subclass from types in Python. It would be types, or to be able to subclass from types in Python. It would be
useful to be able to have class-like meta-data support for types and useful to be able to have class-like meta-data support for types and
the ability to construct instances directly from types.</p> the ability to construct instances directly from types.</p>
<p> Our software is developed in Python. When necessary, we convert <p> Our software is developed in Python. When necessary, we convert
debugged Python routines and classes to C for improved debugged Python routines and classes to C for improved
performance. In most cases, a small number of methods in a class performance. In most cases, a small number of methods in a class
...@@ -88,17 +76,15 @@ ...@@ -88,17 +76,15 @@
class in C that contains only the performance-critical aspects of class in C that contains only the performance-critical aspects of
a class' implementation and mix this base class into a Python a class' implementation and mix this base class into a Python
class. </p> class. </p>
<p> We have need, in a number of projects, for semantics that are <p> We have need, in a number of projects, for semantics that are
slightly different than the usual class and instance semantics, slightly different than the usual class and instance semantics,
yet we don't want to do most of our development in C. For yet we don't want to do most of our development in C. For
example, we have developed a persistence mechanism <a href="#1">[1]</a> that example, we have developed a persistence mechanism <a href="#1">[1]</a> that
redefines <code>__getattr__</code> and <code>__setattr__</code> to take storage-related redefines '_<u>getattr</u><u><code> and </code></u><u>setattr</u>_' to take storage-related
actions when object state is accessed or modified. We want to be actions when object state is accessed or modified. We want to be
able to take certain actions on <em>every</em> attribute reference, but able to take certain actions on <em>every</em> attribute reference, but
for python class instances, <code>__getattr__</code> is only called when for python class instances, '_<u>getattr</u>_' is only called when
attribute lookup fails by normal means.</p> attribute lookup fails by normal means.</p>
<p> As another example, we would like to have greater control over how <p> As another example, we would like to have greater control over how
methods are bound. Currently, when accessing a class methods are bound. Currently, when accessing a class
instance attribute, the attribute value is bound together with the instance attribute, the attribute value is bound together with the
...@@ -110,82 +96,58 @@ ...@@ -110,82 +96,58 @@
For example, we might want to bind instances and callable objects For example, we might want to bind instances and callable objects
with special method objects that assure that no more than one thread with special method objects that assure that no more than one thread
accesses the object or method at one time.</p> accesses the object or method at one time.</p>
<p> We can provide these special semantics in extension types, but we <p> We can provide these special semantics in extension types, but we
wish to provide them for classes developed in Python.</p> wish to provide them for classes developed in Python.</p>
<h2> Background</h2>
<h2>Background</h2>
<p> At the first Python Workshop, Don Beaudry presented work <a href="#3">[3]</a> done <p> At the first Python Workshop, Don Beaudry presented work <a href="#3">[3]</a> done
at V.I. Corp to integrate Python with C++ frameworks. This system at V.I. Corp to integrate Python with C++ frameworks. This system
provided a number of important features, including:</p> provided a number of important features, including:</p>
<ul><li><p>Definition of extension types that provide class-like meta-data <ul>
and that can be called to create instances.</p> <li><p>Definition of extension types that provide class-like meta-data
and that can be called to create instances.</p></li>
<li><p>Ability to subclass in python from C types.</p></li>
<li><p>Ability to subclass in python from C types.</p>
<li><p>Ability to define classes in python who's data are stored as <li><p>Ability to define classes in python who's data are stored as
C structures rather than in dictionaries to better interface to C structures rather than in dictionaries to better interface to
C and C++ libraries, and for better performance.</p> C and C++ libraries, and for better performance.</p></li>
<li><p>Less dynamic data structures. In particular, the data structure <li><p>Less dynamic data structures. In particular, the data structure
for a class is declared during class definition.</p> for a class is declared during class definition.</p></li>
<li><p>Support for enumeration types.</p></li>
<li><p>Support for enumeration types.</p>
</ul> </ul>
<p> This work was not released, initially.</p> <p> This work was not released, initially.</p>
<p> Shortly after the workshop, changes were made to Python to support <p> Shortly after the workshop, changes were made to Python to support
the sub-classing features described in <a href="#3">[3]</a>. These changes were not the sub-classing features described in <a href="#3">[3]</a>. These changes were not
documented until the fourth Python Workshop <a href="#4">[4]</a>.</p> documented until the fourth Python Workshop <a href="#4">[4]</a>.</p>
<p> At the third Python workshop, I presented some work I had done on <p> At the third Python workshop, I presented some work I had done on
generating module documentation for extension types. Based on the generating module documentation for extension types. Based on the
discussion at this workshop, I developed a meta-type proposal <a href="#5">[5]</a>. discussion at this workshop, I developed a meta-type proposal <a href="#5">[5]</a>.
This meta-type proposal was for an object that simply stored This meta-type proposal was for an object that simply stored
meta-information for a type, for the purpose of generating module meta-information for a type, for the purpose of generating module
documentation.</p> documentation.</p>
<p> In the summer of 1996, Don Beaudry released the system described in <p> In the summer of 1996, Don Beaudry released the system described in
<a href="#3">[3]</a> under the name MESS <a href="#6">[6]</a>. MESS addresses a number of needs but <a href="#3">[3]</a> under the name MESS <a href="#6">[6]</a>. MESS addresses a number of needs but
has a few drawbacks:</p> has a few drawbacks:</p>
<ul><li><p>Only single inheritance is supported.</p> <ul>
<li><p>Only single inheritance is supported.</p></li>
<li><p>The mechanisms for defining MESS extension types is very different <li><p>The mechanisms for defining MESS extension types is very different
from and more complicated than the standard Python type creation from and more complicated than the standard Python type creation
mechanism.</p> mechanism.</p></li>
<li><p>Defining MESS types requires the use of an extensive C <li><p>Defining MESS types requires the use of an extensive C
applications programming interface. This presents problems for applications programming interface. This presents problems for
configuring dynamically-loaded extension modules unless the MESS configuring dynamically-loaded extension modules unless the MESS
library is linked into the Python interpreter.</p> library is linked into the Python interpreter.</p></li>
<li><p>Because the system tries to do a number of different things, it is <li><p>Because the system tries to do a number of different things, it is
fairly large, about 15,000 lines.</p> fairly large, about 15,000 lines.</p></li>
<li><p>There is very little documentation, especially for the C <li><p>There is very little documentation, especially for the C
programming interface.</p> programming interface.</p></li>
<li><p>The system is a work in progress, with a number of outstanding <li><p>The system is a work in progress, with a number of outstanding
bugs.</p> bugs.</p></li>
</ul> </ul>
<p> As MESS matures, we expect most of these problems to be addressed.</p> <p> As MESS matures, we expect most of these problems to be addressed.</p>
<h2> Extension Classes</h2>
<h2>Extension Classes</h2>
<p> To meet short term needs for a C-based persistence mechanism <a href="#1">[1]</a>, an <p> To meet short term needs for a C-based persistence mechanism <a href="#1">[1]</a>, an
extension class module was developed using the mechanism described extension class module was developed using the mechanism described
in <a href="#4">[4]</a> and building on ideas from MESS <a href="#6">[6]</a>. The extension class module in <a href="#4">[4]</a> and building on ideas from MESS <a href="#6">[6]</a>. The extension class module
...@@ -193,32 +155,24 @@ ...@@ -193,32 +155,24 @@
eliminate, or at least reduce semantic differences between types and eliminate, or at least reduce semantic differences between types and
classes. The module was designed to meet the following goal:</p> classes. The module was designed to meet the following goal:</p>
<ul><li><p>Provide class-like behavior for extension types, including <ul>
interfaces for meta information and for constructing instances.</p> <li><p>Provide class-like behavior for extension types, including
interfaces for meta information and for constructing instances.</p></li>
<li><p>Support sub-classing in Python from extension classes, with support <li><p>Support sub-classing in Python from extension classes, with support
for multiple inheritance.</p> for multiple inheritance.</p></li>
<li><p>Provide a small hardened implementation that can be used for <li><p>Provide a small hardened implementation that can be used for
current products.</p> current products.</p></li>
<li><p>Provide a mechanism that requires minimal modification to existing <li><p>Provide a mechanism that requires minimal modification to existing
extension types.</p> extension types.</p></li>
<li><p>Provide a basis for research on alternative semantics for classes <li><p>Provide a basis for research on alternative semantics for classes
and inheritance.</p> and inheritance.</p></li>
</ul> </ul>
<p> <strong>Note:</strong> I use <em>non-standard</em> terminology here. By standard <p> <strong>Note:</strong> I use <em>non-standard</em> terminology here. By standard
<em>python</em> terminology, only standard python classes can be called <em>python</em> terminology, only standard python classes can be called
classes. ExtensionClass "classes" are technically just "types" classes. ExtensionClass "classes" are technically just "types"
that happen to swim, walk and quack like python classes.</p> that happen to swim, walk and quack like python classes.</p>
<h3> Base extension classes and extension subclasses</h3>
<h3>Base extension classes and extension subclasses</h3>
<p> Base extension classes are implemented in C. Extension subclasses <p> Base extension classes are implemented in C. Extension subclasses
are implemented in Python and inherit, directly or indirectly from are implemented in Python and inherit, directly or indirectly from
one or more base extension classes. An extension subclass may one or more base extension classes. An extension subclass may
...@@ -227,47 +181,39 @@ ...@@ -227,47 +181,39 @@
apply. Currently, extension subclasses must conform to the apply. Currently, extension subclasses must conform to the
following two rules:</p> following two rules:</p>
<ul><li><p>The first super class listed in the class statement defining an <ul>
<li><p>The first super class listed in the class statement defining an
extension subclass must be either a base extension class or an extension subclass must be either a base extension class or an
extension subclass. This restriction will be removed in extension subclass. This restriction will be removed in
Python-1.5.</p> Python-1.5.</p></li>
<li><p>At most one base extension direct or indirect super class may <li><p>At most one base extension direct or indirect super class may
define C data members. If an extension subclass inherits from define C data members. If an extension subclass inherits from
multiple base extension classes, then all but one must be mix-in multiple base extension classes, then all but one must be mix-in
classes that provide extension methods but no data.</p> classes that provide extension methods but no data.</p></li>
</ul> </ul>
<h3> Meta Information</h3>
<h3>Meta Information</h3>
<p> Like standard python classes, extension classes have the following <p> Like standard python classes, extension classes have the following
attributes containing meta-data:</p> attributes containing meta-data:</p>
<dl>
<dl><dt> <code>__doc__</code> <dd><p>a documentation string for the class,</p> <dt> '_<u>doc</u>_'</dt>
<dd>a documentation string for the class,</dd>
<dt> '_<u>name</u>_'</dt>
<dt> <code>__name__</code> <dd><p>the class name,</p> <dd>the class name,</dd>
<dt> '_<u>bases</u>_'</dt>
<dd>a sequence of base classes,</dd>
<dt> <code>__bases__</code><dd><p>a sequence of base classes,</p> <dt> '_<u>dict</u>_'</dt>
<dd>a class dictionary, and</dd>
<dt> '_<u>module</u>_'</dt>
<dt> <code>__dict__</code> <dd><p>a class dictionary, and</p> <dd>the name of the module in which the class was
defined. </dd>
<dt> <code>__module__</code><dd><p>the name of the module in which the class was
defined. </p>
</dl> </dl>
<p> The class dictionary provides access to unbound methods and their <p> The class dictionary provides access to unbound methods and their
documentation strings, including extension methods and special documentation strings, including extension methods and special
methods, such as methods that implement sequence and numeric methods, such as methods that implement sequence and numeric
protocols. Unbound methods can be called with instance first protocols. Unbound methods can be called with instance first
arguments.</p> arguments.</p>
<h3> Subclass instance data</h3>
<h3>Subclass instance data</h3>
<p> Extension subclass instances have instance dictionaries, just <p> Extension subclass instances have instance dictionaries, just
like Python class instances do. When fetching attribute values, like Python class instances do. When fetching attribute values,
extension class instances will first try to obtain data from the extension class instances will first try to obtain data from the
...@@ -276,20 +222,14 @@ ...@@ -276,20 +222,14 @@
classes. When setting attributes, extension classes first attempt classes. When setting attributes, extension classes first attempt
to use extension base class attribute setting operations, and if to use extension base class attribute setting operations, and if
these fail, then data are placed in the instance dictionary.</p> these fail, then data are placed in the instance dictionary.</p>
<h2> Implementing base extension classes</h2>
<h2>Implementing base extension classes</h2>
<p> A base extension class is implemented in much the same way that an <p> A base extension class is implemented in much the same way that an
extension type is implemented, except:</p> extension type is implemented, except:</p>
<ul><li><p>The include file, <code>ExtensionClass.h</code>, must be included.</p> <ul>
<li><p>The include file, <code>ExtensionClass.h</code>, must be included.</p></li>
<li><p>The type structure is declared to be of type <code>PyExtensionClass</code>, rather <li><p>The type structure is declared to be of type <code>PyExtensionClass</code>, rather
than of type <code>PyTypeObject</code>.</p> than of type <code>PyTypeObject</code>.</p></li>
<li><p>The type structure has an additional member that must be defined <li><p>The type structure has an additional member that must be defined
after the documentation string. This extra member is a method chain after the documentation string. This extra member is a method chain
(<code>PyMethodChain</code>) containing a linked list of method definition (<code>PyMethodChain</code>) containing a linked list of method definition
...@@ -298,65 +238,50 @@ ...@@ -298,65 +238,50 @@
but simply define method lists, which are null-terminated arrays but simply define method lists, which are null-terminated arrays
of method definitions. A macro, <code>METHOD_CHAIN</code> is defined in of method definitions. A macro, <code>METHOD_CHAIN</code> is defined in
<code>ExtensionClass.h</code> that converts a method list to a method chain. <code>ExtensionClass.h</code> that converts a method list to a method chain.
(See the example below.)</p> (See the example below.)</p></li>
<li><p>Module functions that create new instances must be replaced by <li><p>Module functions that create new instances must be replaced by
<code>__init__</code> methods that initialize, but does not create storage for '_<u>init</u>_' methods that initialize, but does not create storage for
instances.</p> instances.</p></li>
<li><p>The extension class must be initialized and exported to the module <li><p>The extension class must be initialized and exported to the module
with::</p> with:
<PRE> <pre>
PyExtensionClass_Export(d,&quot;name&quot;,type); PyExtensionClass_Export(d,"name",type);
</pre>
where 'name' is the module name and 'type' is the extension class </p></li>
type object.
</PRE>
</ul> </ul>
<h3>Attribute lookup</h3> <p> where <code>name</code> is the module name and <code>type</code> is the extension class
type object.<h2> Attribute lookup</h2>
<p> Attribute lookup is performed by calling the base extension class <p> Attribute lookup is performed by calling the base extension class
<code>getattr</code> operation for the base extension class that includes C <code>getattr</code> operation for the base extension class that includes C
data, or for the first base extension class, if none of the base data, or for the first base extension class, if none of the base
extension classes include C data. <code>ExtensionClass.h</code> defines a extension classes include C data. <code>ExtensionClass.h</code> defines a
macro <code>Py_FindAttrString</code> that can be used to find an object's macro <code>Py_FindAttrString</code> that can be used to find an object's
attributes that are stored in the object's instance dictionary or attributes that are stored in the object's instance dictionary or
in the object's class or base classes:</p> in the object's class or base classes:
<PRE> <pre>
v = Py_FindAttrString(self,name); v = Py_FindAttrString(self,name);
</pre>
</PRE> </p>
<p> where <code>name</code> is a C string containing the attribute name.</p> <p> where <code>name</code> is a C string containing the attribute name.</p>
<p> In addition, a macro is provided that replaces 'Py<u>FindMethod'
<p> In addition, a macro is provided that replaces <code>Py_FindMethod</code>
calls with logic to perform the same sort of lookup that is calls with logic to perform the same sort of lookup that is
provided by <code>Py_FindAttrString</code>.</p> provided by 'Py</u>FindAttrString'.</p>
<p> If an attribute name is contained in a Python string object, <p> If an attribute name is contained in a Python string object,
rather than a C string object, then the macro <code>Py_FindAttr</code> should rather than a C string object, then the macro <code>Py_FindAttr</code> should
be used to look up an attribute value.</p> be used to look up an attribute value.</p>
<h2> Linking</h2>
<h3>Linking</h3>
<p> The extension class mechanism was designed to be useful with <p> The extension class mechanism was designed to be useful with
dynamically linked extension modules. Modules that implement dynamically linked extension modules. Modules that implement
extension classes do not have to be linked against an extension extension classes do not have to be linked against an extension
class library. The macro <code>PyExtensionClass_Export</code> imports the class library. The macro <code>PyExtensionClass_Export</code> imports the
<code>ExtensionClass</code> module and uses objects imported from this module <code>ExtensionClass</code> module and uses objects imported from this module
to initialize an extension class with necessary behavior.</p> to initialize an extension class with necessary behavior.</p>
<h2> Example: MultiMapping objects</h2>
<p> An <a href="MultiMapping.html">example</a>, is provided that illustrates the
<h3>Example: MultiMapping objects</h3>
<p> An <a href="MultiMapping.html">example</a> is provided that illustrates the
changes needed to convert an existing type to an ExtensionClass.</p> changes needed to convert an existing type to an ExtensionClass.</p>
</p>
<h2> Implementing base extension class constructors</h2>
<h2>Implementing base extension class constructors</h2>
<p> Some care should be taken when implementing or overriding base <p> Some care should be taken when implementing or overriding base
class constructors. When a Python class overrides a base class class constructors. When a Python class overrides a base class
constructor and fails to call the base class constructor, a constructor and fails to call the base class constructor, a
...@@ -368,18 +293,15 @@ ...@@ -368,18 +293,15 @@
if not set properly, will cause the interpreter to crash when if not set properly, will cause the interpreter to crash when
accessed. This is the case with the <code>MultiMapping</code> extension base accessed. This is the case with the <code>MultiMapping</code> extension base
class shown in the example above.</p> class shown in the example above.</p>
<p> If no base class constructor is provided, extension class instance <p> If no base class constructor is provided, extension class instance
memory will be initialized to 0. It is a good idea to design memory will be initialized to 0. It is a good idea to design
extension base classes so that instance methods check for extension base classes so that instance methods check for
uninitialized memory and perform initialialization if necessary. uninitialized memory and perform initialialization if necessary.
This was not done above to simplify the example.</p> This was not done above to simplify the example.</p>
<h2> Overriding methods inherited from Python base classes</h2>
<h2>Overriding methods inherited from Python base classes</h2>
<p> A problem occurs when trying to overide methods inherited from <p> A problem occurs when trying to overide methods inherited from
Python base classes. Consider the following example:</p> Python base classes. Consider the following example:
<PRE> <pre>
from ExtensionClass import Base from ExtensionClass import Base
class Spam: class Spam:
...@@ -392,22 +314,20 @@ ...@@ -392,22 +314,20 @@
def __init__(self, name, favorite_color): def __init__(self, name, favorite_color):
Spam.__init__(self,name) Spam.__init__(self,name)
self.favorite_color=favorite_color self.favorite_color=favorite_color
</pre>
</PRE> </p>
<p> This implementation will fail when an <code>ECSpam</code> object is <p> This implementation will fail when an <code>ECSpam</code> object is
instantiated. The problem is that <code>ECSpam.__init__</code> calls instantiated. The problem is that 'ECSpam._<u>init</u><u>' calls
<code>Spam.__init__</code>, and <code>Spam.__init__</code> can only be called with a 'Spam.</u><u>init</u><u>', and 'Spam.</u><u>init</u><u>' can only be called with a
Python instance (an object of type <code>"instance"</code>) as the first Python instance (an object of type <code>"instance"</code>) as the first
argument. The first argument passed to <code>Spam.__init__</code> will be an argument. The first argument passed to 'Spam.</u><u>init</u>_' will be an
<code>ECSpam</code> instance (an object of type <code>ECSPam</code>).</p> <code>ECSpam</code> instance (an object of type <code>ECSPam</code>).</p>
<p> To overcome this problem, extension classes provide a class method <p> To overcome this problem, extension classes provide a class method
<code>inheritedAttribute</code> that can be used to obtain an inherited <code>inheritedAttribute</code> that can be used to obtain an inherited
attribute that is suitable for calling with an extension class attribute that is suitable for calling with an extension class
instance. Using the <code>inheritedAttribute</code> method, the above instance. Using the <code>inheritedAttribute</code> method, the above
example can be rewritten as:</p> example can be rewritten as:
<PRE> <pre>
from ExtensionClass import Base from ExtensionClass import Base
class Spam: class Spam:
...@@ -420,47 +340,38 @@ ...@@ -420,47 +340,38 @@
def __init__(self, name, favorite_color): def __init__(self, name, favorite_color):
ECSpam.inheritedAttribute('__init__')(self,name) ECSpam.inheritedAttribute('__init__')(self,name)
self.favorite_color=favorite_color self.favorite_color=favorite_color
</pre>
</PRE> </p>
<p> This isn't as pretty but does provide the desired result.</p> <p> This isn't as pretty but does provide the desired result.</p>
<h2> New class and instance semantics</h2>
<h3> Context Wrapping</h3>
<h2>New class and instance semantics</h2>
<h3>Context Wrapping</h3>
<p> It is sometimes useful to be able to wrap up an object together <p> It is sometimes useful to be able to wrap up an object together
with a containing object. I call this "context wrapping" with a containing object. I call this "context wrapping"
because an object is accessed in the context of the object it is because an object is accessed in the context of the object it is
accessed through.</p> accessed through.</p>
<h4> We have found many applications for this, including:</h4>
<p> We have found many applications for this, including:</p> <ul>
<ul><li><p>User-defined method objects,</p> <li><p>User-defined method objects, </p></li>
<li><p><a href="Acquisition.html">Acquisition</a>, and</p></li>
<li><p>Computed attributes</p></li>
<li><p><a href="Acquisition.html">Acquisition</a> and</p>
<li><p>Computed attributes</p>
</ul> </ul>
<h4> User-defined method objects</h4>
<h4>User-defined method objects</h4>
<p> Python classes wrap Python function attributes into methods. When a <p> Python classes wrap Python function attributes into methods. When a
class has a function attribute that is accessed as an instance class has a function attribute that is accessed as an instance
attribute, a method object is created and returned that contains attribute, a method object is created and returned that contains
references to the original function and instance. When the method references to the original function and instance. When the method
is called, the original function is called with the instance as the is called, the original function is called with the instance as the
first argument followed by any arguments passed to the method.</p> first argument followed by any arguments passed to the method.</p>
<p> Extension classes provide a similar mechanism for attributes that <p> Extension classes provide a similar mechanism for attributes that
are Python functions or inherited extension functions. In are Python functions or inherited extension functions. In
addition, if an extension class attribute is an instance of an addition, if an extension class attribute is an instance of an
extension class that defines an <code>__of__</code> method, then when the extension class that defines an '_<u>of</u><u>' method, then when the
attribute is accessed through an instance, it's <code>__of__</code> method attribute is accessed through an instance, it's '</u><u>of</u>_' method
will be called to create a bound method.</p> will be called to create a bound method.</p>
<p> Consider the following example:
<p> Consider the following example:</p> <pre>
<PRE>
import ExtensionClass import ExtensionClass
class CustomMethod(ExtensionClass.Base): class CustomMethod(ExtensionClass.Base):
...@@ -481,95 +392,70 @@ ...@@ -481,95 +392,70 @@
x=bar() x=bar()
hi=x.hi() hi=x.hi()
</pre>
</PRE> </p>
<p> Note that <code>ExtensionClass.Base</code> is a base extension class that <p> Note that <code>ExtensionClass.Base</code> is a base extension class that
provides very basic ExtensionClass behavior. </p> provides very basic ExtensionClass behavior. </p>
<p> When run, this program outputs: <code>a bar was called</code>.</p> <p> When run, this program outputs: <code>a bar was called</code>.</p>
<h4> Computed Attributes</h4>
<h4>Computed Attributes</h4>
<p> It is not uncommon to wish to expose information via the <p> It is not uncommon to wish to expose information via the
attribute interface without affecting implementation data attribute interface without affecting implementation data
structures. One can use a custom <code>__getattr__</code> method to structures. One can use a custom '_<u>getattr</u><u><code> method to
implement computed attributes, however, this can be a bit implement computed attributes, however, this can be a bit
cumbersome and can interfere with other uses of <code>__getattr__</code>, cumbersome and can interfere with other uses of </code></u><u>getattr</u>_',
such as for persistence.</p> such as for persistence.</p>
<p> The '_<u>of</u><u>' protocol provides a convenient way to implement
<p> The <code>__of__</code> protocol provides a convenient way to implement
computed attributes. First, we define a ComputedAttribute computed attributes. First, we define a ComputedAttribute
class. a ComputedAttribute is constructed with a function to class. a ComputedAttribute is constructed with a function to
be used to compute an attribute, and calls the function when be used to compute an attribute, and calls the function when
it's <code>__of__</code> method is called:</p> it's '</u><u>of</u>_' method is called:<p> import ExtensionClass</p>
<p> import ExtensionClass</p> <h5> class ComputedAttribute(ExtensionClass.Base):</h5>
<p> def _<u>init</u>_(self, func): self.func=func</p>
<p> class ComputedAttribute(ExtensionClass.Base):</p> <p> def _<u>of</u>_(self, parent): return self.func(parent)</p>
<p> def __init__(self, func): self.func=func</p> </p>
<p> def __of__(self, parent): return self.func(parent)</p>
<p> Then we can use this class to create computed attributes. In the <p> Then we can use this class to create computed attributes. In the
example below, we create a computed attribute, <code>radius</code>:</p> example below, we create a computed attribute, 'radius':<p> from math import sqrt</p>
<p> from math import sqrt</p> <h5> class Point(ExtensionClass.Base):</h5>
<p> def _<u>init</u>_(self, x, y): self.x, self.y = x, y</p>
<p> class Point(ExtensionClass.Base):</p> <p> radius=ComputedAttribute(lambda self: sqrt(self.x<strong>2+self.y</strong>2))</p>
<p> def __init__(self, x, y): self.x, self.y = x, y</p> </p>
<h5> which we can use just like an ordinary attribute:</h5>
<p> radius=ComputedAttribute(lambda self: sqrt(self.x**2+self.y**2))</p>
<p> which we can use just like an ordinary attribute:</p>
<p> p=Point(2,2) <p> p=Point(2,2)
print p.radius</p> print p.radius</p>
<h3> Overriding method calls</h3>
<h3>Overriding method calls</h3>
<p> Normally, when a method is called, the function wrapped by the <p> Normally, when a method is called, the function wrapped by the
method is called directly by the method. In some cases, it is method is called directly by the method. In some cases, it is
useful for user-defined logic to participate in the actual useful for user-defined logic to participate in the actual
function call. Extension classes introduce a new protocol that function call. Extension classes introduce a new protocol that
provides extension classes greater control over how their provides extension classes greater control over how their
methods are called. If an extension class defines a special methods are called. If an extension class defines a special
method, <code>__call_method__</code>, then this method will be called to method, '_<u>call</u>method_<u><code>, then this method will be called to
call the functions (or other callable object) wrapped by the call the functions (or other callable object) wrapped by the
method. The method. <code>__call_method__</code> should provide the same method. The method. </code></u><u>call</u>method__' should provide the same
interface as provided by the Python builtin <code>apply</code> function.</p> interface as provided by the Python builtin <code>apply</code> function.</p>
<p> For example, consider the expression: <code>x.meth(arg1, arg2)</code>. The <p> For example, consider the expression: <code>x.meth(arg1, arg2)</code>. The
expression is evaluated by first computing a method object that expression is evaluated by first computing a method object that
wraps <code>x</code> and the attribute of <code>x</code> stored under the name <code>meth</code>. wraps <code>x</code> and the attribute of <code>x</code> stored under the name <code>meth</code>.
Assuming that <code>x</code> has a <code>__call_method__</code> method defined, then Assuming that <code>x</code> has a '_<u>call</u>method_<u><code> method defined, then
the <code>__call_method__</code> method of <code>x</code> will be called with two the </code></u><u>call</u>method__' method of <code>x</code> will be called with two
arguments, the attribute of <code>x</code> stored under the name <code>meth</code>, arguments, the attribute of <code>x</code> stored under the name <code>meth</code>,
and a tuple containing <code>x</code>, <code>arg1</code>, and <code>arg2</code>.</p> and a tuple containing <code>x</code>, <code>arg1</code>, and <code>arg2</code>.</p>
<p> To see how this feature may be used, see the Python module, <p> To see how this feature may be used, see the Python module,
<code>Syn.py</code>, which is included in the ExtensionClass distribution. <code>Syn.py</code>, which is included in the ExtensionClass distribution.
This module provides a mix-in class that provides Java-like This module provides a mix-in class that provides Java-like
"synchonized" classes that limit access to their methods to one "synchonized" classes that limit access to their methods to one
thread at a time.</p> thread at a time.</p>
<p> An interesting application of this mechanism would be to <p> An interesting application of this mechanism would be to
implement interface checking on method calls.</p> implement interface checking on method calls.</p>
<h3> Method attributes</h3>
<h3>Method attributes</h3>
<p> Methods of ExtensionClass instances can have user-defined <p> Methods of ExtensionClass instances can have user-defined
attributes, which are stored in their associated instances.</p> attributes, which are stored in their associated instances.</p>
<p> For example:
<p> For example:</p> <pre>
<PRE>
class C(ExtensionClass.Base): class C(ExtensionClass.Base):
def get_secret(self): def get_secret(self):
&quot;Get a secret&quot; "Get a secret"
.... ....
c=C() c=C()
...@@ -580,63 +466,49 @@ ...@@ -580,63 +466,49 @@
print c.f__roles__ # outputs ['Trusted People'] print c.f__roles__ # outputs ['Trusted People']
print C.f.__roles__ # fails, unbound method print C.f.__roles__ # fails, unbound method
</pre>
</PRE> </p>
<p> A bound method attribute is set by setting an attribute in it's <p> A bound method attribute is set by setting an attribute in it's
instance with a name consisting of the concatination of the instance with a name consisting of the concatination of the
method's <code>__name__</code> attribute and the attribute name. method's '_<u>name</u>_' attribute and the attribute name.
Attributes cannot be set on unbound methods.</p> Attributes cannot be set on unbound methods.</p>
<h3> Class initialization</h3>
<h3>Class initialization</h3>
<p> Normal Python class initialization is similar to but subtley <p> Normal Python class initialization is similar to but subtley
different from instance initialization. An instance <code>__init__</code> different from instance initialization. An instance '_<u>init</u>_'
function is called on an instance immediately <em>after</em> it is function is called on an instance immediately <em>after</em> it is
created. An instance <code>__init__</code> function can use instance created. An instance '_<u>init</u>_' function can use instance
information, like it's class and can pass the instance to other information, like it's class and can pass the instance to other
functions. On the other hand, the code in class statements is functions. On the other hand, the code in class statements is
executed immediately <em>before</em> the class is created. This means executed immediately <em>before</em> the class is created. This means
that the code in a class statement cannot use class attributes, that the code in a class statement cannot use class attributes,
like <code>__bases__</code>, or pass the class to functions.</p> like '_<u>bases</u>_', or pass the class to functions.</p>
<p> Extension classes provide a mechanism for specifying code to be <p> Extension classes provide a mechanism for specifying code to be
run <em>after</em> a class has been created. If a class or one of it's run <em>after</em> a class has been created. If a class or one of it's
base classes defines a <code>__class_init__</code> method, then this method base classes defines a '_<u>class</u>init__' method, then this method
will be called just after a class has been created. The one will be called just after a class has been created. The one
argument passed to the method will be the class, <em>not</em> an argument passed to the method will be the class, <em>not</em> an
instance of the class.</p> instance of the class.</p>
<h2> Useful macros defined in ExtensionClass.h</h2>
<h2>Useful macros defined in ExtensionClass.h</h2>
<p> A number of useful macros are defined in ExtensionClass.h. <p> A number of useful macros are defined in ExtensionClass.h.
These are documented in <code>ExtensionClass.h</code>.</p> These are documented in <code>ExtensionClass.h</code>.</p>
<h2> Pickleability</h2>
<h2>Pickleability</h2>
<p> Classes created with ExtensionClass, including extension base <p> Classes created with ExtensionClass, including extension base
classes are automatically pickleable. The usual gymnastics classes are automatically pickleable. The usual gymnastics
necessary to pickle <code>non-standard</code> types are not necessray for necessary to pickle <code>non-standard</code> types are not necessray for
types that have been modified to be extension base classes.</p> types that have been modified to be extension base classes.</p>
<h2> Status</h2>
<h2>Status</h2>
<p> The current release of the extension class module is <a href="http://www.digicool.com/releases/ExtensionClass/ExtensionClass-1.1.tar.gz">1.1</a>. <p> The current release of the extension class module is <a href="http://www.digicool.com/releases/ExtensionClass/ExtensionClass-1.1.tar.gz">1.1</a>.
The core implementation has less than four thousand lines of code, The core implementation has less than four thousand lines of code,
including comments. This release requires Python 1.4 or higher.</p> including comments. This release requires Python 1.4 or higher.</p>
<p> To find out what's changed in this release, see the <p> To find out what's changed in this release, see the
<a href="release.html">release notes</a>.</p> <a href="release.html">release notes</a>.</p>
<p> <a href="Installation.html">Installation instructions</a>, are provided.</p>
<p> <a href="Installation.html">Installation instructions</a> are provided.</p> <h2> Issues</h2>
<h2>Issues</h2>
<p> There are a number of issues that came up in the course of this work <p> There are a number of issues that came up in the course of this work
and that deserve mention.</p> and that deserve mention.</p>
<ul><li><p>In Python 1.4, the class extension mechanism described in <a href="#4">[4]</a> required <ul>
<li><p>In Python 1.4, the class extension mechanism described in <a href="#4">[4]</a> required
that the first superclass in a list of super-classes must be of the that the first superclass in a list of super-classes must be of the
extended class type. This may not be convenient if mix-in extended class type. This may not be convenient if mix-in
behavior is desired. If a list of base classes starts with a behavior is desired. If a list of base classes starts with a
...@@ -647,16 +519,13 @@ ...@@ -647,16 +519,13 @@
definition. To get around this, the <code>ExtensionClass</code> module exports definition. To get around this, the <code>ExtensionClass</code> module exports
a base extension class, <code>Base</code>, that can be used as the first base a base extension class, <code>Base</code>, that can be used as the first base
class in a list of base classes to assure that an extension class in a list of base classes to assure that an extension
subclass is created.</p> subclass is created.<p> Python 1.5 allows the class extension even if the first non-class
<p> Python 1.5 allows the class extension even if the first non-class
object in the list of base classes is not the first object in object in the list of base classes is not the first object in
the list. This issue appears to go away in Python 1.5, however, the list. This issue appears to go away in Python 1.5, however,
the restriction that the first non-class object in a list of the restriction that the first non-class object in a list of
base classes must be the first in the list may reappear in later base classes must be the first in the list may reappear in later
versions of Python.</p> versions of Python.</p>
</p></li>
<li><p>Currently, only one base extension class can define any data in <li><p>Currently, only one base extension class can define any data in
C. The data layout of subclasses-instances is the same as for the C. The data layout of subclasses-instances is the same as for the
base class that defines data in C, except that the data structure base class that defines data in C, except that the data structure
...@@ -671,13 +540,9 @@ ...@@ -671,13 +540,9 @@
to make sure that methods were bound to the correct base data to make sure that methods were bound to the correct base data
structure. Alternatively, the signature of C methods could be structure. Alternatively, the signature of C methods could be
expanded to allow pointers to expected class data to be passed expanded to allow pointers to expected class data to be passed
in addition to object pointers.</p> in addition to object pointers.</p></li>
<li><p>There is currently no support for sub-classing in C, beyond that <li><p>There is currently no support for sub-classing in C, beyond that
provided by method chains.</p> provided by method chains.</p></li>
<li><p>Rules for mixed-type arithmetic are different for python class <li><p>Rules for mixed-type arithmetic are different for python class
instances than they are for extension type instances. Python instances than they are for extension type instances. Python
classes can define right and left versions of numeric binary classes can define right and left versions of numeric binary
...@@ -689,83 +554,62 @@ ...@@ -689,83 +554,62 @@
classes are based on extension types, they are currently limited classes are based on extension types, they are currently limited
to the coercion-based approach. It should be possible to to the coercion-based approach. It should be possible to
extend the extension class implementation to allow both types of extend the extension class implementation to allow both types of
mixed-type arithmetic control.</p> mixed-type arithmetic control.</p></li>
<li><p>I considered making extension classes immutable, meaning that <li><p>I considered making extension classes immutable, meaning that
class attributes could not be set after class creation. I also class attributes could not be set after class creation. I also
considered making extension subclasses cache inherited considered making extension subclasses cache inherited
attributes. Both of these are related and attractive for some attributes. Both of these are related and attractive for some
applications, however, I decided that it would be better to retain applications, however, I decided that it would be better to retain
standard class instance semantics and provide these features as standard class instance semantics and provide these features as
options at a later time.</p> options at a later time.</p></li>
<li><p>The extension class module defines new method types to bind C and <li><p>The extension class module defines new method types to bind C and
python methods to extension class instances. It would be useful python methods to extension class instances. It would be useful
for these method objects to provide access to function call for these method objects to provide access to function call
information, such as the number and names of arguments and the information, such as the number and names of arguments and the
number of defaults, by parsing extension function documentation number of defaults, by parsing extension function documentation
strings.</p> strings.</p></li>
</ul> </ul>
<h2> Applications</h2>
<h2>Applications</h2>
<p> Aside from test and demonstration applications, the extension class <p> Aside from test and demonstration applications, the extension class
mechanism has been used to provide an extension-based implementation mechanism has been used to provide an extension-based implementation
of the persistence mechanism described in <a href="#1">[1]</a>. We have developed of the persistence mechanism described in <a href="#1">[1]</a>. We have developed
this further to provide features such as automatic deactivation of this further to provide features such as automatic deactivation of
objects not used after some period of time and to provide more objects not used after some period of time and to provide more
efficient persistent-object cache management.</p> efficient persistent-object cache management.</p>
<p> Acquisition has been heavily used in our recent products. <p> Acquisition has been heavily used in our recent products.
Synchonized classes have also been used in recent products.</p> Synchonized classes have also been used in recent products.</p>
<h2> Summary</h2>
<h2>Summary</h2>
<p> The extension-class mechanism described here provides a way to add <p> The extension-class mechanism described here provides a way to add
class services to extension types. It allows:</p> class services to extension types. It allows:
<ul><li><p>Sub-classing extension classes in Python,</p> <ul>
<li><p>Sub-classing extension classes in Python,</p></li>
<li><p>Construction of extension class instances by calling extension <li><p>Construction of extension class instances by calling extension
classes,</p> classes,</p></li>
<li><p>Extension classes to provide meta-data, such as unbound methods <li><p>Extension classes to provide meta-data, such as unbound methods
and their documentation string.</p> and their documentation string.</p></li>
</ul> </ul>
</p>
<p> In addition, the extension class module provides a relatively <p> In addition, the extension class module provides a relatively
concise example of the use of mechanisms that were added to Python concise example of the use of mechanisms that were added to Python
to support MESS <a href="#6">[6]</a>, and that were described at the fourth Python to support MESS <a href="#6">[6]</a>, and that were described at the fourth Python
Workshop <a href="#4">[4]</a>. It is hoped that this will spur research in improved Workshop <a href="#4">[4]</a>. It is hoped that this will spur research in improved
and specialized models for class implementation in Python.</p> and specialized models for class implementation in Python.</p>
<p> References</p> <p> References</p>
<p>.. <a href="#1">[1]</a> Fulton, J., <a href="http://www.digicool.com/papers/Persistence.html">Providing Persistence for World-Wide-Web Applications</a>,
<p> <a name="1">[1]</a> Fulton, J., <a href="http://www.digicool.com/papers/Persistence.html">Providing Persistence for World-Wide-Web Applications</a>
Proceedings of the 5th Python Workshop.</p> Proceedings of the 5th Python Workshop.</p>
<p>.. <a href="#2">[2]</a> Page, R. and Cropper, S., <a href="http://www.digicool.com/papers/DocumentTemplate.html">Document Template</a>,
<p> <a name="2">[2]</a> Page, R. and Cropper, S., <a href="http://www.digicool.com/papers/DocumentTemplate.html">Document Template</a>
Proceedings of the 5th Python Workshop.</p> Proceedings of the 5th Python Workshop.</p>
<p>.. <a href="#3">[3]</a> Beaudry, D., <a href="http://www.python.org/workshops/1994-11/BuiltInClasses/BuiltInClasses_1.html">Deriving Built-In Classes in Python</a>,
<p> <a name="3">[3]</a> Beaudry, D., <a href="http://www.python.org/workshops/1994-11/BuiltInClasses/BuiltInClasses_1.html">Deriving Built-In Classes in Python</a>
Proceedings of the First International Python Workshop.</p> Proceedings of the First International Python Workshop.</p>
<p>.. <a href="#4">[4]</a> Van Rossum, G., <a href="http://www.python.org/workshops/1996-06/notes/thursday.html">Don Beaudry Hack - MESS</a>,
<p> <a name="4">[4]</a> Van Rossum, G., <a href="http://www.python.org/workshops/1996-06/notes/thursday.html">Don Beaudry Hack - MESS</a>
presented in the Developer's Future Enhancements session of the presented in the Developer's Future Enhancements session of the
4th Python Workshop. </p> 4th Python Workshop. </p>
<p>.. <a href="#5">[5]</a> Fulton, J., <a href="http://www.digicool.com/jim/MetaType.c">Meta-Type Object</a>,
<p> <a name="5">[5]</a> Fulton, J., <a href="http://www.digicool.com/jim/MetaType.c">Meta-Type Object</a>
This is a small proposal, the text of which is contained in a This is a small proposal, the text of which is contained in a
sample implementation source file, </p> sample implementation source file, </p>
<p>.. <a href="#6">[6]</a> Beaudry, D., and Ascher, D., <a href="http://starship.skyport.net/~da/mess/">The Meta-Extension Set</a>.</p>
<p> <a name="6">[6]</a> Beaudry, D., and Ascher, D., "The Meta-Extension Set", </body>
http://starship.skyport.net/~da/mess/. </html>
</p>
lib/python/StructuredText/regressions/MultiMapping.ref
View file @ 89994a14
<html>
<head>
<title>Example: MultiMapping objects</title>
</head>
<body>
<h1>Example: MultiMapping objects</h1> <h1>Example: MultiMapping objects</h1>
<p> <a href="COPYRIGHT.html">Copyright (C) 1996-1998, Digital Creations</a>.</p> <p> <a href="COPYRIGHT.html">Copyright (C) 1996-1998, Digital Creations</a>.</p>
<p> As an example, consider an extension class that implements a <p> As an example, consider an extension class that implements a
"MultiMapping". A multi-mapping is an object that encapsulates 0 "MultiMapping". A multi-mapping is an object that encapsulates 0
or more mapping objects. When an attempt is made to lookup an or more mapping objects. When an attempt is made to lookup an
object, the encapsulated mapping objects are searched until an object, the encapsulated mapping objects are searched until an
object is found.</p> object is found.</p>
<p> Consider an implementation of a MultiMapping extension type, <p> Consider an implementation of a MultiMapping extension type,
without use of the extension class mechanism:</p> without use of the extension class mechanism:
<PRE> <pre>
#include &quot;Python.h&quot; #include "Python.h"
#define UNLESS(E) if(!(E)) #define UNLESS(E) if(!(E))
...@@ -24,7 +27,7 @@ ...@@ -24,7 +27,7 @@
static PyObject * static PyObject *
MM_push(MMobject *self, PyObject *args){ MM_push(MMobject *self, PyObject *args){
PyObject *src; PyObject *src;
UNLESS(PyArg_ParseTuple(args, &quot;O&quot;, &amp;src)) return NULL; UNLESS(PyArg_ParseTuple(args, "O", &amp;src)) return NULL;
UNLESS(-1 != PyList_Append(self-&gt;data,src)) return NULL; UNLESS(-1 != PyList_Append(self-&gt;data,src)) return NULL;
Py_INCREF(Py_None); Py_INCREF(Py_None);
return Py_None; return Py_None;
...@@ -37,7 +40,7 @@ ...@@ -37,7 +40,7 @@
static PyObject *emptyList=0; static PyObject *emptyList=0;
UNLESS(emptyList) UNLESS(emptyList=PyList_New(0)) return NULL; UNLESS(emptyList) UNLESS(emptyList=PyList_New(0)) return NULL;
UNLESS(PyArg_ParseTuple(args, &quot;&quot;)) return NULL; UNLESS(PyArg_ParseTuple(args, "")) return NULL;
UNLESS(-1 != (l=PyList_Size(self-&gt;data))) return NULL; UNLESS(-1 != (l=PyList_Size(self-&gt;data))) return NULL;
l--; l--;
UNLESS(r=PySequence_GetItem(self-&gt;data,l)) return NULL; UNLESS(r=PySequence_GetItem(self-&gt;data,l)) return NULL;
...@@ -49,10 +52,10 @@ ...@@ -49,10 +52,10 @@
} }
static struct PyMethodDef MM_methods[] = { static struct PyMethodDef MM_methods[] = {
{&quot;push&quot;, (PyCFunction) MM_push, 1, {"push", (PyCFunction) MM_push, 1,
&quot;push(mapping_object) -- Add a data source&quot;}, "push(mapping_object) -- Add a data source"},
{&quot;pop&quot;, (PyCFunction) MM_pop, 1, {"pop", (PyCFunction) MM_pop, 1,
&quot;pop() -- Remove and return the last data source added&quot;}, "pop() -- Remove and return the last data source added"},
{NULL, NULL} /* sentinel */ {NULL, NULL} /* sentinel */
}; };
...@@ -60,7 +63,7 @@ ...@@ -60,7 +63,7 @@
newMMobject(PyObject *ignored, PyObject *args){ newMMobject(PyObject *ignored, PyObject *args){
MMobject *self; MMobject *self;
UNLESS(PyArg_ParseTuple(args, &quot;&quot;)) return NULL; UNLESS(PyArg_ParseTuple(args, "")) return NULL;
UNLESS(self = PyObject_NEW(MMobject, &amp;MMtype)) return NULL; UNLESS(self = PyObject_NEW(MMobject, &amp;MMtype)) return NULL;
UNLESS(self-&gt;data=PyList_New(0)) goto err; UNLESS(self-&gt;data=PyList_New(0)) goto err;
return (PyObject *)self; return (PyObject *)self;
...@@ -120,13 +123,13 @@ ...@@ -120,13 +123,13 @@
/* -------------------------------------------------------- */ /* -------------------------------------------------------- */
static char MMtype__doc__[] = static char MMtype__doc__[] =
&quot;MultiMapping -- Combine multiple mapping objects for lookup&quot; "MultiMapping -- Combine multiple mapping objects for lookup"
; ;
static PyTypeObject MMtype = { static PyTypeObject MMtype = {
PyObject_HEAD_INIT(&amp;PyType_Type) PyObject_HEAD_INIT(&amp;PyType_Type)
0, /*ob_size*/ 0, /*ob_size*/
&quot;MultMapping&quot;, /*tp_name*/ "MultMapping", /*tp_name*/
sizeof(MMobject), /*tp_basicsize*/ sizeof(MMobject), /*tp_basicsize*/
0, /*tp_itemsize*/ 0, /*tp_itemsize*/
/* methods */ /* methods */
...@@ -149,8 +152,8 @@ ...@@ -149,8 +152,8 @@
}; };
static struct PyMethodDef MultiMapping_methods[] = { static struct PyMethodDef MultiMapping_methods[] = {
{&quot;MultiMapping&quot;, (PyCFunction)newMMobject, 1, {"MultiMapping", (PyCFunction)newMMobject, 1,
&quot;MultiMapping() -- Create a new empty multi-mapping&quot;}, "MultiMapping() -- Create a new empty multi-mapping"},
{NULL, NULL} /* sentinel */ {NULL, NULL} /* sentinel */
}; };
...@@ -159,16 +162,15 @@ ...@@ -159,16 +162,15 @@
PyObject *m; PyObject *m;
m = Py_InitModule4( m = Py_InitModule4(
&quot;MultiMapping&quot;, MultiMapping_methods, "MultiMapping", MultiMapping_methods,
&quot;MultiMapping -- Wrap multiple mapping objects for lookup&quot;, "MultiMapping -- Wrap multiple mapping objects for lookup",
(PyObject*)NULL,PYTHON_API_VERSION); (PyObject*)NULL,PYTHON_API_VERSION);
if (PyErr_Occurred()) if (PyErr_Occurred())
Py_FatalError(&quot;can't initialize module MultiMapping&quot;); Py_FatalError("can't initialize module MultiMapping");
} }
</pre>
</PRE> </p>
<p> This module defines an extension type, <code>MultiMapping</code>, and exports a <p> This module defines an extension type, <code>MultiMapping</code>, and exports a
module function, <code>MultiMapping</code>, that creates <code>MultiMapping</code> module function, <code>MultiMapping</code>, that creates <code>MultiMapping</code>
Instances. The type provides two methods, <code>push</code>, and <code>pop</code>, for Instances. The type provides two methods, <code>push</code>, and <code>pop</code>, for
...@@ -176,12 +178,11 @@ ...@@ -176,12 +178,11 @@
The type provides mapping behavior, implementing mapping length The type provides mapping behavior, implementing mapping length
and subscript operators but not mapping a subscript assignment and subscript operators but not mapping a subscript assignment
operator.</p> operator.</p>
<p> Now consider an extension class implementation of MultiMapping <p> Now consider an extension class implementation of MultiMapping
objects:</p> objects:
<PRE> <pre>
#include &quot;Python.h&quot; #include "Python.h"
#include &quot;ExtensionClass.h&quot; #include "ExtensionClass.h"
#define UNLESS(E) if(!(E)) #define UNLESS(E) if(!(E))
...@@ -198,7 +199,7 @@ ...@@ -198,7 +199,7 @@
PyObject *args; PyObject *args;
{ {
PyObject *src; PyObject *src;
UNLESS(PyArg_ParseTuple(args, &quot;O&quot;, &amp;src)) return NULL; UNLESS(PyArg_ParseTuple(args, "O", &amp;src)) return NULL;
UNLESS(-1 != PyList_Append(self-&gt;data,src)) return NULL; UNLESS(-1 != PyList_Append(self-&gt;data,src)) return NULL;
Py_INCREF(Py_None); Py_INCREF(Py_None);
return Py_None; return Py_None;
...@@ -214,7 +215,7 @@ ...@@ -214,7 +215,7 @@
static PyObject *emptyList=0; static PyObject *emptyList=0;
UNLESS(emptyList) UNLESS(emptyList=PyList_New(0)) return NULL; UNLESS(emptyList) UNLESS(emptyList=PyList_New(0)) return NULL;
UNLESS(PyArg_ParseTuple(args, &quot;&quot;)) return NULL; UNLESS(PyArg_ParseTuple(args, "")) return NULL;
UNLESS(-1 != (l=PyList_Size(self-&gt;data))) return NULL; UNLESS(-1 != (l=PyList_Size(self-&gt;data))) return NULL;
l--; l--;
UNLESS(r=PySequence_GetItem(self-&gt;data,l)) return NULL; UNLESS(r=PySequence_GetItem(self-&gt;data,l)) return NULL;
...@@ -230,7 +231,7 @@ ...@@ -230,7 +231,7 @@
MMobject *self; MMobject *self;
PyObject *args; PyObject *args;
{ {
UNLESS(PyArg_ParseTuple(args, &quot;&quot;)) return NULL; UNLESS(PyArg_ParseTuple(args, "")) return NULL;
UNLESS(self-&gt;data=PyList_New(0)) goto err; UNLESS(self-&gt;data=PyList_New(0)) goto err;
Py_INCREF(Py_None); Py_INCREF(Py_None);
return Py_None; return Py_None;
...@@ -240,12 +241,12 @@ ...@@ -240,12 +241,12 @@
} }
static struct PyMethodDef MM_methods[] = { static struct PyMethodDef MM_methods[] = {
{&quot;__init__&quot;, (PyCFunction)MM__init__, 1, {"__init__", (PyCFunction)MM__init__, 1,
&quot;__init__() -- Create a new empty multi-mapping&quot;}, "__init__() -- Create a new empty multi-mapping"},
{&quot;push&quot;, (PyCFunction) MM_push, 1, {"push", (PyCFunction) MM_push, 1,
&quot;push(mapping_object) -- Add a data source&quot;}, "push(mapping_object) -- Add a data source"},
{&quot;pop&quot;, (PyCFunction) MM_pop, 1, {"pop", (PyCFunction) MM_pop, 1,
&quot;pop() -- Remove and return the last data source added&quot;}, "pop() -- Remove and return the last data source added"},
{NULL, NULL} /* sentinel */ {NULL, NULL} /* sentinel */
}; };
...@@ -310,13 +311,13 @@ ...@@ -310,13 +311,13 @@
/* -------------------------------------------------------- */ /* -------------------------------------------------------- */
static char MMtype__doc__[] = static char MMtype__doc__[] =
&quot;MultiMapping -- Combine multiple mapping objects for lookup&quot; "MultiMapping -- Combine multiple mapping objects for lookup"
; ;
static PyExtensionClass MMtype = { static PyExtensionClass MMtype = {
PyObject_HEAD_INIT(&amp;PyType_Type) PyObject_HEAD_INIT(&amp;PyType_Type)
0, /*ob_size*/ 0, /*ob_size*/
&quot;MultMapping&quot;, /*tp_name*/ "MultMapping", /*tp_name*/
sizeof(MMobject), /*tp_basicsize*/ sizeof(MMobject), /*tp_basicsize*/
0, /*tp_itemsize*/ 0, /*tp_itemsize*/
/* methods */ /* methods */
...@@ -349,37 +350,34 @@ ...@@ -349,37 +350,34 @@
PyObject *m, *d; PyObject *m, *d;
m = Py_InitModule4( m = Py_InitModule4(
&quot;MultiMapping&quot;, MultiMapping_methods, "MultiMapping", MultiMapping_methods,
&quot;MultiMapping -- Wrap multiple mapping objects for lookup&quot;, "MultiMapping -- Wrap multiple mapping objects for lookup",
(PyObject*)NULL,PYTHON_API_VERSION); (PyObject*)NULL,PYTHON_API_VERSION);
d = PyModule_GetDict(m); d = PyModule_GetDict(m);
PyExtensionClass_Export(d,&quot;MultiMapping&quot;,MMtype); PyExtensionClass_Export(d,"MultiMapping",MMtype);
if (PyErr_Occurred()) if (PyErr_Occurred())
Py_FatalError(&quot;can't initialize module MultiMapping&quot;); Py_FatalError("can't initialize module MultiMapping");
} }
</pre>
</PRE> </p>
<p> This version includes <code>ExtensionClass.h</code>. The two declarations of <p> This version includes <code>ExtensionClass.h</code>. The two declarations of
<code>MMtype</code> have been changed from <code>PyTypeObject</code> to <code>PyExtensionClass</code>. <code>MMtype</code> have been changed from <code>PyTypeObject</code> to <code>PyExtensionClass</code>.
The <code>METHOD_CHAIN</code> macro has been used to add methods to the end of The 'METHOD<u>CHAIN' macro has been used to add methods to the end of
the definition for <code>MMtype</code>. The module function, newMMobject has the definition for <code>MMtype</code>. The module function, newMMobject has
been replaced by the <code>MMtype</code> method, <code>MM__init__</code>. Note that this been replaced by the <code>MMtype</code> method, 'MM</u><u>init</u>_'. Note that this
method does not create or return a new object. Finally, the lines:</p> method does not create or return a new object. Finally, the lines:
<PRE> <pre>
d = PyModule_GetDict(m); d = PyModule_GetDict(m);
PyExtensionClass_Export(d,&quot;MultiMapping&quot;,MMtype); PyExtensionClass_Export(d,"MultiMapping",MMtype);
</pre>
</PRE> </p>
<p> Have been added to both initialize the extension class and to export <p> Have been added to both initialize the extension class and to export
it in the module dictionary.</p> it in the module dictionary.</p>
<p> To use this module, compile, link, and import it as with any other <p> To use this module, compile, link, and import it as with any other
extension module. The following python code illustrates the extension module. The following python code illustrates the
module's use:</p> module's use:
<PRE> <pre>
from MultiMapping import MultiMapping from MultiMapping import MultiMapping
m=MultiMapping() m=MultiMapping()
m.push({'spam':1, 'eggs':2}) m.push({'spam':1, 'eggs':2})
...@@ -388,16 +386,15 @@ ...@@ -388,16 +386,15 @@
m['spam'] # returns 3 m['spam'] # returns 3
m['ham'] # returns 4 m['ham'] # returns 4
m['foo'] # raises a key error m['foo'] # raises a key error
</pre>
</PRE> </p>
<p> Creating the <code>MultiMapping</code> object took three steps, one to create <p> Creating the <code>MultiMapping</code> object took three steps, one to create
an empty <code>MultiMapping</code>, and two to add mapping objects to it. We an empty <code>MultiMapping</code>, and two to add mapping objects to it. We
might wish to simplify the process of creating MultiMapping might wish to simplify the process of creating MultiMapping
objects by providing a constructor that takes source mapping objects by providing a constructor that takes source mapping
objects as parameters. We can do this by sub-classing MultiMapping objects as parameters. We can do this by sub-classing MultiMapping
in Python:</p> in Python:
<PRE> <pre>
from MultiMapping import MultiMapping from MultiMapping import MultiMapping
class ExtendedMultiMapping(MultiMapping): class ExtendedMultiMapping(MultiMapping):
def __init__(self,*data): def __init__(self,*data):
...@@ -409,13 +406,11 @@ ...@@ -409,13 +406,11 @@
m['spam'] # returns 3 m['spam'] # returns 3
m['ham'] # returns 4 m['ham'] # returns 4
m['foo'] # raises a key error m['foo'] # raises a key error
</pre>
</PRE> </p>
<p> Note that the source file included in the ExtensionClass <p> Note that the source file included in the ExtensionClass
distribution has numerous enhancements beyond the version shown in distribution has numerous enhancements beyond the version shown in
this document. this document.</p>
</p> </body>
</html>
lib/python/StructuredText/regressions/examples.ref
View file @ 89994a14
<html>
<head>
<title>Small Trials for Structured Text Formatting</title>
</head>
<body>
<h1>Small Trials for Structured Text Formatting</h1> <h1>Small Trials for Structured Text Formatting</h1>
<p> This paragraph should be preceded by a level 1 header. It should <p> This paragraph should be preceded by a level 1 header. It should
not, itself, be made into a header, just a regular paragraph.</p> not, itself, be made into a header, just a regular paragraph.</p>
<p> Here are a few presentation styles, in a list <a href="#1">[1]</a>:</p> <p> Here are a few presentation styles, in a list <a href="#1">[1]</a>:</p>
<ul><li><p>A word: <em>emphasized</em>.</p> <ul>
<li><p>A word: <em>emphasized</em>.</p></li>
<li><p>A word: <u>underlined</u>.</p></li>
<li><p>A word: <u>underlined</u>.</p> <li><p>A word <strong>strong</strong>.</p></li>
<li><p>An inline example: <code>1+2</code>.</p></li>
<li><p>Another example with a different format:
<li><p>A word <strong>strong</strong>.</p> ``x='spam''' or ``y='spam''' or ``<dtml-var spam>'<code>.</code><p> We can use expressions in the DTML var tag as
in ``<dtml-var "x+'.txt'">''</p>
</p></li>
<li><p>A mult-line example:
<pre>
blah
*foo bar*
&lt;dtml-var yeha&gt;
</pre>
</p></li>
</ul> </ul>
<p>.. <a href="#1">[1]</a> (The referring text should be a paragraph, not a header, and
<p> <a name="1">[1]</a> (The referring text should be a paragraph, not a header, and should contain a reference to this footnote, footnote "<a href="#1">[1]</a>".)<p> Some hrefs, in a definition list:</p>
should contain a reference to this footnote, footnote "[1]".)</p> <dl>
<p> Some hrefs, in a definition list:</p> <dt> <u>Regular</u></dt>
<dd><a href="http://www.zope.org">http://www.zope.org/</a></dd>
<dl><dt> <u>Regular</u><dd><p><a href="http://www.zope.org">http://www.zope.org/</a></p> <dt> <u>W/trailing punctuation</u></dt>
<dd><a href="http://www.zope.org">http://www.zope.org/</a>.</dd>
<dt> <u>W protocol implicit</u></dt>
<dt> <u>W/trailing punctuation</u><dd><p><a href="http://www.zope.org">http://www.zope.org/</a>.</p> <dd><a href=":locallink">locallink</a></dd>
<dt> <u>W protocol implicit</u>, alternate</dt>
<dd>"locallink", :locallink</dd>
<dt> <u>W protocol implicit</u><dd><p><a href="locallink">locallink</a></p>
<dt> <u>W protocol implicit</u>, alternate<dd><p><a href="locallink">locallink</a></p>
</dl> </dl>
<p> <p> |||| A Simple Two-column Table ||
<TABLE BORDER=1 CELLPADDING=2> || Column A || Column B ||
<TR> || Apples || Oranges ||</p>
<TD ALIGN=CENTER COLSPAN=2> A Simple Two-column Table </TD> </p>
</TR> </body>
<TR> </html>
<TD ALIGN=CENTER COLSPAN=1> Column A </TD>
<TD ALIGN=CENTER COLSPAN=1> Column B </TD>
</TR>
<TR>
<TD ALIGN=CENTER COLSPAN=1> Apples </TD>
<TD ALIGN=CENTER COLSPAN=1> Oranges </TD>
</TR>
</TABLE></p>
<p>
<TABLE BORDER=1 CELLPADDING=2>
</TABLE></p>
lib/python/StructuredText/regressions/index.ref
View file @ 89994a14
<p> <html>
Extension Class</p> <head>
<title>Extension Class</title>
</head>
<body>
<h1>Extension Class</h1>
<p> <a href="COPYRIGHT.html">Copyright (C) 1996-1998, Digital Creations</a>.</p> <p> <a href="COPYRIGHT.html">Copyright (C) 1996-1998, Digital Creations</a>.</p>
<p> A lightweight mechanism has been developed for making Python <p> A lightweight mechanism has been developed for making Python
extension types more class-like. Classes can be developed in an extension types more class-like. Classes can be developed in an
extension language, such as C or C++, and these classes can be extension language, such as C or C++, and these classes can be
treated like other python classes:</p> treated like other python classes:</p>
<ul><li><p>They can be sub-classed in python,</p> <ul>
<li><p>They can be sub-classed in python,</p></li>
<li><p>They provide access to method documentation strings, and</p></li>
<li><p>They provide access to method documentation strings, and</p> <li><p>They can be used to directly create new instances.</p></li>
<li><p>They can be used to directly create new instances.</p>
</ul> </ul>
<p> Extension classes provide additional extensions to class and <p> Extension classes provide additional extensions to class and
instance semantics, including:</p> instance semantics, including:</p>
<ul><li><p>A protocol for accessing subobjects "in the context of" their <ul>
<li><p>A protocol for accessing subobjects "in the context of" their
containers. This is used to implement custom method types containers. This is used to implement custom method types
and <a href="Acquisition.html">environmental acquisition</a>.</p> and <a href="Acquisition.html">environmental acquisition</a>.</p></li>
<li><p>A protocol for overriding method call semantics. This is used <li><p>A protocol for overriding method call semantics. This is used
to implement "synchonized" classes and could be used to to implement "synchonized" classes and could be used to
implement argument type checking.</p> implement argument type checking.</p></li>
<li><p>A protocol for class initialization that supports execution of a <li><p>A protocol for class initialization that supports execution of a
special <code>__class_init__</code> method after a class has been special '_<u>class</u>init__' method after a class has been
initialized.</p> initialized. </p></li>
</ul> </ul>
<p> Extension classes illustrate how the Python class mechanism can be <p> Extension classes illustrate how the Python class mechanism can be
extended and may provide a basis for improved or specialized class extended and may provide a basis for improved or specialized class
models. </p> models. </p>
<h2> Releases</h2>
<h1>Releases</h1> <p> The current release is <a href="ExtensionClass-1.2.tar.gz">1.2</a>,
<p> The current release is <a href="ExtensionClass-1.2.tar.gz">1.2</a>
To find out what's changed in this release, To find out what's changed in this release,
see the <a href="release.html">release notes</a>.</p> see the <a href="release.html">release notes</a>.</p>
<p> Documentation is available <a href="ExtensionClass.html">on-line</a>.</p> <p> Documentation is available <a href="ExtensionClass.html">on-line</a>.</p>
<h3> Windows Binaries</h3>
<p> A win32 binary release, <a href="ec12.zip">ec12.zip</a>, is available. This
<h1>Windows Binaries</h1>
<p> A win32 binary release, <a href="ec12.zip">ec12.zip</a> is available. This
release includes all of the ExtensionClass modules built as release includes all of the ExtensionClass modules built as
Windows extension modules (.pyd) files. These were built for Windows extension modules (.pyd) files. These were built for
Python 1.5.1 using Microsoft Visual C++ 5.0 in "Release" mode.</p> Python 1.5.1 using Microsoft Visual C++ 5.0 in "Release" mode.</p>
</body>
</html>
<p>
<TABLE BORDER=1 CELLPADDING=2>
</TABLE></p>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7