Ticket #4568: core-howto.xhtml.patch

File core-howto.xhtml.patch, 80.6 KB (added by jdb, 6 years ago)
  • doc/core/howto/components.xhtml

     
    101101inheritance to break code into small reusable chunks. Let us continue with the
    102102Multiple Inheritance example, though, because it is often used in practice.</p>
    103103
    104 <p>What if both the Color and the Area base class defined the same method,
    105 perhaps <code>calculate</code>? Where would the implementation come from? The
    106 implementation that is located for <code>Square().calculate()</code> depends on
    107 the method resolution order, or MRO, and can change when programmers change
    108 seemingly unrelated things by refactoring classes in other parts of the system,
    109 causing obscure bugs. Our first thought might be to change the calculate method
    110 name to avoid name clashes, to perhaps <code>calculateArea</code> and
    111 <code>calculateColor</code>.  While explicit, this change could potentially
    112 require a large number of changes throughout a system, and is error-prone,
    113 especially when attempting to integrate two systems which you didn't write.</p>
     104<p>What if both the Color and the Area base class defined the same
     105method, perhaps <code>calculate</code>? Where would the implementation
     106come from? The implementation that is located
     107for <code>Square().calculate()</code> depends on the method resolution
     108order, or MRO, and can change when programmers change seemingly
     109unrelated things by refactoring classes in other parts of the system,
     110causing obscure bugs. Our first thought might be to change the
     111calculate method name to avoid name clashes, to
     112perhaps <code>calculateArea</code> and <code>calculateColor</code>.
     113While explicit, this change could potentially require a large number
     114of changes throughout a system, and is error-prone, especially when
     115attempting to integrate two systems which you didn't write.</p>
    114116
    115117<p>Let's imagine another example. We have an electric appliance, say a hair
    116118dryer. The hair dryer is American voltage. We have two electric sockets, one of
     
    152154now you have no hair dryer any more.
    153155</pre>
    154156
    155 <p>We are going to attempt to solve this problem by writing an Adapter for the
    156 <code>UKSocket</code> which converts the voltage for use with an American
     157<p>We are going to attempt to solve this problem by writing an Adapter for
     158the <code>UKSocket</code> which converts the voltage for use with an American
    157159hair dryer. An Adapter is a class which is constructed with one and only one
    158160argument, the <q>adaptee</q> or <q>original</q> object. In this example, we
    159161will show all code involved for clarity:</p>
     
    216218distinguishes an Interface definition from a Class.</p>
    217219
    218220<p>Now that we have a defined Interface, we can talk about objects using terms
    219 like this: <q>The <code>AmericanSocket</code> class implements the
    220 <code>IAmericanSocket</code> interface</q> and <q>Please give me an object which
     221like this: <q>The <code>AmericanSocket</code> class implements the <code>IAmericanSocket</code> interface</q> and <q>Please give me an object which
    221222adapts <code>UKSocket</code> to the <code>IAmericanSocket</code>
    222223interface</q>. We can make <em>declarations</em> about what interfaces a certain
    223224class implements, and we can request adapters which implement a certain
     
    236237        return 120
    237238</pre>
    238239
    239 <p>So, to declare that a class implements an interface, we simply call
    240 <code>zope.interface.implements</code> at the class level.</p>
     240<p>So, to declare that a class implements an interface, we simply
     241call <code>zope.interface.implements</code> at the class level.</p>
    241242
    242 <p>Now, let's say we want to rewrite the <code>AdaptToAmericanSocket</code>
    243 class as a real adapter. In this case we also specify it as implementing
    244 <code>IAmericanSocket</code>:</p>
     243<p>Now, let's say we want to rewrite
     244the <code>AdaptToAmericanSocket</code> class as a real adapter. In
     245this case we also specify it as
     246implementing <code>IAmericanSocket</code>:</p>
    245247
    246248<pre class="python">
    247249from zope.interface import implements
     
    325327
    326328<p>As you can see, the <code>AmericanSocket</code> instance claims to
    327329implement <code>IAmericanSocket</code>, but the <code>UKSocket</code>
    328 does not. If we wanted to use the <code>HairDryer</code> with the
    329 <code>AmericanSocket</code>, we could know that it would be safe to do so by
     330does not. If we wanted to use the <code>HairDryer</code> with the <code>AmericanSocket</code>, we could know that it would be safe to do so by
    330331checking whether it implements <code>IAmericanSocket</code>. However, if we
    331332decide we want to use <code>HairDryer</code> with a <code>UKSocket</code>
    332333instance, we must <em>adapt</em> it to <code>IAmericanSocket</code> before
     
    341342looks in the adapter registry for an adapter which implements the interface for
    342343the given instance's class. If it finds one, it constructs an instance of the
    343344Adapter class, passing the constructor the original instance, and returns it.
    344 Now the <code>HairDryer</code> can safely be used with the adapted
    345 <code>UKSocket</code>. But what happens if we attempt to adapt an object
     345Now the <code>HairDryer</code> can safely be used with the adapted  <code>UKSocket</code>. But what happens if we attempt to adapt an object
    346346which already implements <code>IAmericanSocket</code>? We simply get back the
    347347original instance:</p>
    348348
     
    432432True
    433433</pre>
    434434
    435 <p>If you want <code>MyThing</code> to inherit from <code>pb.Root</code> but
    436 <em>not</em> implement <code>IPBRoot</code> like <code>pb.Root</code> does,
     435<p>If you want <code>MyThing</code> to inherit from <code>pb.Root</code> but <em>not</em> implement <code>IPBRoot</code> like <code>pb.Root</code> does,
    437436use <code>implementOnly</code>:</p>
    438437
    439438<pre class="python">
  • doc/core/howto/defer.xhtml

     
    4444available (this series of functions is known as a series of
    4545<strong>callbacks</strong>, or a <strong>callback chain</strong>), together
    4646with a series of functions to be called if there is an error in the
    47 asychronous request (known as a series of <strong>errbacks</strong> or an
    48 <strong>errback chain</strong>). The asychronous library code calls the first
     47asychronous request (known as a series of <strong>errbacks</strong> or an  <strong>errback chain</strong>). The asychronous library code calls the first
    4948callback when the result is available, or the first errback when an error
    5049occurs, and the <code>Deferred</code> object then hands the results of each
    5150callback or errback function to the next function in the chain.</p>
     
    305304<p>What this means in a practical sense is in Case 1, the callback in line
    306305A will handle a success condition from <code>getDeferredFromSomewhere</code>,
    307306and the errback in line B will handle any errors that occur <em>from either the
    308 upstream source, or that occur in A</em>.  In Case 2, the errback in line C
    309 <em>will only handle an error condition raised by</em>
    310 <code>getDeferredFromSomewhere</code>, it will not do any handling of errors
     307upstream source, or that occur in A</em>.  In Case 2, the errback in line C  <em>will
     308only handle an error condition raised by</em> <code>getDeferredFromSomewhere</code>,
     309it will not do any handling of errors
    311310raised in <code>callback1</code>.</p>
    312311
    313312
     
    391390    return d
    392391</pre>
    393392
    394 <p> Our original implementation of <code>authenticateUser</code> expected
    395 <code>isValidUser</code> to be synchronous, but now we need to change it to handle both
     393<p> Our original implementation of <code>authenticateUser</code> expected  <code>isValidUser</code> to be synchronous, but now we need to change it to handle both
    396394synchronous and asynchronous implementations of <code>isValidUser</code>. For this, we
    397395use <code class="API" base="twisted.internet.defer">maybeDeferred</code> to
    398396call <code>isValidUser</code>, ensuring that the result of <code>isValidUser</code> is a Deferred,
     
    414412</pre>
    415413
    416414<p>
    417 Now <code>isValidUser</code> could be either <code>synchronousIsValidUser</code> or
    418 <code>asynchronousIsValidUser</code>.
     415Now <code>isValidUser</code> could be either <code>synchronousIsValidUser</code> or  <code>asynchronousIsValidUser</code>.
    419416</p>
    420417
    421418<p>It is also possible to modify <code>synchronousIsValidUser</code> to return
     
    437434dl = defer.DeferredList([deferred1, deferred2, deferred3])
    438435</pre>
    439436
    440 <p>You can now treat the DeferredList like an ordinary Deferred; you can call
    441 <code>addCallbacks</code> and so on.  The DeferredList will call its callback
     437<p>You can now treat the DeferredList like an ordinary Deferred; you can call  <code>addCallbacks</code> and so on.  The DeferredList will call its callback
    442438when all the deferreds have completed.  The callback will be called with a list
    443439of the results of the Deferreds it contains, like so:</p>
    444440
     
    552548class="footnote">Unless of course a later callback starts a fresh error &mdash;
    553549but as we've already noted, adding callbacks to a Deferred after its used in a
    554550DeferredList is confusing and usually avoided.</span>.  Passing a true value
    555 for the <code>consumeErrors</code> parameter will not change the behavior of
    556 <code>fireOnOneCallback</code> or <code>fireOnOneErrback</code>.</p>
     551for the <code>consumeErrors</code> parameter will not change the behavior of <code>fireOnOneCallback</code> or <code>fireOnOneErrback</code>.</p>
    557552
    558553<a name="class"></a>
    559554
     
    564559substitute for the docstrings in the Deferred class, but can provide guidelines
    565560for its use.</p>
    566561
    567 <p>There is a parallel overview of functions used by the Deferred's
    568 <em>creator</em> in <a href="gendefer.xhtml#class">Generating Deferreds</a>.</p>
     562<p>There is a parallel overview of functions used by the Deferred's  <em>creator</em> in <a href="gendefer.xhtml#class">Generating Deferreds</a>.</p>
    569563
    570564<h3>Basic Callback Functions</h3>
    571565
  • doc/core/howto/udp.xhtml

     
    8989class Helloer(DatagramProtocol):
    9090
    9191    def startProtocol(self):
    92         host = "192.168.1.1"
    93         port = 1234
     92        host = "192.168.1.1"
     93        port = 1234
    9494
    9595        self.transport.connect(host, port)
    9696        print "now we can only send to host %s port %d" % (host, port)
  • doc/core/howto/pb-intro.xhtml

     
    208208<p>There are 2 basic flavors that allow for copying objects remotely.  Again,
    209209you can use these by subclassing them.  In order to specify what state you want
    210210to have copied when these are serialized, you can either use the Python default
    211 <code class="python">__getstate__</code> or specialized method calls for that
     211 <code class="python">__getstate__</code> or specialized method calls for that
    212212flavor.</p>
    213213
    214214<p>
  • doc/core/howto/internet-overview.xhtml

     
    1919<p>Twisted Internet contains the various interfaces to the reactor
    2020API, whose usage is documented in the low-level chapter. Those APIs
    2121are <code class="API" base="twisted.internet.interfaces">IReactorCore</code>,
    22 <code class="API" base="twisted.internet.interfaces">IReactorTCP</code>,
    23 <code class="API" base="twisted.internet.interfaces">IReactorSSL</code>,
    24 <code class="API" base="twisted.internet.interfaces">IReactorUNIX</code>,
    25 <code class="API" base="twisted.internet.interfaces">IReactorUDP</code>,
    26 <code class="API" base="twisted.internet.interfaces">IReactorTime</code>,
    27 <code class="API" base="twisted.internet.interfaces">IReactorProcess</code>,
    28 <code class="API" base="twisted.internet.interfaces">IReactorMulticast</code>
     22 <code class="API" base="twisted.internet.interfaces">IReactorTCP</code>,
     23 <code class="API" base="twisted.internet.interfaces">IReactorSSL</code>,
     24 <code class="API" base="twisted.internet.interfaces">IReactorUNIX</code>,
     25 <code class="API" base="twisted.internet.interfaces">IReactorUDP</code>,
     26 <code class="API" base="twisted.internet.interfaces">IReactorTime</code>,
     27 <code class="API" base="twisted.internet.interfaces">IReactorProcess</code>,
     28 <code class="API" base="twisted.internet.interfaces">IReactorMulticast</code>
    2929and <code class="API" base="twisted.internet.interfaces">IReactorThreads</code>.
    3030The reactor APIs allow non-persistent calls to be made.</p>
    3131
  • doc/core/howto/deferredindepth.xhtml

     
    1212<p>Deferreds are quite possibly the single most confusing topic that a
    1313newcomer to Twisted has to deal with. I am going to forgo the normal talk
    1414about what deferreds are, what they aren't, and why they're used in Twisted.
    15 Instead, I'm going show you the logic behind what they
    16 <strong>do</strong>.</p>
     15Instead, I'm going show you the logic behind what they <strong>do</strong>.</p>
    1716
    1817
    1918<p>A deferred allows you to encapsulate the logic that you'd normally use to
     
    255254</pre>
    256255
    257256<p>Two things to note here. First, &quot;- A -&quot; was skipped, like we wanted it to,
    258 and the second thing is that after &quot;- A -&quot;, noDecision is called, because
    259 <strong>it is the next errback that exists in the chain</strong>. It returns a
     257and the second thing is that after &quot;- A -&quot;, noDecision is called, because  <strong>it is the next errback that exists in the chain</strong>. It returns a
    260258non-failure, so processing continues with the next callback at &quot;- B -&quot;, and
    261259the errback at the end of the chain is never called </p>
    262260
  • doc/core/howto/pb-copyable.xhtml

     
    7575protocol that involved sending a file-like object with a <code>read()</code>
    7676method that was supposed to used later to retrieve a document. Then imagine
    7777what if that object were created with
    78 <code>os.fdopen("~/.gnupg/secring.gpg")</code>. Or an instance of
    79 <code>telnetlib.Telnet("localhost", "chargen")</code>. </p>
     78 <code>os.fdopen("~/.gnupg/secring.gpg")</code>. Or an instance of
     79 <code>telnetlib.Telnet("localhost", "chargen")</code>. </p>
    8080
    8181<p>Classes you've written for your own program are likely to have far more
    8282power. They may run code during <code>__init__</code>, or even have special
    8383meaning simply because of their existence. A program might have
    84 <code>User</code> objects to represent user accounts, and have a rule that
     84 <code>User</code> objects to represent user accounts, and have a rule that
    8585says all <code>User</code> objects in the system are referenced when
    8686authorizing a login session. (In this system, <code>User.__init__</code>
    8787would probably add the object to a global list of known users). The simple
     
    127127that a serialized representation A (of some remote object) can be
    128128unserialized into a local object of type B. It is these objects <q>B</q>
    129129that are the <q>Unjellyable</q> second argument of the
    130 <code>setUnjellyableForClass</code> function.
     130 <code>setUnjellyableForClass</code> function.
    131131In particular, <q>unjellyable</q> does <em>not</em> mean <q>cannot be
    132132jellied</q>. <code class="API"
    133133base="twisted.spread.jelly">Unpersistable</code> means <q>not
     
    143143the remote end sends an object, the class name that they transmit is looked
    144144up in the table controlled by this function. If a matching class is found,
    145145it is used to create the local object. If not, you get the
    146 <code>InsecureJelly</code> exception.</p>
     146 <code>InsecureJelly</code> exception.</p>
    147147
    148148<p>In general you expect both ends to share the same codebase: either you
    149149control the program that is running on both ends of the wire, or both
     
    152152the MyFooziWhatZit class unless you also had a definition for that class. So
    153153it is reasonable for the Jelly layer to reject all incoming classes except
    154154the ones that you have explicitly marked with
    155 <code>setUnjellyableForClass</code>. But keep in mind that the sender's idea
     155 <code>setUnjellyableForClass</code>. But keep in mind that the sender's idea
    156156of a <code>User</code> object might differ from the recipient's, either
    157157through namespace collisions between unrelated packages, version skew
    158158between nodes that haven't been updated at the same rate, or a malicious
     
    175175base="twisted.spread.pb">Serializable</code> classes. In this section,
    176176we focus on <code class="API" base="twisted.spread.pb">Copyable</code>.
    177177The copyable subclass of <code>LilyPond</code> is called
    178 <code>CopyPond</code>. We create an instance of it and send it through
    179 <code>callRemote</code> as an argument to the receiver's
    180 <code>remote_takePond</code> method. The Jelly layer will serialize
     178 <code>CopyPond</code>. We create an instance of it and send it through
     179 <code>callRemote</code> as an argument to the receiver's
     180 <code>remote_takePond</code> method. The Jelly layer will serialize
    181181(<q>jelly</q>) that object as an instance with a class name of
    182182<q>copy_sender.CopyPond</q> and some chunk of data that represents the
    183183object's state. <code>pond.__class__.__module__</code> and
    184 <code>pond.__class__.__name__</code> are used to derive the class name
     184 <code>pond.__class__.__name__</code> are used to derive the class name
    185185string. The object's <code class="API"
    186186base="twisted.spread.flavors.Copyable">getStateToCopy</code> method is
    187187used to get the state: this is provided by <code class="API"
    188188base="twisted.spread">pb.Copyable</code>, and the default just retrieves
    189 <code>self.__dict__</code>. This works just like the optional
    190 <code>__getstate__</code> method used by <code>pickle</code>. The pair of
     189 <code>self.__dict__</code>. This works just like the optional
     190 <code>__getstate__</code> method used by <code>pickle</code>. The pair of
    191191name and state are sent over the wire to the receiver.</p>
    192192
    193193<p>The receiving end defines a local class named <code>ReceiverPond</code>
     
    200200base="twisted.spread">pb.RemoteCopy</code>, which is a requirement for all
    201201classes that act in this local-representative role (those which are given to
    202202the second argument of <code>setUnjellyableForClass</code>).
    203 <code>RemoteCopy</code> provides the methods that tell the Jelly layer how
     203 <code>RemoteCopy</code> provides the methods that tell the Jelly layer how
    204204to create the local object from the incoming serialized state.</p>
    205205
    206206<p>Then <code>setUnjellyableForClass</code> is used to register the two
     
    212212<p>When the receiver unserializes (<q>unjellies</q>) the object, it will
    213213create an instance of the local <code>ReceiverPond</code> class, and hand
    214214the transmitted state (usually in the form of a dictionary) to that object's
    215 <code class="API"
     215 <code class="API"
    216216base="twisted.spread.flavors.RemoteCopy">setCopyableState</code> method.
    217217This acts just like the <code>__setstate__</code> method that
    218 <code>pickle</code> uses when unserializing an object.
    219 <code>getStateToCopy</code>/<code>setCopyableState</code> are distinct from
    220 <code>__getstate__</code>/<code>__setstate__</code> to allow objects to be
     218 <code>pickle</code> uses when unserializing an object.
     219 <code>getStateToCopy</code>/<code>setCopyableState</code> are distinct from
     220 <code>__getstate__</code>/<code>__setstate__</code> to allow objects to be
    221221persisted (across time) differently than they are transmitted (across
    222222[memory]space).</p>
    223223
     
    246246<h3>Controlling the Copied State</h3>
    247247
    248248<p>By overriding <code>getStateToCopy</code> and
    249 <code>setCopyableState</code>, you can control how the object is transmitted
     249 <code>setCopyableState</code>, you can control how the object is transmitted
    250250over the wire. For example, you might want perform some data-reduction:
    251251pre-compute some results instead of sending all the raw data over the wire.
    252252Or you could replace references to a local object on the sender's side with
     
    261261system. Combined with the fact that <code>Copyable</code> objects return
    262262unchanged from a round trip, this could be used to build a
    263263challenge-response system (in fact PB does this with
    264 <code>pb.Referenceable</code> objects to implement authorization as
     264 <code>pb.Referenceable</code> objects to implement authorization as
    265265described <a href="pb-cred.xhtml">here</a>).</p>
    266266
    267267<p>Whatever <code>getStateToCopy</code> returns from the sending object will
     
    422422useful to subclass or modify, so simply treat it as a little demon that sits
    423423in your <code>pb.Cacheable</code> class and helps you distribute change
    424424notifications. The only useful thing to do with it is to run its
    425 <code>callRemote</code> method, which acts just like a normal
    426 <code>pb.Referenceable</code>'s method of the same name.</span> that points at that receiver-side cache. Every time the state of the object
     425 <code>callRemote</code> method, which acts just like a normal
     426 <code>pb.Referenceable</code>'s method of the same name.</span> that points at that receiver-side cache. Every time the state of the object
    427427is changed, you give a message to the observer, informing them of the
    428428change. The other method, <code>stoppedObserving</code>, is called when the
    429429remote cache goes away, so that you can stop sending updates.</p>
    430430
    431431<p>On the receiver end, you make your cache class inherit from <code
    432432class="API" base="twisted.spread">pb.RemoteCache</code>, and implement the
    433 <code>setCopyableState</code> as you would for a <code>pb.RemoteCopy</code>
     433 <code>setCopyableState</code> as you would for a <code>pb.RemoteCopy</code>
    434434object. In addition, you must implement methods to receive the updates sent
    435435to the observer by the <code>pb.Cacheable</code>: these methods should have
    436436names that start with <code>observe_</code>, and match the
    437 <code>callRemote</code> invocations from the sender side just as the usual
    438 <code>remote_*</code> and <code>perspective_*</code> methods match normal
    439 <code>callRemote</code> calls. </p>
     437 <code>callRemote</code> invocations from the sender side just as the usual
     438 <code>remote_*</code> and <code>perspective_*</code> methods match normal
     439 <code>callRemote</code> calls. </p>
    440440
    441441<p>The first time a reference to the <code>pb.Cacheable</code> object is
    442442sent to any particular recipient, a sender-side Observer will be created for
     
    447447described above (in fact it inherits from that class). </p>
    448448
    449449<p>After that, your <q>setter</q> functions on the sender side should call
    450 <code>callRemote</code> on the Observer, which causes <code>observe_*</code>
     450 <code>callRemote</code> on the Observer, which causes <code>observe_*</code>
    451451methods to run on the receiver, which are then supposed to update the
    452452receiver-local (cached) state.</p>
    453453
     
    463463
    464464<p>With the <code>pb.Cacheable</code> and <code>pb.RemoteCache</code>
    465465classes in place, bound together by a call to
    466 <code>pb.setUnjellyableForClass</code>, all that remains is to pass a
     466 <code>pb.setUnjellyableForClass</code>, all that remains is to pass a
    467467reference to your <code>pb.Cacheable</code> over the wire to the remote end.
    468468The corresponding <code>pb.RemoteCache</code> object will automatically be
    469469created, and the matching methods will be used to keep the receiver-side
  • doc/core/howto/glossary.xhtml

     
    307307
    308308<dt><a name="SUX">SUX</a></dt>
    309309<dd><em>S</em>mall <em>U</em>ncomplicated <em>X</em>ML, Twisted's simple XML
    310 parser written in pure Python.  See
    311 <code class="API">twisted.web.sux</code>.</dd>
     310parser written in pure Python.  See <code class="API">twisted.web.sux</code>.</dd>
    312311
    313312<dt><a name="TAC">TAC</a></dt>
    314313<dd>A <em>T</em>wisted <em>A</em>pplication <em>C</em>onfiguration is a Python
  • doc/core/howto/pb-cred.xhtml

     
    3434
    3535<p>Imagine how you would write a chat server using PB. The first step might
    3636be a <code>ChatServer</code> object which had a bunch of
    37 <code>pb.RemoteReference</code>s that point at user clients. Pretend that
     37 <code>pb.RemoteReference</code>s that point at user clients. Pretend that
    3838those clients offered a <code>remote_print</code> method which lets the
    3939server print a message on the user's console. In that case, the server might
    4040look something like this:</p>
     
    6060</pre>
    6161
    6262<p>For now, assume that all clients have somehow acquired a
    63 <code>pb.RemoteReference</code> to this <code>ChatServer</code> object,
     63 <code>pb.RemoteReference</code> to this <code>ChatServer</code> object,
    6464perhaps using <code>pb.Root</code> and <code>getRootObject</code> as
    6565described in the <a href="pb-usage.xhtml">previous chapter</a>. In this
    6666scheme, when a user sends a message to the group, their client runs
     
    9999place to keep state is in an object, so this suggests we need a per-user
    100100object. Rather than choosing an obvious name<span class="footnote">The
    101101obvious name is clearly
    102 <code>ServerSidePerUserObjectWhichNobodyElseHasAccessTo</code>, but because
     102 <code>ServerSidePerUserObjectWhichNobodyElseHasAccessTo</code>, but because
    103103Python makes everything else so easy to read, it only seems fair to make
    104104your audience work for <em>something</em>.</span>, let's call this the
    105 <code>User</code> class.
     105 <code>User</code> class.
    106106</p>
    107107
    108108<pre class="python">
     
    134134</pre>
    135135
    136136<p>Again, assume that each remote client gets access to a single
    137 <code>User</code> object, which is created with the proper username.</p>
     137 <code>User</code> object, which is created with the proper username.</p>
    138138
    139139<p>Note how the <code>ChatServer</code> object has no remote access: it
    140140isn't even <code>pb.Referenceable</code> anymore. This means that all access
     
    143143
    144144<p>As long as Alice only has access to her own <code>User</code> object, she
    145145can no longer spoof Bob. The only way for her to invoke
    146 <code>ChatServer.sendMessage</code> is to call her <code>User</code>
     146 <code>ChatServer.sendMessage</code> is to call her <code>User</code>
    147147object's <code>remote_sendMessage</code> method, and that method uses its
    148148own state to provide the <code>from_username</code> argument. It doesn't
    149149give her any way to change that state.</p>
     
    151151<p>This restriction is important. The <code>User</code> object is able to
    152152maintain its own integrity because there is a wall between the object and
    153153the client: the client cannot inspect or modify internal state, like the
    154 <code>.name</code> attribute. The only way through this wall is via remote
     154 <code>.name</code> attribute. The only way through this wall is via remote
    155155method invocations, and the only control Alice has over those invocations is
    156156when they get invoked and what arguments they are given.</p>
    157157
     
    170170sensitive and calming them down after someone said <q>mattress</q> is a
    171171hassle that's best avoided altogether. Again, per-group state implies a
    172172per-group object. We'll go out on a limb and call this the
    173 <code>Group</code> object:</p>
     173 <code>Group</code> object:</p>
    174174
    175175<pre class="python">
    176176class User(pb.Referenceable):
     
    208208
    209209
    210210<p>This example takes advantage of the fact that
    211 <code>pb.Referenceable</code> objects sent over a wire can be returned to
     211 <code>pb.Referenceable</code> objects sent over a wire can be returned to
    212212you, and they will be turned into references to the same object that you
    213213originally sent. The client cannot modify the object in any way: all they
    214214can do is point at it and invoke its <code>remote_*</code> methods. Thus,
     
    232232into a <code>pb.RemoteReference</code> when it arrives at the client. The
    233233client sends it back to <code>Group.remote_send</code>, and PB turns it back
    234234into a reference to the original <code>User</code> when it gets there.
    235 <code>Group.remote_send</code> can then use its <code>.name</code> attribute
     235 <code>Group.remote_send</code> can then use its <code>.name</code> attribute
    236236as the sender of the message.</p>
    237237
    238238<div class="note">
     
    240240<p>Third party references (there aren't any)</p>
    241241
    242242<p>This technique also relies upon the fact that the
    243 <code>pb.Referenceable</code> reference can <em>only</em> come from someone
     243 <code>pb.Referenceable</code> reference can <em>only</em> come from someone
    244244who holds a corresponding <code>pb.RemoteReference</code>. The design of the
    245245serialization mechanism (implemented in <code
    246246class="API">twisted.spread.jelly</code>: pb, jelly, spread.. get it?  Look for
     
    254254dropped, further limiting the scope of those references.</p>
    255255
    256256<p>Futhermore, it is not possible for Bob to send <em>his</em>
    257 <code>User</code> reference to Alice (perhaps over some other PB channel
     257 <code>User</code> reference to Alice (perhaps over some other PB channel
    258258just between the two of them). Outside the context of Bob's connection to
    259259the server, that reference is just a meaningless number. To prevent
    260260confusion, PB will tell you if you try to give it away: when you try to hand
     
    287287
    288288
    289289<p>But again, note the vulnerability. If Alice holds a
    290 <code>RemoteReference</code> to <em>any</em> object on the server side that
     290 <code>RemoteReference</code> to <em>any</em> object on the server side that
    291291has a <code>.name</code> attribute, she can use that name as a spoofed
    292292<q>from</q> parameter. As a simple example, what if her client code looked
    293293like:</p>
     
    314314
    315315<p>There are two techniques to close this hole. The first is to have your
    316316remotely-invokable methods do type-checking on their arguments: if
    317 <code>Group.remote_send</code> asserted <code>isinstance(from_user,
     317 <code>Group.remote_send</code> asserted <code>isinstance(from_user,
    318318User)</code> then Alice couldn't use non-User objects to do her spoofing,
    319319and hopefully the rest of the system is designed well enough to prevent her
    320320from obtaining access to somebody else's User object.</p>
     
    325325<p>The second technique is to avoid having the client send you the objects
    326326altogether. If they don't send you anything, there is nothing to verify. In
    327327this case, you would have to have a per-user-per-group object, in which the
    328 <code>remote_send</code> method would only take a single
    329 <code>message</code> argument. The <code>UserGroup</code> object is created
     328 <code>remote_send</code> method would only take a single
     329 <code>message</code> argument. The <code>UserGroup</code> object is created
    330330with references to the only <code>User</code> and <code>Group</code> objects
    331331that it will ever use, so no lookups are needed:</p>
    332332
     
    353353</pre>
    354354
    355355<p>The only message-sending method Alice has left is
    356 <code>UserGroup.remote_send</code>, and it only accepts a message: there are
     356 <code>UserGroup.remote_send</code>, and it only accepts a message: there are
    357357no remaining ways to influence the <q>from</q> name.</p>
    358358
    359359<p>In this model, each remotely-accessible object represents a very small
     
    361361abilities to each remote user.</p>
    362362
    363363<p>PB provides a shortcut which makes this technique easier to use. The
    364 <code>Viewable</code> class will be discussed <a
     364 <code>Viewable</code> class will be discussed <a
    365365href="#viewable">below</a>.</p>
    366366
    367367<h2>Avatars and Perspectives</h2>
     
    382382
    383383<p>For PB, the first question is easy. The Avatar is a remotely-accessible
    384384object which can run code: this is a perfect description of
    385 <code>pb.Referenceable</code> and its subclasses. We shall defer the second
     385 <code>pb.Referenceable</code> and its subclasses. We shall defer the second
    386386question until the next section.</p>
    387387
    388388<p>In the example above, you can think of the <code>ChatServer</code> and
    389 <code>Group</code> objects as a service. The <code>User</code> object is the
     389 <code>Group</code> objects as a service. The <code>User</code> object is the
    390390user's server-side representative: everything the user is capable of doing
    391391is done by running one of its methods. Anything that the server wants to do
    392392to the user (change their group membership, change their name, delete their
     
    401401provides and controls (i.e. <q>brokers</q>) access to Perspectives.</p>
    402402
    403403<p>Once upon a time, these local-representative objects were actually called
    404 <code>pb.Perspective</code>. But this has changed with the advent of the
     404 <code>pb.Perspective</code>. But this has changed with the advent of the
    405405rewritten cred system, and now the more generic term for a local
    406406representative object is an Avatar. But you will still see reference to
    407407<q>Perspective</q> in the code, the docs, and the module names<span
    408408class="footnote">We could just go ahead and rename Perspective Broker to be
    409409Avatar Broker, but 1) that would cause massive compatibility problems, and 2)
    410 <q>AB</q> doesn't fit into the whole sandwich-themed naming scheme nearly as
     410 <q>AB</q> doesn't fit into the whole sandwich-themed naming scheme nearly as
    411411well as <q>PB</q> does. If we changed it to AB, we'd probably have to change
    412412Banana to be CD (CoderDecoder), and Jelly to be EF (EncapsulatorFragmentor).
    413413twisted.spread would then have to be renamed twisted.alphabetsoup, and then
     
    417417<p>Despite all we've been <a href="cred.xhtml">telling you</a> about how
    418418Avatars are more of a concept than an actual class, the base class from
    419419which you can create your server-side avatar-ish objects is, in fact, named
    420 <code>pb.Avatar</code><span class="footnote">The avatar-ish class is named
    421 <code>pb.Avatar</code> because <code>pb.Perspective</code> was already
     420 <code>pb.Avatar</code><span class="footnote">The avatar-ish class is named
     421 <code>pb.Avatar</code> because <code>pb.Perspective</code> was already
    422422taken, by the (now obsolete) oldcred perspective-ish class. It is a pity,
    423423but it simply wasn't possible both replace <code>pb.Perspective</code>
    424424in-place <em>and</em> maintain a reasonable level of
    425425backwards-compatibility.</span>. These objects behave very much like
    426 <code>pb.Referenceable</code>. The only difference is that instead of
     426 <code>pb.Referenceable</code>. The only difference is that instead of
    427427offering <q>remote_FOO</q> methods, they offer <q>perspective_FOO</q>
    428428methods.</p>
    429429
    430430<p>The other way in which <code>pb.Avatar</code> differs from
    431 <code>pb.Referenceable</code> is that the avatar objects are designed to be
     431 <code>pb.Referenceable</code> is that the avatar objects are designed to be
    432432the first thing retrieved by a cred-using remote client. Just as
    433 <code>PBClientFactory.getRootObject</code> gives the client access to a
    434 <code>pb.Root</code> object (which can then provide access to all kinds of
     433 <code>PBClientFactory.getRootObject</code> gives the client access to a
     434 <code>pb.Root</code> object (which can then provide access to all kinds of
    435435other objects), <code>PBClientFactory.login</code> gives client access to a
    436 <code>pb.Avatar</code> object (which can return other references). </p>
     436 <code>pb.Avatar</code> object (which can return other references). </p>
    437437
    438438<p>So, the first half of using cred in your PB application is to create an
    439439Avatar object which implements <code>perspective_</code> methods and is
     
    491491they can provide it with an optional <code>client</code> argument (which
    492492must be a <code>pb.Referenceable</code> object). If they do, then a
    493493reference to that object will be handed to the realm's
    494 <code>requestAvatar</code> in the <code>mind</code> argument.</p>
     494 <code>requestAvatar</code> in the <code>mind</code> argument.</p>
    495495
    496496<p>The server-side Perspective can use it to invoke remote methods on
    497497something in the client, so that the client doesn't always have to drive the
     
    523523that is exposed to the remote client.</p>
    524524
    525525<p>Second, we created a realm (an object which implements
    526 <code>IRealm</code>, and therefore implements <code>requestAvatar</code>).
     526 <code>IRealm</code>, and therefore implements <code>requestAvatar</code>).
    527527This realm manufactures <code>MyPerspective</code> objects. It makes as many
    528528as we want, and names each one with the avatarID (a username) that comes out
    529529of the checkers. This MyRealm object returns two other objects as well,
     
    534534Avatars for any which survive the authentication process.</p>
    535535
    536536<p>Fourth, we made a simple checker (an object which implements
    537 <code>IChecker</code>) to hold valid user/password pairs. The checker
     537 <code>IChecker</code>) to hold valid user/password pairs. The checker
    538538gets registered with the portal, so it knows who to ask when new
    539539clients connect.  We use a checker named
    540 <code>InMemoryUsernamePasswordDatabaseDontUse</code>, which suggests
     540 <code>InMemoryUsernamePasswordDatabaseDontUse</code>, which suggests
    541541that 1: all the username/password pairs are kept in memory instead of
    542542being saved to a database or something, and 2: you shouldn't use
    543543it. The admonition against using it is because there are better
     
    558558href="pb-usage.xhtml">before</a>) and attached to a TCP connection. When the
    559559connection completes, the factory will be asked to produce a Protocol, and
    560560it will create a PB object. Unlike the previous chapter, where we used
    561 <code>.getRootObject</code>, here we use <code>factory.login</code> to
    562 initiate the cred authentication process. We provide a
    563 <code>credentials</code> object, which is the client-side agent for doing
     561 <code>.getRootObject</code>, here we use <code>factory.login</code> to
     562 initiate the cred authentication process. We provide a
     563 <code>credentials</code> object, which is the client-side agent for doing
    564564our half of the authentication process. This process may involve several
    565565messages: challenges, responses, encrypted passwords, secure hashes, etc. We
    566566give our credentials object everything it will need to respond correctly (in
     
    568568used public-key encryption or even fancier techniques).</p>
    569569
    570570<p><code>login</code> returns a Deferred which, when it fires, will return a
    571 <code>pb.RemoteReference</code> to the remote avatar. We can then do
    572 <code>callRemote</code> to invoke a <code>perspective_foo</code> method on
     571 <code>pb.RemoteReference</code> to the remote avatar. We can then do
     572 <code>callRemote</code> to invoke a <code>perspective_foo</code> method on
    573573that Avatar.</p>
    574574
    575575
     
    580580
    581581<p>pbAnonServer.py implements a server based on pb6server.py, extending it to
    582582permit anonymous logins in addition to authenticated logins. An
    583 <code class="API" base="twisted.cred.checkers">AllowAnonymousAccess</code>
     583 <code class="API" base="twisted.cred.checkers">AllowAnonymousAccess</code>
    584584checker and an <code class="API"
    585585base="twisted.cred.checkers">InMemoryUsernamePasswordDatabaseDontUse</code>
    586586checker are registered and the
    587587client's choice of credentials object determines which is used to authenticate
    588588the login.  In either case, the realm will be called on to create an avatar for
    589589the login.  <code>AllowAnonymousAccess</code> always produces an <code>avatarId
    590 </code> of <code>twisted.cred.checkers.ANONYMOUS</code>.</p>
     590 </code> of <code>twisted.cred.checkers.ANONYMOUS</code>.</p>
    591591
    592592<p>On the client side, the only change is the use of an instance of
    593 <code class="API" base="twisted.cred.credentials">Anonymous</code> when calling
    594 <code class="API" base="twisted.spread.pb">PBClientFactory.login</code>.</p>
     593 <code class="API" base="twisted.cred.credentials">Anonymous</code> when calling
     594 <code class="API" base="twisted.spread.pb">PBClientFactory.login</code>.</p>
    595595
    596596
    597597<h2>Using Avatars</h2>
     
    621621<h3>Making Avatars</h3>
    622622
    623623<p>In the example above, we create Avatars upon request, during
    624 <code>requestAvatar</code>. Depending upon the service, these Avatars might
     624 <code>requestAvatar</code>. Depending upon the service, these Avatars might
    625625already exist before the connection is received, and might outlive the
    626626connection. The Avatars might also accept multiple connections.</p>
    627627
     
    633633Avatar later, once the lookup had completed.</p>
    634634
    635635<p>Here are some possible implementations of
    636 <code>MyRealm.requestAvatar</code>:</p>
     636 <code>MyRealm.requestAvatar</code>:</p>
    637637
    638638<pre class="python">
    639639    # pre-existing, static avatars
     
    695695avatar that a remote client has just attached. The Realm can also ask the
    696696protocol to let it know when the connection goes away, so it can then inform
    697697the Avatar that the client has detached. The third member of the
    698 <code>requestAvatar</code> return tuple is a callable which will be invoked
     698 <code>requestAvatar</code> return tuple is a callable which will be invoked
    699699when the connection is lost.</p>
    700700
    701701<pre class="python">
     
    727727represent users, the <code class="API"
    728728base="twisted.spread.flavors">Viewable</code> class can come into play. This
    729729class behaves a lot like <code>Referenceable</code>: it turns into a
    730 <code>RemoteReference</code> when sent over the wire, and certain methods
     730 <code>RemoteReference</code> when sent over the wire, and certain methods
    731731can be invoked by the holder of that reference. However, the methods that
    732 can be called have names that start with <code>view_</code> instead of
    733 <code>remote_</code>, and those methods are always called with an extra
     732can be called have names that start with <code>view_</code> instead of  <code>remote_</code>, and those methods are always called with an extra
    734733<code>perspective</code> argument that points to the Avatar through which
    735734the reference was sent:</p>
    736735
     
    751750just have per-group objects which inherit from <code>pb.Viewable</code>, and
    752751give the user references to them. The local <code>pb.Avatar</code> object
    753752will automatically show up as the <q>perspective</q> argument in the
    754 <code>view_*</code> method calls, give you a chance to involve the Avatar in
     753 <code>view_*</code> method calls, give you a chance to involve the Avatar in
    755754the process.</p>
    756755
    757756
     
    767766
    768767<p>Notice that the client uses <code>perspective_joinGroup</code> to both
    769768join a group and retrieve a <code>RemoteReference</code> to the
    770 <code>Group</code> object. However, the reference they get is actually to a
     769 <code>Group</code> object. However, the reference they get is actually to a
    771770special intermediate object called a <code>pb.ViewPoint</code>. When they do
    772 <code>group.callRemote("send", "message")</code>, their avatar is inserted
     771 <code>group.callRemote("send", "message")</code>, their avatar is inserted
    773772into the argument list that <code>Group.view_send</code> actually sees. This
    774773lets the group get their username out of the Avatar without giving the
    775774client an opportunity to spoof someone else.</p>
  • doc/core/howto/cred.xhtml

     
    6565<ul>
    6666<li><code class="API" base="twisted.cred.portal.Portal">login</code><code>(credentials, mind, *interfaces)</code>
    6767
    68 <p>The docstring is quite expansive (see <code class="API">twisted.cred.portal</code>), but in
     68<p>The docstring is quite expensive (see <code class="API">twisted.cred.portal</code>), but in
    6969brief, this is what you call when you need to call in order to connect
    7070a user to the system.  Typically you only pass in one interface, and the mind
    7171is <code class="python">None</code>. The interfaces are the possible interfaces the returned
  • doc/core/howto/testing.xhtml

     
    7272The <code>tearDown</code> method is a good place to put cleanup code: it is
    7373always run regardless of whether your test passes or fails (like a bare <code>
    7474except</code> clause in a try-except construct). Exceptions in <code>tearDown
    75 </code> are flagged as errors and flunk the test.
    76 <code class="API" base="twisted.trial.unittest">TestCase.addCleanup</code> is
     75 </code> are flagged as errors and flunk the test.
     76 <code class="API" base="twisted.trial.unittest">TestCase.addCleanup</code> is
    7777another useful tool for cleaning up.  With it, you can register callables to
    7878clean up resources as the test allocates them.  Generally, code should be
    7979written so that only resources allocated in the tests need to be cleaned up in
     
    8484return a Deferred from your test method, setUp, or tearDown and Trial will
    8585do the right thing. That is, it will run the reactor for you until the
    8686Deferred has triggered and its callbacks have been run. Don't use
    87 <code>reactor.run()</code>, <code>reactor.stop()</code>, <code>reactor.crash()</code> or <code>reactor.iterate()</code> in your tests.</p>
     87 <code>reactor.run()</code>, <code>reactor.stop()</code>, <code>reactor.crash()</code> or <code>reactor.iterate()</code> in your tests.</p>
    8888
    8989<p>Calls to <code>reactor.callLater</code> create <code class="API"
    9090base="twisted.internet.interfaces">IDelayedCall</code>s.  These need to be run
     
    132132<h3>Interacting with warnings in tests</h3>
    133133
    134134<p>Trial includes specific support for interacting with Python's
    135 <code>warnings</code> module.  This support allows warning-emitting code to
     135 <code>warnings</code> module.  This support allows warning-emitting code to
    136136be written test-driven, just as any other code would be.  It also improves
    137137the way in which warnings reporting when a test suite is running.</p>
    138138
     
    140140class="API" base="twisted.trial.unittest">TestCase.flushWarnings</code>
    141141allows tests to be written which make assertions about what warnings have
    142142been emitted during a particular test method. In order to test a warning with
    143 <code>flushWarnings</code>, write a test which first invokes the code which
     143 <code>flushWarnings</code>, write a test which first invokes the code which
    144144will emit a warning and then calls <code>flushWarnings</code> and makes
    145145assertions about the result.  For example:</p>
    146146
     
    161161method, it will not raise an exception when warnings have been configured as
    162162errors.  However, if called outside of a test method (for example, at module
    163163scope in a test module or a module imported by a test module) then it
    164 <em>will</em> raise an exception.</p>
     164 <em>will</em> raise an exception.</p>
    165165
    166166  </body>
    167167</html>
  • doc/core/howto/gendefer.xhtml

     
    120120d.addCallback(printNumber)
    121121</pre>
    122122
    123 <p>You will notice that despite creating a Deferred in the
    124 <code>largeFibonnaciNumber</code> function, these things happened:</p>
     123<p>You will notice that despite creating a Deferred in the  <code>largeFibonnaciNumber</code> function, these things happened:</p>
    125124<ul>
    126125<li>the &quot;Total time taken for largeFibonnaciNumber call&quot; output
    127126shows that the function did not return immediately as asynchronous functions
     
    286285
    287286<h3>Firing Deferreds more than once is impossible</h3>
    288287
    289 <p>Deferreds are one-shot. You can only call <code>Deferred.callback</code> or
    290 <code>Deferred.errback</code> once. The processing chain continues each time
     288<p>Deferreds are one-shot. You can only call <code>Deferred.callback</code> or <code>Deferred.errback</code> once. The processing chain continues each time
    291289you add new callbacks to an already-called-back-to Deferred.</p>
    292290
    293291<h3>Synchronous callback execution</h3>
    294292
    295 <p>If a Deferred already has a result available, <code>addCallback</code>
    296 <strong>may</strong> call the callback synchronously: that is, immediately
     293<p>If a Deferred already has a result available, <code>addCallback</code> <strong>may</strong> call the callback synchronously: that is, immediately
    297294after it's been added.  In situations where callbacks modify state, it is
    298295might be desirable for the chain of processing to halt until all callbacks are
    299296added. For this, it is possible to <code>pause</code> and <code>unpause</code>
     
    301298
    302299<p>Be careful when you use these methods! If you <code>pause</code> a
    303300Deferred, it is <em>your</em> responsibility to make sure that you unpause it.
    304 The function adding the callbacks must unpause a paused Deferred, it should
    305 <em>never</em> be the responsibility of the code that actually fires the
     301The function adding the callbacks must unpause a paused Deferred, it should <em>never</em> be the responsibility of the code that actually fires the
    306302callback chain by calling <code>callback</code> or <code>errback</code> as
    307303this would negate its usefulness!</p>
    308304
  • doc/core/howto/telnet.xhtml

     
    5858
    5959<p>The service object is the service used to serve the telnet shell,
    6060and that it is listening on port 4040 with something called a
    61 <code class="API" base="twisted.manhole.telnet">ShellFactory</code>.
     61 <code class="API" base="twisted.manhole.telnet">ShellFactory</code>.
    6262Its parent is a <code class="python">twisted.application.service.MultiService</code>,
    6363a collection of services. We can keep getting the parent attribute
    6464of services until we hit the root of all services.</p>
     
    6767running process, see the internal objects, and even change
    6868their attributes. The telnet server can of course be used from straight
    6969Python code; you can see how to do this by reading the code for
    70 <code class="API">twisted.tap.telnet</code>.</p>
     70 <code class="API">twisted.tap.telnet</code>.</p>
    7171
    7272<p>A final note - if you want access to be more secure, you can even
    7373have the telnet server use SSL. Assuming you have the appropriate
  • doc/core/howto/pb-limits.xhtml

     
    3232
    3333  <p>Another limit imposed by Twisted's Banana implementation is a limit on
    3434the size of long integers.  The purpose of this limit is the same as the
    35 <code>SIZE_LIMIT</code>.  By default, only integers between -2 ** 448 and 2
     35 <code>SIZE_LIMIT</code>.  By default, only integers between -2 ** 448 and 2
    3636** 448 (exclusive) can be transferred.  This limit can be changed using
    37 <code class="API">twisted.spread.banana.setPrefixLimit</code>.</p>
     37 <code class="API">twisted.spread.banana.setPrefixLimit</code>.</p>
    3838
    3939  <h2>Perspective Broker Limits</h2>
    4040
  • doc/core/howto/dirdbm.xhtml

     
    4545can transparently persist
    4646them. <code>Shelf</code> works exactly like <code>DirDBM</code>, except that
    4747the values (but not the keys) can be arbitrary picklable objects. However,
    48 notice that mutating an object after it has been stored in the
    49 <code>Shelf</code> has no effect on the Shelf.
     48notice that mutating an object after it has been stored in the  <code>Shelf</code> has no effect on the Shelf.
    5049When mutating objects, it is neccessary to explictly store them back in the <code>Shelf</code>
    5150afterwards:</p>
    5251
  • doc/core/howto/pb-usage.xhtml

     
    1111
    1212<p>The first example to look at is a complete (although somewhat trivial)
    1313application. It uses <code>PBServerFactory()</code> on the server side, and
    14 <code>PBClientFactory()</code> on the client side.</p>
     14 <code>PBClientFactory()</code> on the client side.</p>
    1515
    1616<a href="../examples/pbsimple.py" class="py-listing" skipLines="5"
    1717>pbsimple.py</a>
     
    1919>pbsimpleclient.py</a>
    2020
    2121<p>First we look at the server. This defines an Echoer class (derived from
    22 <code class="API" base="twisted.spread">pb.Root</code>), with a method called
    23 <code>remote_echo()</code>.
    24 <code class="API" base="twisted.spread">pb.Root</code> objects (because of
     22 <code class="API" base="twisted.spread">pb.Root</code>), with a method called
     23 <code>remote_echo()</code>.
     24 <code class="API" base="twisted.spread">pb.Root</code> objects (because of
    2525their inheritance of
    26 <code class="API" base="twisted.spread">pb.Referenceable</code>, described
     26 <code class="API" base="twisted.spread">pb.Referenceable</code>, described
    2727later) can define methods with names of the form <code>remote_*</code>; a
    2828client which obtains a remote reference to that
    29 <code class="API" base="twisted.spread">pb.Root</code> object will be able to
     29 <code class="API" base="twisted.spread">pb.Root</code> object will be able to
    3030invoke those methods.</p>
    3131
    3232<p>The <code class="API" base="twisted.spread">pb.Root</code>-ish object is
    3333given to a <code class="API"
    3434base="twisted.spread">pb.PBServerFactory</code><code>()</code>. This is a
    35 <code class="API" base="twisted.internet.protocol">Factory</code> object like
     35 <code class="API" base="twisted.internet.protocol">Factory</code> object like
    3636any other: the <code class="API"
    3737base="twisted.internet.protocol">Protocol</code> objects it creates for new
    3838connections know how to speak the PB protocol. The object you give to
    39 <code>pb.PBServerFactory()</code> becomes the <q>root object</q>, which
     39 <code>pb.PBServerFactory()</code> becomes the <q>root object</q>, which
    4040simply makes it available for the client to retrieve. The client may only
    4141request references to the objects you want to provide it: this helps you
    4242implement your security model. Because it is so common to export just a
     
    4747the client retrieves it.</p>
    4848
    4949<p>The client side uses
    50 <code class="API" base="twisted.spread">pb.PBClientFactory</code> to make a
     50 <code class="API" base="twisted.spread">pb.PBClientFactory</code> to make a
    5151connection to a given port. This is a two-step process involving opening
    5252a TCP connection to a given host and port and requesting the root object
    5353using <code>.getRootObject()</code>.</p>
     
    6262obtained, this callback is run. The first argument passed to the
    6363callback is a remote reference to the distant root object.  (you can
    6464give other arguments to the callback too, see the other parameters for
    65 <code>.addCallback()</code> and <code>.addCallbacks()</code>).</p>
     65 <code>.addCallback()</code> and <code>.addCallbacks()</code>).</p>
    6666
    6767<p>The callback does:</p>
    6868
     
    7272
    7373<p>which causes the server's <code>.remote_echo()</code> method to be invoked.
    7474(running <code>.callRemote("boom")</code> would cause
    75 <code>.remote_boom()</code> to be run, etc). Again because of the delay
     75 <code>.remote_boom()</code> to be run, etc). Again because of the delay
    7676involved, <code>callRemote()</code> returns a
    77 <code class="API" base="twisted.internet.defer">Deferred</code>. Assuming the
     77 <code class="API" base="twisted.internet.defer">Deferred</code>. Assuming the
    7878remote method was run without causing an exception (including an attempt to
    7979invoke an unknown method), the callback attached to that
    80 <code class="API" base="twisted.internet.defer">Deferred</code> will be
     80 <code class="API" base="twisted.internet.defer">Deferred</code> will be
    8181invoked with any objects that were returned by the remote method call.</p>
    8282
    8383<p>In this example, the server's <code>Echoer</code> object has a method
     
    101101Deferreds turns out to be a very clean way to deal with the whole thing.</p>
    102102
    103103<p>The remote reference object (the one given to
    104 <code>getRootObject()</code>'s success callback) is an instance the <code
     104 <code>getRootObject()</code>'s success callback) is an instance the <code
    105105class="API" base="twisted.spread.pb">RemoteReference</code> class. This means
    106106you can use it to invoke methods on the remote object that it refers to. Only
    107107instances of <code class="API"
    108108base="twisted.spread.pb">RemoteReference</code> are eligible for
    109 <code>.callRemote()</code>. The <code class="API"
     109 <code>.callRemote()</code>. The <code class="API"
    110110base="twisted.spread.pb">RemoteReference</code> object is the one that lives
    111111on the remote side (the client, in this case), not the local side (where the
    112112actual object is defined).</p>
     
    114114<p>In our example, the local object is that <code>Echoer()</code> instance,
    115115which inherits from <code class="API" base="twisted.spread">pb.Root</code>,
    116116which inherits from
    117 <code class="API" base="twisted.spread">pb.Referenceable</code>. It is that
    118 <code>Referenceable</code> class that makes the object eligible to be available
     117 <code class="API" base="twisted.spread">pb.Referenceable</code>. It is that
     118 <code>Referenceable</code> class that makes the object eligible to be available
    119119for remote method calls<span class="footnote">There are a few other classes
    120120that can bestow this ability, but pb.Referenceable is the easiest to
    121121understand; see 'flavors' below for details on the others.</span>. If you have
     
    129129<code>remote_*</code> methods can do.</p>
    130130
    131131<p>Also note: the other classes like
    132 <code class="API" base="twisted.spread.pb">Referenceable</code> allow access to
     132 <code class="API" base="twisted.spread.pb">Referenceable</code> allow access to
    133133other methods, in particular <code>perspective_*</code> and <code>view_*</code>
    134134may be accessed.  Don't write local-only methods with these names, because then
    135135remote callers will be able to do more than you intended.</p>
    136136
    137137<p>Also also note: the other classes like
    138 <code class="API" base="twisted.spread">pb.Copyable</code> <em>do</em> allow
     138 <code class="API" base="twisted.spread">pb.Copyable</code> <em>do</em> allow
    139139access to attributes, but you control which ones they can see.</p>
    140140</div>
    141141
    142142<p>You don't have to be a
    143 <code class="API" base="twisted.spread">pb.Root</code> to be remotely callable,
     143 <code class="API" base="twisted.spread">pb.Root</code> to be remotely callable,
    144144but you do have to be
    145 <code class="API" base="twisted.spread">pb.Referenceable</code>.  (Objects that
     145 <code class="API" base="twisted.spread">pb.Referenceable</code>.  (Objects that
    146146inherit from <code class="API" base="twisted.spread">pb.Referenceable</code>
    147147but not from <code class="API" base="twisted.spread">pb.Root</code> can be
    148148remotely called, but only
    149 <code class="API" base="twisted.spread">pb.Root</code>-ish objects can be given
     149 <code class="API" base="twisted.spread">pb.Root</code>-ish objects can be given
    150150to the <code class="API" base="twisted.spread.pb">PBServerFactory</code>.)</p>
    151151
    152152<h2>Complete Example</h2>
     
    167167It returns a <code class="API"
    168168base="twisted.internet.defer">Deferred</code>, which will have its
    169169callback called when the reactor connects to the remote server and
    170 <code class="API" base="twisted.spread">pb.PBClientFactory</code> gets the
     170 <code class="API" base="twisted.spread">pb.PBClientFactory</code> gets the
    171171root, and have its <code class="python">errback</code> called when the
    172172object-connection fails for any reason, whether it was host lookup
    173173failure, connection refusal, or some server-side error.
     
    199199inherit from <code class="API" base="twisted.spread.pb">Referenceable</code>
    200200(or one of the other flavors). If you try to pass a non-Referenceable object
    201201(say, by returning one from a <code>remote_*</code> method), you'll get an
    202 <code class="API" base="twisted.spread.jelly">InsecureJelly</code>
     202 <code class="API" base="twisted.spread.jelly">InsecureJelly</code>
    203203exception<span class="footnote">This can be overridden, by subclassing one of
    204204the Serializable flavors and defining custom serialization code for your
    205205class. See <a href="pb-copyable.xhtml">Passing Complex Types</a> for
     
    214214reference identifiers and turns them into actual objects. You need to stay
    215215aware of where the object lives: if it is on your side, you do actual method
    216216calls. If it is on the other side, you do
    217 <code>.callRemote()</code><span class="footnote">The binary nature of this
     217 <code>.callRemote()</code><span class="footnote">The binary nature of this
    218218local vs. remote scheme works because you cannot give RemoteReferences to a
    219219third party. If you could, then your object A could go to B, B could give it to
    220220C, C might give it back to you, and you would be hard pressed to tell if the
     
    281281subclass by deriving it from <code class="API"
    282282base="twisted.spread">pb.Error</code>. When any remotely-invokable method
    283283(like <code>remote_*</code> or <code>perspective_*</code>) raises a
    284 <code>pb.Error</code>-derived exception, a serialized form of that Exception
     284 <code>pb.Error</code>-derived exception, a serialized form of that Exception
    285285object will be sent back over the wire<span class="footnote">To be precise,
    286286the Failure will be sent if <em>any</em> exception is raised, not just
    287287pb.Error-derived ones. But the server will print ugly error messages if you
     
    303303for remotely-thrown <code>Exception</code> objects. To extract the string that
    304304was put into the exception, use its <code>.getErrorMessage()</code> method.
    305305To get the type of the exception (as a string), look at its
    306 <code>.type</code> attribute. The stack traceback is available too. The
     306 <code>.type</code> attribute. The stack traceback is available too. The
    307307intent is to let the errback function get just as much information about the
    308308exception as Python's normal <code>try:</code> clauses do, even though the
    309309exception occurred in somebody else's memory space at some unknown time in
     
    325325that <em>isn't</em> subclassed from <code>pb.Error</code>? Well, those are
    326326called <q>unexpected exceptions</q>, which make Twisted think that something
    327327has <em>really</em> gone wrong. These will raise an exception on the
    328 <em>server</em> side. This won't break the connection (the exception is
     328 <em>server</em> side. This won't break the connection (the exception is
    329329trapped, just like most exceptions that occur in response to network
    330330traffic), but it will print out an unsightly stack trace on the server's
    331331stderr with a message that says <q>Peer Will Receive PB Traceback</q>, just
     
    344344class="API" base="twisted.internet.defer">Deferred</code>, then a remote
    345345exception will still send a <code>Failure</code> object back over, but it
    346346will get lodged in the <code>Deferred</code> with nowhere to go. When that
    347 <code>Deferred</code> finally goes out of scope, the side that did
    348 <code>callRemote</code> will emit a message about an <q>Unhandled error in
     347 <code>Deferred</code> finally goes out of scope, the side that did
     348 <code>callRemote</code> will emit a message about an <q>Unhandled error in
    349349Deferred</q>, along with an ugly stack trace. It can't raise an exception at
    350350that point (after all, the <code>callRemote</code> that triggered the
    351351problem is long gone), but it will emit a traceback. So be a good programmer
     
    358358<p>To implement the equivalent of the Python try/except blocks (which can
    359359trap particular kinds of exceptions and pass others <q>up</q> to
    360360higher-level <code>try/except</code> blocks), you can use the
    361 <code>.trap()</code> method in conjunction with multiple
    362 <code>errback</code> handlers on the <code>Deferred</code>. Re-raising an
     361 <code>.trap()</code> method in conjunction with multiple
     362 <code>errback</code> handlers on the <code>Deferred</code>. Re-raising an
    363363exception in an <code>errback</code> handler serves to pass that new
    364364exception to the next handler in the chain. The <code>trap</code> method is
    365365given a list of exceptions to look for, and will re-raise anything that
     
    399399SomeClass</code> to match a remote caller who claims to have an object of
    400400type <q>SomeClass</q> could have nasty consequences for some modules that do
    401401significant operations in their <code>__init__</code> methods (think
    402 <code>telnetlib.Telnet(host='localhost', port='chargen')</code>, or even
     402 <code>telnetlib.Telnet(host='localhost', port='chargen')</code>, or even
    403403more powerful classes that you have available in your server program).
    404404Allowing a remote entity to create arbitrary classes in your namespace is
    405405nearly equivalent to allowing them to run arbitrary code.</p>
     
    410410base="twisted.spread">jelly</code>). The easiest way to make it possible to
    411411copy entire class instances over the wire is to have them inherit from <code
    412412class="API" base="twisted.spread">pb.Copyable</code>, and then to use
    413 <code>setUnjellyableForClass(remoteClass, localClass)</code> on the
     413 <code>setUnjellyableForClass(remoteClass, localClass)</code> on the
    414414receiving side. See <a href="pb-copyable.xhtml">Passing Complex Types</a>
    415415for an example.</p></span>.</p>
    416416
     
    420420at the remote end, the exception is returned to the caller asynchronously,
    421421so an <code>errback</code> handler for the associated <code>Deferred</code>
    422422is run. That errback receives a <code>Failure</code> which wraps the
    423 <code>InsecureJelly</code>.</p>
     423 <code>InsecureJelly</code>.</p>
    424424
    425425
    426426<p>Remember that <code>trap</code> re-raises exceptions that it wasn't asked
    427427to look for. You can only check for one set of exceptions per errback
    428428handler: all others must be checked in a subsequent handler.
    429 <code>check_MyException</code> shows how multiple kinds of exceptions can be
     429 <code>check_MyException</code> shows how multiple kinds of exceptions can be
    430430checked in a single errback: give a list of exception types to
    431 <code>trap</code>, and it will return the matching member. In this case, the
     431 <code>trap</code>, and it will return the matching member. In this case, the
    432432kinds of exceptions we are checking for (<code>MyException</code> and
    433 <code>MyOtherException</code>) may be raised by the remote end: they inherit
     433 <code>MyOtherException</code>) may be raised by the remote end: they inherit
    434434from <code class="API" base="twisted.spread">pb.Error</code>.</p>
    435435
    436436<p>The handler can return <code>None</code> to terminate processing of the
     
    438438errback; if there is no callback then processing terminates). It is a good
    439439idea to put an errback that will catch everything (no <code>trap</code>
    440440tests, no possible chance of raising more exceptions, always returns
    441 <code>None</code>) at the end of the chain. Just as with regular <code>try:
     441 <code>None</code>) at the end of the chain. Just as with regular <code>try:
    442442except:</code> handlers, you need to think carefully about ways in which
    443443your errback handlers could themselves raise exceptions. The extra
    444444importance in an asynchronous environment is that an exception that falls
    445445off the end of the <code>Deferred</code> will not be signalled until that
    446 <code>Deferred</code> goes out of scope, and at that point may only cause a
     446 <code>Deferred</code> goes out of scope, and at that point may only cause a
    447447log message (which could even be thrown away if <code class="API"
    448448base="twisted.python">log.startLogging</code> is not used to point it at
    449449stdout or a log file). In contrast, a synchronous exception that is not
  • doc/core/howto/basics.xhtml

     
    1212
    1313<h2>Application</h2>
    1414
    15 <p>Twisted programs usually work with
    16 <code class="API">twisted.application.service.Application</code>.
    17 This class usually holds all persistent configuration of
    18 a running server -- ports to bind to, places where connections
    19 to must be kept or attempted, periodic actions to do and almost
    20 everything else. It is the root object in a tree of services implementing
    21 <code class="API" base="twisted.application.service">IService</code>.</p>
     15<p>Twisted programs usually work
     16with <code class="API">twisted.application.service.Application</code>.
     17This class usually holds all persistent configuration of a running
     18server -- ports to bind to, places where connections to must be kept
     19or attempted, periodic actions to do and almost everything else. It is
     20the root object in a tree of services implementing <code class="API"
     21base="twisted.application.service">IService</code>.</p>
    2222
    2323<p>Other HOWTOs describe how to write custom code for Applications,
    2424but this one describes how to use already written code (which can be
     
    3434
    3535<p>The Twisted Daemon is a program that knows how to run Applications.
    3636This program
    37 is <code class="shell">twistd</code>.  Strictly
     37is <code class="shell">twistd(1)</code>.  Strictly
    3838speaking, <code class="shell">twistd</code> is not necessary --
    3939fetching the application, getting the <code>IService</code> component,
    4040calling <code>startService</code>, scheduling <code>stopService</code> when
    4141the reactor shuts down, and then calling <code>reactor.run()</code> could be
    42 done manually. <code class="shell">twistd</code>, however, supplies
     42done manually. <code class="shell">twistd(1)</code>, however, supplies
    4343many options which are highly useful for program set up.</p>
    4444
    4545<p><code class="shell">twistd</code> supports choosing a reactor (for more on
     
    5252object called <code>application</code> is used, use the <code class="shell">-y</code>
    5353option.</p>
    5454
    55 <p>When <code class="shell">twistd</code> runs, it records its process id in a
    56 <code>twistd.pid</code> file (this can be configured via a command line
    57 switch). In order to shutdown the <code class="shell">twistd</code> process, kill that
    58 pid (usually you would do <code class="shell">kill `cat twistd.pid`</code>).
     55<p>When <code class="shell">twistd</code> runs, it records its process
     56id in a <code>twistd.pid</code> file (this can be configured via a
     57command line switch). In order to shutdown
     58the <code class="shell">twistd</code> process, kill that pid (usually
     59you would do <code class="shell">kill `cat twistd.pid`</code>).
    5960</p>
    6061
    6162<p>As always, the gory details are in the manual page.</p>
     
    6364<h2>OS Integration</h2>
    6465
    6566<p>
    66 If you have an Application that runs with <code class="shell">twistd</code>,
    67 you can easily deploy it on RedHat Linux or Debian GNU/Linux based systems
    68 using the <code class="shell">tap2deb</code> or <code
    69 class="shell">tap2rpm</code> tools. These take a Twisted Application file (of
    70 any of the supported formats — Python source, XML or pickle), and build a
    71 Debian or RPM package (respectively) that installs the Application as a system
    72 service. The package includes the Application file, a default
    73 <code>/etc/init.d/</code> script that starts and stops the process with twistd,
    74 and post-installation scripts that configure the Application to be run in the
    75 appropriate init levels.
     67If you have an Application that runs
     68with <code class="shell">twistd</code>, you can easily deploy it on
     69RedHat Linux or Debian GNU/Linux based systems using
     70the <code class="shell">tap2deb</code>
     71or <code class="shell">tap2rpm</code> tools. These take a Twisted
     72Application file (of any of the supported formats — Python source, XML
     73or pickle), and build a Debian or RPM package (respectively) that
     74installs the Application as a system service. The package includes the
     75Application file, a default <code>/etc/init.d/</code> script that
     76starts and stops the process with twistd, and post-installation
     77scripts that configure the Application to be run in the appropriate
     78init levels.
    7679</p>
    7780
    7881<!-- Is "note" really the right class to be using here? -->
    79 <div class="note">
    80 <code class="shell">tap2rpm</code> and <code class="shell">tap2deb</code> do
    81 not package your entire application and dependent code, just the Twisted
    82 Application file. You will need to find some other way to package your Python
    83 code, such as <code class="API">distutils</code>' <code>bdist_rpm</code>
    84 command.
     82<div class="note"> <code class="shell">tap2rpm</code>
     83and <code class="shell">tap2deb</code> do not package your entire
     84application and dependent code, just the Twisted Application file. You
     85will need to find some other way to package your Python code, such
     86as <code class="API">distutils</code>' <code>bdist_rpm</code> command.
    8587</div>
    8688
    8789<p>
  • doc/core/howto/row.xhtml

     
    187187class="python">loadObjectsFrom</code> is called for a table, it will
    188188automatically load all the children rows for the rows from the specified
    189189table. The child rows will be put into a list member variable of the
    190 rowObject instance with the name <code>childRows</code> or if a
    191 <em>containerMethod</em> is specified for the foreign key relationship,
     190rowObject instance with the name <code>childRows</code> or if a <em>containerMethod</em> is specified for the foreign key relationship,
    192191that method will be called on the parent row object for each row that is
    193192being added to it as a child.</p>
    194193
  • doc/core/howto/design.xhtml

     
    9292<p> The <code class="python">QOTDFactory</code>'s role is to specify to the
    9393Twisted framework how to create a <code class="python">Protocol</code> instance
    9494that will handle the connection.  Twisted will not instantiate a <code
    95 class="python">QOTDFactory</code>; you will do that yourself later, in a
    96 <code class="shell">twistd</code> plug-in.
     95class="python">QOTDFactory</code>; you will do that yourself later, in a <code class="shell">twistd</code> plug-in.
    9796</p>
    9897
    99 <p>Note: you can read more specifics of <code class="python">Protocol</code> and
    100 <code class="python">Factory</code> in the <a href="servers.xhtml">Writing
     98<p>Note: you can read more specifics of <code class="python">Protocol</code> and <code class="python">Factory</code> in the <a href="servers.xhtml">Writing
    10199Servers</a> HOWTO.</p>
    102100
    103101<p>Once we have an abstraction -- a <code>Quoter</code> -- and we have a
    104102mechanism to connect it to the network -- the <code>QOTD</code> protocol -- the
    105103next thing to do is to put the last link in the chain of functionality between
    106 abstraction and user.  This last link will allow a user to choose a
    107 <code>Quoter</code> and configure the protocol. Writing this configuration is
     104abstraction and user.  This last link will allow a user to choose a <code>Quoter</code> and configure the protocol. Writing this configuration is
    108105covered in the <a href="application.xhtml">Application HOWTO</a>.</p>
    109106
    110107</body>
  • doc/core/howto/process.xhtml

     
    2929and added to the reactor core so that the application will not block while
    3030sending data into or pulling data out of the new
    3131process. <code>reactor.spawnProcess</code> requires two arguments,
    32 <code>processProtocol</code> and <code>executable</code>, and optionally takes
     32 <code>processProtocol</code> and <code>executable</code>, and optionally takes
    3333several more: <code>args</code>, <code>environment</code>,
    34 <code>path</code>, <code>userID</code>, <code>groupID</code>,
    35 <code>usePTY</code>, and <code>childFDs</code>. Not all of these are
     34 <code>path</code>, <code>userID</code>, <code>groupID</code>,
     35 <code>usePTY</code>, and <code>childFDs</code>. Not all of these are
    3636available on Windows.</p>
    3737
    3838
     
    8989
    9090<p><code>args</code> and <code>env</code> have empty default values, but
    9191many programs depend upon them to be set correctly. At the very least,
    92 <code>args[0]</code> should probably be the same as <code>executable</code>.
     92 <code>args[0]</code> should probably be the same as <code>executable</code>.
    9393If you just provide <code>os.environ</code> for <code>env</code>, the child
    9494program will inherit the environment from the current process, which is
    9595usually the civilized thing to do (unless you want to explicitly clean the
     
    170170<h2>Things that can happen to your ProcessProtocol</h2>
    171171
    172172<p>These are the methods that you can usefully override in your subclass of
    173 <code>ProcessProtocol</code>:</p>
     173 <code>ProcessProtocol</code>:</p>
    174174
    175175<ul>
    176176
     
    386386three fds, you need addtional methods to access those pipes. These methods
    387387are more generalized than the <code>.outReceived</code> ones described above.
    388388In fact, those methods (<code>outReceived</code> and
    389 <code>errReceived</code>) are actually just wrappers left in for
     389 <code>errReceived</code>) are actually just wrappers left in for
    390390compatibility with older code, written before this generalized fd mapping was
    391391implemented. The new list of things that can happen to your ProcessProtocol
    392392is as follows:</p>
  • doc/core/howto/quotes.xhtml

     
    3838</li>
    3939<li>Add the <code>TwistedQuotes</code> directory's <em>parent</em> to your Python
    4040path. For example, if the TwistedQuotes directory's path is
    41 <code>/tmp/TwistedQuotes</code>
     41 <code>/tmp/TwistedQuotes</code>
    4242add <code>/tmp</code> to your Python path. On UNIX this would be <code
    4343class="shell">export PYTHONPATH=/my/stuff:$PYTHONPATH</code>, on Microsoft
    4444Windows change the <code class="shell">PYTHONPATH</code> variable through the
  • doc/core/howto/upgrading.xhtml

     
    2222<h2>Basic Persistence: Application and .tap files</h2>
    2323
    2424<p>Simple object persistence (using <code>pickle</code> or
    25 <code>jelly</code>) provides the fundamental <q>save the object to disk</q>
     25 <code>jelly</code>) provides the fundamental <q>save the object to disk</q>
    2626functionality at application shutdown. If you use the <code class="API"
    2727base="twisted.application.service">Application</code> object, every object
    2828referenced by your Application will be saved into the
    29 <code>-shutdown.tap</code> file when the program terminates. When you use
    30 <code>twistd</code> to launch that new .tap file, the Application object
     29 <code>-shutdown.tap</code> file when the program terminates. When you use
     30 <code>twistd</code> to launch that new .tap file, the Application object
    3131will be restored along with all of its referenced data.</p>
    3232
    3333<p>This provides a simple way to have data outlive any particular invocation
     
    3535that all Services are referenced by the Application, so their attributes
    3636will be stored as well. Ports that have been bound with listenTCP (and the
    3737like) are also remembered, and the sockets are created at startup time (when
    38 <code>Application.run</code> is called).</p>
     38 <code>Application.run</code> is called).</p>
    3939
    4040<p>To influence the way that the <code class="API"
    4141base="twisted.application.service">Application</code> is persisted, you can adapt
     
    4646saved Application.</p>
    4747
    4848<p>You can manually cause the application to be saved by calling its
    49 <code>.save</code> method (on the <code class="API">twisted.persisted.sob.IPersistable</code>
     49 <code>.save</code> method (on the <code class="API">twisted.persisted.sob.IPersistable</code>
    5050adapted object).</p>
    5151
    5252
     
    7777</p>
    7878
    7979<p>The version number is defined in a class attribute named
    80 <code>persistenceVersion</code>. This is an integer which will be stored in
     80 <code>persistenceVersion</code>. This is an integer which will be stored in
    8181the .tap file along with the rest of the instance state. When the object is
    8282unserialized, the saved persistenceVersion is compared against the current
    8383class's value, and if they differ, special upgrade methods are called. These
     
    138138</pre>
    139139
    140140<p>Note that we must provide both <code>upgradeToVersion1</code>
    141 <em>and</em> <code>upgradeToVersion2</code>. We have to assume that the
     141 <em>and</em> <code>upgradeToVersion2</code>. We have to assume that the
    142142saved .tap files which will be provided to this class come from a random
    143143assortment of old versions: we must be prepared to accept anything ever
    144144saved by a released version of our application.</p>
     
    299299mixed with <code class="API"
    300300base="twisted.persisted.styles">Versioned</code>. <code>rebuild</code> does
    301301not run any of the classes' methods, whereas <code>Versioned</code> works by
    302 running <code>__setstate__</code> during the load process and
    303 <code>doUpgrade</code> afterwards. This means <code>rebuild</code> can only
     302running <code>__setstate__</code> during the load process and  <code>doUpgrade</code> afterwards. This means <code>rebuild</code> can only
    304303be used to process upgrades that do not change the data attributes of any of
    305304the involved classes. Any time attributes are added or removed, the program
    306305must be shut down, persisted, and restarted, with <code>upgradeToVersionNN</code> methods