Ticket #4568: core-howto2.xhtml.patch

File core-howto2.xhtml.patch, 79.8 KB (added by jdb, 4 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/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