Ticket #4568: pb.xhtml.patch

doc/core/howto/pb-clients.xhtml

@@ -15 +15 @@
 
 <p>In more complicated cases, for example an <code>Avatar</code> that
 represents a player object which is persistent in the game universe,
-we will want connections from the same player to use the same
-<code>Avatar</code>.</p>
-
-<p>Another thing which is necessary in more complicated scenarios
-is notifying a player asynchronously. While it is possible, of
-course, to allow a player to call
-<code>perspective_remoteListener(referencable)</code> that would
-mean both duplication of code and a higher latency in logging in,
-both bad.</p>
+we will want connections from the same player to use the
+same <code>Avatar</code>.</p>
+
+<p>Another thing which is necessary in more complicated scenarios is
+notifying a player asynchronously. While it is possible, of course, to
+allow a player to
+call <code>perspective_remoteListener(referencable)</code> that would
+mean both duplication of code and a higher latency in logging in, both
+bad.</p>
 
 <p>In previous sections all realms looked to be identical.
 In this one we will show the usefulness of realms in accomplishing

doc/core/howto/pb-copyable.xhtml

@@ -69 +69 @@
 other data structures when executed. Once previously-trusted data is
 subverted, the rest of the program is compromised.</p>
 
-<p>The built-in Python <q>batteries included</q> classes are relatively
-tame, but you still wouldn't want to let a foreign program use them to
-create arbitrary objects in your namespace or on your computer. Imagine a
-protocol that involved sending a file-like object with a <code>read()</code>
-method that was supposed to used later to retrieve a document. Then imagine
-what if that object were created with
-<code>os.fdopen("~/.gnupg/secring.gpg")</code>. Or an instance of
-<code>telnetlib.Telnet("localhost", "chargen")</code>. </p>
-
-<p>Classes you've written for your own program are likely to have far more
-power. They may run code during <code>__init__</code>, or even have special
-meaning simply because of their existence. A program might have
-<code>User</code> objects to represent user accounts, and have a rule that
-says all <code>User</code> objects in the system are referenced when
-authorizing a login session. (In this system, <code>User.__init__</code>
-would probably add the object to a global list of known users). The simple
-act of creating an object would give access to somebody. If you could be
-tricked into creating a bad object, an unauthorized user would get
-access.</p>
+<p>The built-in Python <q>batteries included</q> classes are
+relatively tame, but you still wouldn't want to let a foreign program
+use them to create arbitrary objects in your namespace or on your
+computer. Imagine a protocol that involved sending a file-like object
+with a <code>read()</code> method that was supposed to used later to
+retrieve a document. Then imagine what if that object were created
+with <code>os.fdopen("~/.gnupg/secring.gpg")</code>. Or an instance
+of <code>telnetlib.Telnet("localhost", "chargen")</code>. </p>
+
+<p>Classes you've written for your own program are likely to have far
+more power. They may run code during <code>__init__</code>, or even
+have special meaning simply because of their existence. A program
+might have <code>User</code> objects to represent user accounts, and
+have a rule that says all <code>User</code> objects in the system are
+referenced when authorizing a login session. (In this
+system, <code>User.__init__</code> would probably add the object to a
+global list of known users). The simple act of creating an object
+would give access to somebody. If you could be tricked into creating a
+bad object, an unauthorized user would get access.</p>
 
 <p>So object creation needs to be part of a system's security design. The
 dotted line between <q>trusted inside</q> and <q>untrusted outside</q> needs
@@ -117 +117 @@
 with the <code class="API"
 base="twisted.spread.jelly">setUnjellyableForClass</code> function<!--
 
---><span class="footnote"> <p>Note that, in this context, <q>unjelly</q> is
-a verb with the opposite meaning of <q>jelly</q>. The verb <q>to jelly</q>
-means to serialize an object or data structure into a sequence of bytes (or
-other primitive transmittable/storable representation), while <q>to
-unjelly</q> means to unserialize the bytestream into a live object in the
-receiver's memory space. <q>Unjellyable</q> is a noun, (<em>not</em> an
+--><span class="footnote"> <p>Note that, in this
+context, <q>unjelly</q> is a verb with the opposite meaning
+of <q>jelly</q>. The verb <q>to jelly</q> means to serialize an object
+or data structure into a sequence of bytes (or other primitive
+transmittable/storable representation), while <q>to unjelly</q> means
+to unserialize the bytestream into a live object in the receiver's
+memory space. <q>Unjellyable</q> is a noun, (<em>not</em> an
 adjective), referring to the the class that serves as a destination or
-recipient of the unjellying process. <q>A is unjellyable into B</q> means
-that a serialized representation A (of some remote object) can be
-unserialized into a local object of type B. It is these objects <q>B</q>
-that are the <q>Unjellyable</q> second argument of the
-<code>setUnjellyableForClass</code> function.</p>
+recipient of the unjellying process. <q>A is unjellyable into B</q>
+means that a serialized representation A (of some remote object) can
+be unserialized into a local object of type B. It is these
+objects <q>B</q> that are the <q>Unjellyable</q> second argument of
+the <code>setUnjellyableForClass</code> function.</p>
 
 <p>In particular, <q>unjellyable</q> does <em>not</em> mean <q>cannot be
 jellied</q>. <code class="API"
@@ -139 +140 @@
 
 
 This function takes a remote/sender class reference (either the
-fully-qualified name as used by the sending end, or a class object from
-which the name can be extracted), and a local/recipient class (used to
-create the local representation for incoming serialized objects). Whenever
-the remote end sends an object, the class name that they transmit is looked
-up in the table controlled by this function. If a matching class is found,
-it is used to create the local object. If not, you get the
-<code>InsecureJelly</code> exception.</p>
-
-<p>In general you expect both ends to share the same codebase: either you
-control the program that is running on both ends of the wire, or both
-programs share some kind of common language that is implemented in code
-which exists on both ends. You wouldn't expect them to send you an object of
-the MyFooziWhatZit class unless you also had a definition for that class. So
-it is reasonable for the Jelly layer to reject all incoming classes except
-the ones that you have explicitly marked with
-<code>setUnjellyableForClass</code>. But keep in mind that the sender's idea
-of a <code>User</code> object might differ from the recipient's, either
-through namespace collisions between unrelated packages, version skew
-between nodes that haven't been updated at the same rate, or a malicious
-intruder trying to cause your code to fail in some interesting or
-potentially vulnerable way.</p>
+fully-qualified name as used by the sending end, or a class object
+from which the name can be extracted), and a local/recipient class
+(used to create the local representation for incoming serialized
+objects). Whenever the remote end sends an object, the class name that
+they transmit is looked up in the table controlled by this
+function. If a matching class is found, it is used to create the local
+object. If not, you get the <code>InsecureJelly</code> exception.</p>
+
+<p>In general you expect both ends to share the same codebase: either
+you control the program that is running on both ends of the wire, or
+both programs share some kind of common language that is implemented
+in code which exists on both ends. You wouldn't expect them to send
+you an object of the MyFooziWhatZit class unless you also had a
+definition for that class. So it is reasonable for the Jelly layer to
+reject all incoming classes except the ones that you have explicitly
+marked with <code>setUnjellyableForClass</code>. But keep in mind that
+the sender's idea of a <code>User</code> object might differ from the
+recipient's, either through namespace collisions between unrelated
+packages, version skew between nodes that haven't been updated at the
+same rate, or a malicious intruder trying to cause your code to fail
+in some interesting or potentially vulnerable way.</p>
 
 
 <h2>pb.Copyable</h2>
@@ -170 +171 @@
 <a href="listings/pb/copy_sender.py" class="py-listing">copy_sender.py</a>
 <a href="listings/pb/copy_receiver.tac" class="py-listing">copy_receiver.tac</a>
 
-<p>The sending side has a class called <code>LilyPond</code>. To make this
-eligble for transport through <code>callRemote</code> (either as an
-argument, a return value, or something referenced by either of those [like a
-dictionary value]), it must inherit from one of the four <code class="API"
-base="twisted.spread.pb">Serializable</code> classes. In this section,
-we focus on <code class="API" base="twisted.spread.pb">Copyable</code>.
-The copyable subclass of <code>LilyPond</code> is called
-<code>CopyPond</code>. We create an instance of it and send it through
-<code>callRemote</code> as an argument to the receiver's
-<code>remote_takePond</code> method. The Jelly layer will serialize
-(<q>jelly</q>) that object as an instance with a class name of
+<p>The sending side has a class called <code>LilyPond</code>. To make
+this eligble for transport through <code>callRemote</code> (either as
+an argument, a return value, or something referenced by either of
+those [like a dictionary value]), it must inherit from one of the
+four <code class="API" base="twisted.spread.pb">Serializable</code>
+classes. In this section, we focus on <code class="API"
+base="twisted.spread.pb">Copyable</code>.  The copyable subclass
+of <code>LilyPond</code> is called <code>CopyPond</code>. We create an
+instance of it and send it through <code>callRemote</code> as an
+argument to the receiver's <code>remote_takePond</code> method. The
+Jelly layer will serialize (<q>jelly</q>) that object as an instance
+with a class name of
 <q>copy_sender.CopyPond</q> and some chunk of data that represents the
-object's state. <code>pond.__class__.__module__</code> and
-<code>pond.__class__.__name__</code> are used to derive the class name
-string. The object's <code class="API"
-base="twisted.spread.pb.Copyable">getStateToCopy</code> method is
-used to get the state: this is provided by <code class="API"
-base="twisted.spread">pb.Copyable</code>, and the default just retrieves
-<code>self.__dict__</code>. This works just like the optional
-<code>__getstate__</code> method used by <code>pickle</code>. The pair of
-name and state are sent over the wire to the receiver.</p>
-
-<p>The receiving end defines a local class named <code>ReceiverPond</code>
-to represent incoming <code>LilyPond</code> instances. This class derives
-from the sender's <code>LilyPond</code> class (with a fully-qualified name
-of <code>copy_sender.LilyPond</code>), which specifies how we expect it to
-behave. We trust that this is the same <code>LilyPond</code> class as the
-sender used. (At the very least, we hope ours will be able to accept a state
-created by theirs). It also inherits from <code class="API"
-base="twisted.spread">pb.RemoteCopy</code>, which is a requirement for all
-classes that act in this local-representative role (those which are given to
-the second argument of <code>setUnjellyableForClass</code>).
-<code>RemoteCopy</code> provides the methods that tell the Jelly layer how
-to create the local object from the incoming serialized state.</p>
+object's state. <code>pond.__class__.__module__</code>
+and <code>pond.__class__.__name__</code> are used to derive the class
+name string. The object's <code class="API"
+base="twisted.spread.pb.Copyable">getStateToCopy</code> method is used
+to get the state: this is provided by <code class="API"
+base="twisted.spread">pb.Copyable</code>, and the default just
+retrieves <code>self.__dict__</code>. This works just like the
+optional <code>__getstate__</code> method used
+by <code>pickle</code>. The pair of name and state are sent over the
+wire to the receiver.</p>
+
+<p>The receiving end defines a local class
+named <code>ReceiverPond</code> to represent
+incoming <code>LilyPond</code> instances. This class derives from the
+sender's <code>LilyPond</code> class (with a fully-qualified name
+of <code>copy_sender.LilyPond</code>), which specifies how we expect
+it to behave. We trust that this is the same <code>LilyPond</code>
+class as the sender used. (At the very least, we hope ours will be
+able to accept a state created by theirs). It also inherits
+from <code class="API" base="twisted.spread">pb.RemoteCopy</code>,
+which is a requirement for all classes that act in this
+local-representative role (those which are given to the second
+argument
+of <code>setUnjellyableForClass</code>). <code>RemoteCopy</code>
+provides the methods that tell the Jelly layer how to create the local
+object from the incoming serialized state.</p>
 
 <p>Then <code>setUnjellyableForClass</code> is used to register the two
 classes. This has two effects: instances of the remote class (the first
@@ -211 +217 @@
 the local class (the second argument) will be used to contain the state that
 is transmitted when the sender serializes the remote object.</p>
 
-<p>When the receiver unserializes (<q>unjellies</q>) the object, it will
-create an instance of the local <code>ReceiverPond</code> class, and hand
-the transmitted state (usually in the form of a dictionary) to that object's
-<code class="API"
+<p>When the receiver unserializes (<q>unjellies</q>) the object, it
+will create an instance of the local <code>ReceiverPond</code> class,
+and hand the transmitted state (usually in the form of a dictionary)
+to that object's <code class="API"
 base="twisted.spread.pb.RemoteCopy">setCopyableState</code> method.
-This acts just like the <code>__setstate__</code> method that
-<code>pickle</code> uses when unserializing an object.
-<code>getStateToCopy</code>/<code>setCopyableState</code> are distinct from
-<code>__getstate__</code>/<code>__setstate__</code> to allow objects to be
-persisted (across time) differently than they are transmitted (across
-[memory]space).</p>
+This acts just like the <code>__setstate__</code> method
+that <code>pickle</code> uses when unserializing an
+object. <code>getStateToCopy</code>/<code>setCopyableState</code> are
+distinct from <code>__getstate__</code>/<code>__setstate__</code> to
+allow objects to be persisted (across time) differently than they are
+transmitted (across [memory]space).</p>
 
 <p>When this is run, it produces the following output:</p>
 
@@ -247 +253 @@
 
 <h3>Controlling the Copied State</h3>
 
-<p>By overriding <code>getStateToCopy</code> and
-<code>setCopyableState</code>, you can control how the object is transmitted
-over the wire. For example, you might want perform some data-reduction:
-pre-compute some results instead of sending all the raw data over the wire.
-Or you could replace references to a local object on the sender's side with
-markers before sending, then upon receipt replace those markers with
-references to a receiver-side proxy that could perform the same operations
-against a local cache of data.</p>
+<p>By overriding <code>getStateToCopy</code>
+and <code>setCopyableState</code>, you can control how the object is
+transmitted over the wire. For example, you might want perform some
+data-reduction: pre-compute some results instead of sending all the
+raw data over the wire.  Or you could replace references to a local
+object on the sender's side with markers before sending, then upon
+receipt replace those markers with references to a receiver-side proxy
+that could perform the same operations against a local cache of
+data.</p>
 
 <p>Another good use for <code>getStateToCopy</code> is to implement
-<q>local-only</q> attributes: data that is only accessible by the local
-process, not to any remote users. For example, a <code>.password</code>
-attribute could be removed from the object state before sending to a remote
-system. Combined with the fact that <code>Copyable</code> objects return
-unchanged from a round trip, this could be used to build a
-challenge-response system (in fact PB does this with
-<code>pb.Referenceable</code> objects to implement authorization as
-described <a href="pb-cred.xhtml">here</a>).</p>
+<q>local-only</q> attributes: data that is only accessible by the
+local process, not to any remote users. For example,
+a <code>.password</code> attribute could be removed from the object
+state before sending to a remote system. Combined with the fact
+that <code>Copyable</code> objects return unchanged from a round trip,
+this could be used to build a challenge-response system (in fact PB
+does this with <code>pb.Referenceable</code> objects to implement
+authorization as described <a href="pb-cred.xhtml">here</a>).</p>
 
 <p>Whatever <code>getStateToCopy</code> returns from the sending object will
 be serialized and sent over the wire; <code>setCopyableState</code> gets
@@ -276 +283 @@
 <a href="listings/pb/copy2_sender.py" class="py-listing">copy2_sender.py</a>
 <a href="listings/pb/copy2_receiver.py" class="py-listing">copy2_receiver.py</a>
 
-<p>In this example, the classes are defined in a separate source file, which
-also sets up the binding between them. The <code>SenderPond</code> and
-<code>ReceiverPond</code> are unrelated save for this binding: they happen
-to implement the same methods, but use different internal instance variables
-to accomplish them.</p>
+<p>In this example, the classes are defined in a separate source file,
+which also sets up the binding between
+them. The <code>SenderPond</code> and <code>ReceiverPond</code> are
+unrelated save for this binding: they happen to implement the same
+methods, but use different internal instance variables to accomplish
+them.</p>
 
 <p>The recipient of the object doesn't even have to import the class
 definition into their namespace. It is sufficient that they import the class
@@ -426 +434 @@
 
 --><span class="footnote"> this is actually a <code class="API"
 base="twisted.spread.pb">RemoteCacheObserver</code>, but it isn't very
-useful to subclass or modify, so simply treat it as a little demon that sits
-in your <code>pb.Cacheable</code> class and helps you distribute change
-notifications. The only useful thing to do with it is to run its
-<code>callRemote</code> method, which acts just like a normal
-<code>pb.Referenceable</code>'s method of the same name.</span>
+useful to subclass or modify, so simply treat it as a little demon
+that sits in your <code>pb.Cacheable</code> class and helps you
+distribute change notifications. The only useful thing to do with it
+is to run its <code>callRemote</code> method, which acts just like a
+normal <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
 is changed, you give a message to the observer, informing them of the
 change. The other method, <code>stoppedObserving</code>, is called when the
 remote cache goes away, so that you can stop sending updates.</p>
 
-<p>On the receiver end, you make your cache class inherit from <code
-class="API" base="twisted.spread">pb.RemoteCache</code>, and implement the
-<code>setCopyableState</code> as you would for a <code>pb.RemoteCopy</code>
-object. In addition, you must implement methods to receive the updates sent
-to the observer by the <code>pb.Cacheable</code>: these methods should have
-names that start with <code>observe_</code>, and match the
-<code>callRemote</code> invocations from the sender side just as the usual
-<code>remote_*</code> and <code>perspective_*</code> methods match normal
-<code>callRemote</code> calls. </p>
+<p>On the receiver end, you make your cache class inherit
+from <code class="API" base="twisted.spread">pb.RemoteCache</code>,
+and implement the <code>setCopyableState</code> as you would for
+a <code>pb.RemoteCopy</code> object. In addition, you must implement
+methods to receive the updates sent to the observer by
+the <code>pb.Cacheable</code>: these methods should have names that
+start with <code>observe_</code>, and match
+the <code>callRemote</code> invocations from the sender side just as
+the usual <code>remote_*</code> and <code>perspective_*</code> methods
+match normal <code>callRemote</code> calls. </p>
 
 <p>The first time a reference to the <code>pb.Cacheable</code> object is
 sent to any particular recipient, a sender-side Observer will be created for
@@ -455 +464 @@
 using <code>setCopyableState</code> just like <code>pb.RemoteCopy</code>,
 described above (in fact it inherits from that class). </p>
 
-<p>After that, your <q>setter</q> functions on the sender side should call
-<code>callRemote</code> on the Observer, which causes <code>observe_*</code>
-methods to run on the receiver, which are then supposed to update the
-receiver-local (cached) state.</p>
+<p>After that, your <q>setter</q> functions on the sender side should
+call <code>callRemote</code> on the Observer, which
+causes <code>observe_*</code> methods to run on the receiver, which
+are then supposed to update the receiver-local (cached) state.</p>
 
 <p>When the receiver stops following the cached object and the last
 reference goes away, the <code>pb.RemoteCache</code> object can be freed.
@@ -471 +480 @@
 away.</p>
 
 <p>With the <code>pb.Cacheable</code> and <code>pb.RemoteCache</code>
-classes in place, bound together by a call to
-<code>pb.setUnjellyableForClass</code>, all that remains is to pass a
-reference to your <code>pb.Cacheable</code> over the wire to the remote end.
-The corresponding <code>pb.RemoteCache</code> object will automatically be
-created, and the matching methods will be used to keep the receiver-side
-slave object in sync with the sender-side master object.</p>
+classes in place, bound together by a call
+to <code>pb.setUnjellyableForClass</code>, all that remains is to pass
+a reference to your <code>pb.Cacheable</code> over the wire to the
+remote end.  The corresponding <code>pb.RemoteCache</code> object will
+automatically be created, and the matching methods will be used to
+keep the receiver-side slave object in sync with the sender-side
+master object.</p>
 
 <h3>Example</h3>
 
@@ -571 +581 @@
   in <code class="API">twisted.spread.flavors</code>,
   where <code>pb.Cacheable</code> is implemented.</li>
 
-  <li><code class="API">twisted.manhole.explorer</code> uses
-  <code>Cacheable</code>, and does some fairly interesting things with it.</li>
+  <li><code class="API">twisted.manhole.explorer</code>
+  uses <code>Cacheable</code>, and does some fairly interesting things
+  with it.</li>
 <!--   (XXX: I've heard explorer is currently broken, it might not be a good -->
 <!--   example to recommend)</li> -->
 

doc/core/howto/pb-cred.xhtml

@@ -32 +32 @@
 
 <h2>Compartmentalizing Services</h2>
 
-<p>Imagine how you would write a chat server using PB. The first step might
-be a <code>ChatServer</code> object which had a bunch of
-<code>pb.RemoteReference</code>s that point at user clients. Pretend that
-those clients offered a <code>remote_print</code> method which lets the
-server print a message on the user's console. In that case, the server might
-look something like this:</p>
+<p>Imagine how you would write a chat server using PB. The first step
+might be a <code>ChatServer</code> object which had a bunch
+of <code>pb.RemoteReference</code>s that point at user
+clients. Pretend that those clients offered
+a <code>remote_print</code> method which lets the server print a
+message on the user's console. In that case, the server might look
+something like this:</p>
 
 <pre class="python">
 class ChatServer(pb.Referenceable):
@@ -59 +60 @@
                                                          message))
 </pre>
 
-<p>For now, assume that all clients have somehow acquired a
-<code>pb.RemoteReference</code> to this <code>ChatServer</code> object,
-perhaps using <code>pb.Root</code> and <code>getRootObject</code> as
-described in the <a href="pb-usage.xhtml">previous chapter</a>. In this
-scheme, when a user sends a message to the group, their client runs
-something like the following:</p>
+<p>For now, assume that all clients have somehow acquired
+a <code>pb.RemoteReference</code> to this <code>ChatServer</code>
+object, perhaps using <code>pb.Root</code>
+and <code>getRootObject</code> as described in
+the <a href="pb-usage.xhtml">previous chapter</a>. In this scheme,
+when a user sends a message to the group, their client runs something
+like the following:</p>
 
 <pre class="python">
 remotegroup.callRemote("sendMessage", "alice", "Hi, my name is alice.")
@@ -94 +96 @@
 <p>(In general, learn to get suspicious if you see any argument of a
 remotely-invokable method described as <q>must be X</q>)</p>
 
-<p>The best way to fix this is to keep track of the user's name locally,
-rather than asking them to send it to the server with each message. The best
-place to keep state is in an object, so this suggests we need a per-user
-object. Rather than choosing an obvious name<span class="footnote">the
-obvious name is clearly
-<code>ServerSidePerUserObjectWhichNobodyElseHasAccessTo</code>, but because
-python makes everything else so easy to read, it only seems fair to make
-your audience work for <em>something</em></span>, let's call this the
-<code>User</code> class.
+<p>The best way to fix this is to keep track of the user's name
+locally, rather than asking them to send it to the server with each
+message. The best place to keep state is in an object, so this
+suggests we need a per-user object. Rather than choosing an obvious
+name<span class="footnote">the obvious name is
+clearly <code>ServerSidePerUserObjectWhichNobodyElseHasAccessTo</code>,
+but because python makes everything else so easy to read, it only
+seems fair to make your audience work for <em>something</em></span>,
+let's call this the <code>User</code> class.
 </p>
 
 <pre class="python">
@@ -133 +135 @@
                 user.send("&lt;%s&gt; says: %s" % (from_username, message))
 </pre>
 
-<p>Again, assume that each remote client gets access to a single
-<code>User</code> object, which is created with the proper username.</p>
+<p>Again, assume that each remote client gets access to a
+single <code>User</code> object, which is created with the proper
+username.</p>
 
 <p>Note how the <code>ChatServer</code> object has no remote access: it
 isn't even <code>pb.Referenceable</code> anymore. This means that all access
 to it must be mediated through other objects, with code that is under your
 control.</p>
 
-<p>As long as Alice only has access to her own <code>User</code> object, she
-can no longer spoof Bob. The only way for her to invoke
-<code>ChatServer.sendMessage</code> is to call her <code>User</code>
-object's <code>remote_sendMessage</code> method, and that method uses its
-own state to provide the <code>from_username</code> argument. It doesn't
-give her any way to change that state.</p>
-
-<p>This restriction is important. The <code>User</code> object is able to
-maintain its own integrity because there is a wall between the object and
-the client: the client cannot inspect or modify internal state, like the
-<code>.name</code> attribute. The only way through this wall is via remote
-method invocations, and the only control Alice has over those invocations is
-when they get invoked and what arguments they are given.</p>
+<p>As long as Alice only has access to her own <code>User</code>
+object, she can no longer spoof Bob. The only way for her to
+invoke <code>ChatServer.sendMessage</code> is to call
+her <code>User</code> object's <code>remote_sendMessage</code> method,
+and that method uses its own state to provide
+the <code>from_username</code> argument. It doesn't give her any way
+to change that state.</p>
+
+<p>This restriction is important. The <code>User</code> object is able
+to maintain its own integrity because there is a wall between the
+object and the client: the client cannot inspect or modify internal
+state, like the <code>.name</code> attribute. The only way through
+this wall is via remote method invocations, and the only control Alice
+has over those invocations is when they get invoked and what arguments
+they are given.</p>
 
 <div class="note">
 <p>No object can maintain its integrity against local threats: by design,
@@ -165 +170 @@
 
 <h3>Unforgeable References</h3>
 
-<p>Now suppose you wanted to implement group parameters, for example a mode
-in which nobody was allowed to talk about mattresses because some users were
-sensitive and calming them down after someone said <q>mattress</q> is a
-hassle that were best avoided altogether. Again, per-group state implies a
-per-group object. We'll go out on a limb and call this the
-<code>Group</code> object:</p>
+<p>Now suppose you wanted to implement group parameters, for example a
+mode in which nobody was allowed to talk about mattresses because some
+users were sensitive and calming them down after someone
+said <q>mattress</q> is a hassle that were best avoided
+altogether. Again, per-group state implies a per-group object. We'll
+go out on a limb and call this the <code>Group</code> object:</p>
 
 <pre class="python">
 class User(pb.Referenceable):
@@ -207 +212 @@
 </pre>
 
 
-<p>This example takes advantage of the fact that
-<code>pb.Referenceable</code> objects sent over a wire can be returned to
-you, and they will be turned into references to the same object that you
-originally sent. The client cannot modify the object in any way: all they
-can do is point at it and invoke its <code>remote_*</code> methods. Thus,
-you can be sure that the <code>.name</code> attribute remains the same as
-you left it. In this case, the client code would look something like
-this:</p>
+<p>This example takes advantage of the fact
+that <code>pb.Referenceable</code> objects sent over a wire can be
+returned to you, and they will be turned into references to the same
+object that you originally sent. The client cannot modify the object
+in any way: all they can do is point at it and invoke
+its <code>remote_*</code> methods. Thus, you can be sure that
+the <code>.name</code> attribute remains the same as you left it. In
+this case, the client code would look something like this:</p>
 
 <pre class="python">
 class ClientThing(pb.Referenceable):
@@ -228 +233 @@
         group.callRemote("send", self.remoteUser, "hi everybody")
 </pre>
 
-<p>The <code>User</code> object is sent from the server side, and is turned
-into a <code>pb.RemoteReference</code> when it arrives at the client. The
-client sends it back to <code>Group.remote_send</code>, and PB turns it back
-into a reference to the original <code>User</code> when it gets there.
-<code>Group.remote_send</code> can then use its <code>.name</code> attribute
-as the sender of the message.</p>
+<p>The <code>User</code> object is sent from the server side, and is
+turned into a <code>pb.RemoteReference</code> when it arrives at the
+client. The client sends it back to <code>Group.remote_send</code>,
+and PB turns it back into a reference to the
+original <code>User</code> when it gets
+there. <code>Group.remote_send</code> can then use
+its <code>.name</code> attribute as the sender of the message.</p>
 
 <div class="note">
 
 <p>Third party references (there aren't any)</p>
 
-<p>This technique also relies upon the fact that the
-<code>pb.Referenceable</code> reference can <em>only</em> come from someone
-who holds a corresponding <code>pb.RemoteReference</code>. The design of the
-serialization mechanism (implemented in <code
-class="API">twisted.spread.jelly</code>: pb, jelly, spread.. get it?  Look for
+<p>This technique also relies upon the fact that
+the <code>pb.Referenceable</code> reference can <em>only</em> come
+from someone who holds a
+corresponding <code>pb.RemoteReference</code>. The design of the
+serialization mechanism (implemented
+in <code class="API">twisted.spread.jelly</code>: pb, jelly,
+spread.. get it?  Look for
 <q>banana</q>, too.  What other networking framework
 can claim API names based on sandwich ingredients?) makes it impossible for
 a client to obtain a reference that they weren't explicitly given.
@@ -253 +261 @@
 will give them anything else. The dict goes away when the connection is
 dropped, further limiting the scope of those references.</p>
 
-<p>Futhermore, it is not possible for Bob to send <em>his</em>
-<code>User</code> reference to Alice (perhaps over some other PB channel
-just between the two of them). Outside the context of Bob's connection to
-the server, that reference is just a meaningless number. To prevent
-confusion, PB will tell you if you try to give it away: when you try to hand
-a <code>pb.RemoteReference</code> to a third party, you'll get an exception
-(implemented with an assert in pb.py:364 RemoteReference.jellyFor).</p>
+<p>Futhermore, it is not possible for Bob to
+send <em>his</em> <code>User</code> reference to Alice (perhaps over
+some other PB channel just between the two of them). Outside the
+context of Bob's connection to the server, that reference is just a
+meaningless number. To prevent confusion, PB will tell you if you try
+to give it away: when you try to hand
+a <code>pb.RemoteReference</code> to a third party, you'll get an
+exception (implemented with an assert in pb.py:364
+RemoteReference.jellyFor).</p>
 
 <p>This helps the security model somewhat: only the client you gave the
 reference to can cause any damage with it. Of course, the client might be a
@@ -286 +296 @@
 </div>
 
 
-<p>But again, note the vulnerability. If Alice holds a
-<code>RemoteReference</code> to <em>any</em> object on the server side that
-has a <code>.name</code> attribute, she can use that name as a spoofed
+<p>But again, note the vulnerability. If Alice holds
+a <code>RemoteReference</code> to <em>any</em> object on the server
+side that has a <code>.name</code> attribute, she can use that name as
+a spoofed
 <q>from</q> parameter. As a simple example, what if her client code looked
 like:</p>
 
@@ -312 +323 @@
 
 <h3>Argument Typechecking</h3>
 
-<p>There are two techniques to close this hole. The first is to have your
-remotely-invokable methods do type-checking on their arguments: if
-<code>Group.remote_send</code> asserted <code>isinstance(from_user,
-User)</code> then Alice couldn't use non-User objects to do her spoofing,
-and hopefully the rest of the system is designed well enough to prevent her
-from obtaining access to somebody else's User object.</p>
+<p>There are two techniques to close this hole. The first is to have
+your remotely-invokable methods do type-checking on their arguments:
+if <code>Group.remote_send</code> asserted <code>isinstance(from_user,
+User)</code> then Alice couldn't use non-User objects to do her
+spoofing, and hopefully the rest of the system is designed well enough
+to prevent her from obtaining access to somebody else's User
+object.</p>
 
 
 <h3>Objects as Capabilities</h3>
 
-<p>The second technique is to avoid having the client send you the objects
-altogether. If they don't send you anything, there is nothing to verify. In
-this case, you would have to have a per-user-per-group object, in which the
-<code>remote_send</code> method would only take a single
-<code>message</code> argument. The <code>UserGroup</code> object is created
-with references to the only <code>User</code> and <code>Group</code> objects
-that it will ever use, so no lookups are needed:</p>
+<p>The second technique is to avoid having the client send you the
+objects altogether. If they don't send you anything, there is nothing
+to verify. In this case, you would have to have a per-user-per-group
+object, in which the <code>remote_send</code> method would only take a
+single <code>message</code> argument. The <code>UserGroup</code>
+object is created with references to the only <code>User</code>
+and <code>Group</code> objects that it will ever use, so no lookups
+are needed:</p>
 
 <pre class="python">
 class UserGroup(pb.Referenceable):
@@ -352 +365 @@
         self.users.append(user)
 </pre>
 
-<p>The only message-sending method Alice has left is
-<code>UserGroup.remote_send</code>, and it only accepts a message: there are
-no remaining ways to influence the <q>from</q> name.</p>
+<p>The only message-sending method Alice has left
+is <code>UserGroup.remote_send</code>, and it only accepts a message:
+there are no remaining ways to influence the <q>from</q> name.</p>
 
 <p>In this model, each remotely-accessible object represents a very small
 set of capabilities. Security is achieved by only granting a minimal set of
 abilities to each remote user.</p>
 
-<p>PB provides a shortcut which makes this technique easier to use. The
-<code>Viewable</code> class will be discussed <a
-href="#viewable">below</a>.</p>
+<p>PB provides a shortcut which makes this technique easier to
+use. The <code>Viewable</code> class will be
+discussed <a href="#viewable">below</a>.</p>
 
 <h2>Avatars and Perspectives</h2>
 
@@ -380 +393 @@
 <q>what serves as the Avatar?</q>, and <q>how does the user get access to
 it?</q>.</p>
 
-<p>For PB, the first question is easy. The Avatar is a remotely-accessible
-object which can run code: this is a perfect description of
-<code>pb.Referenceable</code> and its subclasses. We shall defer the second
-question until the next section.</p>
+<p>For PB, the first question is easy. The Avatar is a
+remotely-accessible object which can run code: this is a perfect
+description of <code>pb.Referenceable</code> and its subclasses. We
+shall defer the second question until the next section.</p>
 
-<p>In the example above, you can think of the <code>ChatServer</code> and
-<code>Group</code> objects as a service. The <code>User</code> object is the
-user's server-side representative: everything the user is capable of doing
-is done by running one of its methods. Anything that the server wants to do
-to the user (change their group membership, change their name, delete their
-pet cat, whatever) is done by manipulating the <code>User</code> object.</p>
+<p>In the example above, you can think of the <code>ChatServer</code>
+and <code>Group</code> objects as a service. The <code>User</code>
+object is the user's server-side representative: everything the user
+is capable of doing is done by running one of its methods. Anything
+that the server wants to do to the user (change their group
+membership, change their name, delete their pet cat, whatever) is done
+by manipulating the <code>User</code> object.</p>
 
 <p>There are multiple User objects living in peace and harmony around the
 ChatServer. Each has a different point of view on the services provided by
@@ -400 +414 @@
 origin of the term <q>Perspective</q> in <q>Perspective Broker</q>: PB
 provides and controls (i.e. <q>brokers</q>) access to Perspectives.</p>
 
-<p>Once upon a time, these local-representative objects were actually called
-<code>pb.Perspective</code>. But this has changed with the advent of the
-rewritten cred system, and now the more generic term for a local
-representative object is an Avatar. But you will still see reference to
+<p>Once upon a time, these local-representative objects were actually
+called <code>pb.Perspective</code>. But this has changed with the
+advent of the rewritten cred system, and now the more generic term for
+a local representative object is an Avatar. But you will still see
+reference to
 <q>Perspective</q> in the code, the docs, and the module names<span
 class="footnote">We could just go ahead and rename Perspective Broker to be
 Avatar Broker, but 1) that would cause massive compatibility problems, and 2)
@@ -414 +429 @@
 the whole food-pun thing would start all over again.</span>. Just remember
 that perspectives and avatars are basically the same thing. </p>
 
-<p>Despite all we've been <a href="cred.xhtml">telling you</a> about how
-Avatars are more of a concept than an actual class, the base class from
-which you can create your server-side avatar-ish objects is, in fact, named
-<code>pb.Avatar</code><span class="footnote">The avatar-ish class is named
-<code>pb.Avatar</code> because <code>pb.Perspective</code> was already
-taken, by the (now obsolete) oldcred perspective-ish class. It is a pity,
-but it simply wasn't possible both replace <code>pb.Perspective</code>
+<p>Despite all we've been <a href="cred.xhtml">telling you</a> about
+how Avatars are more of a concept than an actual class, the base class
+from which you can create your server-side avatar-ish objects is, in
+fact, named <code>pb.Avatar</code><span class="footnote">The
+avatar-ish class is named <code>pb.Avatar</code>
+because <code>pb.Perspective</code> was already taken, by the (now
+obsolete) oldcred perspective-ish class. It is a pity, but it simply
+wasn't possible both replace <code>pb.Perspective</code>
 in-place <em>and</em> maintain a reasonable level of
-backwards-compatibility.</span>. These objects behave very much like
-<code>pb.Referenceable</code>. The only difference is that instead of
-offering <q>remote_FOO</q> methods, they offer <q>perspective_FOO</q>
-methods.</p>
-
-<p>The other way in which <code>pb.Avatar</code> differs from
-<code>pb.Referenceable</code> is that the avatar objects are designed to be
-the first thing retrieved by a cred-using remote client. Just as
-<code>PBClientFactory.getRootObject</code> gives the client access to a
-<code>pb.Root</code> object (which can then provide access to all kinds of
-other objects), <code>PBClientFactory.login</code> gives client access to a
-<code>pb.Avatar</code> object (which can return other references). </p>
+backwards-compatibility.</span>. These objects behave very much
+like <code>pb.Referenceable</code>. The only difference is that
+instead of offering <q>remote_FOO</q> methods, they
+offer <q>perspective_FOO</q> methods.</p>
+
+<p>The other way in which <code>pb.Avatar</code> differs
+from <code>pb.Referenceable</code> is that the avatar objects are
+designed to be the first thing retrieved by a cred-using remote
+client. Just as <code>PBClientFactory.getRootObject</code> gives the
+client access to a <code>pb.Root</code> object (which can then provide
+access to all kinds of other
+objects), <code>PBClientFactory.login</code> gives client access to
+a <code>pb.Avatar</code> object (which can return other
+references). </p>
 
 <p>So, the first half of using cred in your PB application is to create an
 Avatar object which implements <code>perspective_</code> methods and is
@@ -488 +506 @@
 <div class="note">
 
 <p>When the client runs <code>login</code> to request the Perspective,
-they can provide it with an optional <code>client</code> argument (which
-must be a <code>pb.Referenceable</code> object). If they do, then a
-reference to that object will be handed to the realm's
-<code>requestAvatar</code> in the <code>mind</code> argument.</p>
+they can provide it with an optional <code>client</code> argument
+(which must be a <code>pb.Referenceable</code> object). If they do,
+then a reference to that object will be handed to the
+realm's <code>requestAvatar</code> in the <code>mind</code>
+argument.</p>
 
 <p>The server-side Perspective can use it to invoke remote methods on
 something in the client, so that the client doesn't always have to drive the
@@ -522 +541 @@
 our server-side Avatar. It implements a <code>perspective_foo</code> method
 that is exposed to the remote client.</p>
 
-<p>Second, we created a realm (an object which implements
-<code>IRealm</code>, and therefore implements <code>requestAvatar</code>).
-This realm manufactures <code>MyPerspective</code> objects. It makes as many
-as we want, and names each one with the avatarID (a username) that comes out
-of the checkers. This MyRealm object returns two other objects as well,
-which we will describe later.</p>
+<p>Second, we created a realm (an object which
+implements <code>IRealm</code>, and therefore
+implements <code>requestAvatar</code>).  This realm
+manufactures <code>MyPerspective</code> objects. It makes as many as
+we want, and names each one with the avatarID (a username) that comes
+out of the checkers. This MyRealm object returns two other objects as
+well, which we will describe later.</p>
 
 <p>Third, we created a portal to hold this realm. The portal's job is to
 dispatch incoming clients to the credential checkers, and then to request
 Avatars for any which survive the authentication process.</p>
 
-<p>Fourth, we made a simple checker (an object which implements
-<code>IChecker</code>) to hold valid user/password pairs. The checker
-gets registered with the portal, so it knows who to ask when new
-clients connect.  We use a checker named
-<code>InMemoryUsernamePasswordDatabaseDontUse</code>, which suggests
-that 1: all the username/password pairs are kept in memory instead of
-being saved to a database or something, and 2: you shouldn't use
-it. The admonition against using it is because there are better
-schemes: keeping everything in memory will not work when you have
-thousands or millions of users to keep track of, the passwords will be
-stored in the .tap file when the application shuts down (possibly a
-security risk), and finally it is a nuisance to add or remove users
-after the checker is constructed.</p>
+<p>Fourth, we made a simple checker (an object which
+implements <code>IChecker</code>) to hold valid user/password
+pairs. The checker gets registered with the portal, so it knows who to
+ask when new clients connect.  We use a checker
+named <code>InMemoryUsernamePasswordDatabaseDontUse</code>, which
+suggests that 1: all the username/password pairs are kept in memory
+instead of being saved to a database or something, and 2: you
+shouldn't use it. The admonition against using it is because there are
+better schemes: keeping everything in memory will not work when you
+have thousands or millions of users to keep track of, the passwords
+will be stored in the .tap file when the application shuts down
+(possibly a security risk), and finally it is a nuisance to add or
+remove users after the checker is constructed.</p>
 
 <p>Fifth, we create a <code>pb.PBServerFactory</code> to listen on a TCP
 port. This factory knows how to connect the remote client to the Portal, so
@@ -554 +574 @@
 Protocol objects will give those objects access to the Portal so
 authentication can take place.</p>
 
-<p>On the client side, a <code>pb.PBClientFactory</code> is created (as <a
-href="pb-usage.xhtml">before</a>) and attached to a TCP connection. When the
-connection completes, the factory will be asked to produce a Protocol, and
-it will create a PB object. Unlike the previous chapter, where we used
-<code>.getRootObject</code>, here we use <code>factory.login</code> to
-initiate the cred authentication process. We provide a
-<code>credentials</code> object, which is the client-side agent for doing
-our half of the authentication process. This process may involve several
-messages: challenges, responses, encrypted passwords, secure hashes, etc. We
-give our credentials object everything it will need to respond correctly (in
-this case, a username and password, but you could write a credential that
-used public-key encryption or even fancier techniques).</p>
-
-<p><code>login</code> returns a Deferred which, when it fires, will return a
-<code>pb.RemoteReference</code> to the remote avatar. We can then do
-<code>callRemote</code> to invoke a <code>perspective_foo</code> method on
+<p>On the client side, a <code>pb.PBClientFactory</code> is created
+(as <a href="pb-usage.xhtml">before</a>) and attached to a TCP
+connection. When the connection completes, the factory will be asked
+to produce a Protocol, and it will create a PB object. Unlike the
+previous chapter, where we used <code>.getRootObject</code>, here we
+use <code>factory.login</code> to initiate the cred authentication
+process. We provide a <code>credentials</code> object, which is the
+client-side agent for doing our half of the authentication
+process. This process may involve several messages: challenges,
+responses, encrypted passwords, secure hashes, etc. We give our
+credentials object everything it will need to respond correctly (in
+this case, a username and password, but you could write a credential
+that used public-key encryption or even fancier techniques).</p>
+
+<p><code>login</code> returns a Deferred which, when it fires, will
+return a <code>pb.RemoteReference</code> to the remote avatar. We can
+then do <code>callRemote</code> to invoke a <code>perspective_foo</code> method on
 that Avatar.</p>
 
 
@@ -578 +599 @@
 <a href="listings/pb/pbAnonServer.py" class="py-listing">pbAnonServer.py</a>
 <a href="listings/pb/pbAnonClient.py" class="py-listing">pbAnonClient.py</a>
 
-<p>pbAnonServer.py implements a server based on pb6server.py, extending it to
-permit anonymous logins in addition to authenticated logins. A
-<code class="API" base="twisted.cred.checkers">AllowAnonymousAccess</code>
-checker and a <code class="API" base="twisted.cred.checkers">
-InMemoryUsernamePasswordDatabaseDontUse</code> checker are registered and the
-client's choice of credentials object determines which is used to authenticate
-the login.  In either case, the realm will be called on to create an avatar for
-the login.  <code>AllowAnonymousAccess</code> always produces an <code>avatarId
-</code> of <code class="API" base="twisted.cred.checkers">ANONYMOUS</code>.</p>
-
-<p>On the client side, the only change is the use of an instance of
-<code class="API" base="twisted.cred.credentials">Anonymous</code> when calling
-<code class="API" base="twisted.spread.pb">PBClientFactory.login</code>.</p>
+<p>pbAnonServer.py implements a server based on pb6server.py,
+extending it to permit anonymous logins in addition to authenticated
+logins. A <code class="API"
+base="twisted.cred.checkers">AllowAnonymousAccess</code> checker and
+a <code class="API" base="twisted.cred.checkers">
+InMemoryUsernamePasswordDatabaseDontUse</code> checker are registered
+and the client's choice of credentials object determines which is used
+to authenticate the login.  In either case, the realm will be called
+on to create an avatar for the
+login.  <code>AllowAnonymousAccess</code> always produces
+an <code>avatarId</code> of <code class="API"
+base="twisted.cred.checkers">ANONYMOUS</code>.</p>
+
+<p>On the client side, the only change is the use of an instance
+of <code class="API" base="twisted.cred.credentials">Anonymous</code>
+when calling <code class="API"
+base="twisted.spread.pb">PBClientFactory.login</code>.</p>
 
 
 <h2>Using Avatars</h2>
@@ -619 +644 @@
 
 <h3>Making Avatars</h3>
 
-<p>In the example above, we create Avatars upon request, during
-<code>requestAvatar</code>. Depending upon the service, these Avatars might
-already exist before the connection is received, and might outlive the
-connection. The Avatars might also accept multiple connections.</p>
+<p>In the example above, we create Avatars upon request,
+during <code>requestAvatar</code>. Depending upon the service, these
+Avatars might already exist before the connection is received, and
+might outlive the connection. The Avatars might also accept multiple
+connections.</p>
 
 <p>Another possibility is that the Avatars might exist ahead of time, but in
 a different form (frozen in a pickle and/or saved in a database). In this
@@ -631 +657 @@
 case, it would probably return a Deferred so it could provide the real
 Avatar later, once the lookup had completed.</p>
 
-<p>Here are some possible implementations of
-<code>MyRealm.requestAvatar</code>:</p>
+<p>Here are some possible implementations
+of <code>MyRealm.requestAvatar</code>:</p>
 
 <pre class="python">
     # pre-existing, static avatars
@@ -690 +716 @@
 them (through the <q>mind</q> argument which lets the Avatar do callRemote
 on the client).</p>
 
-<p>One common idiom which accomplishes this is to have the Realm tell the
-avatar that a remote client has just attached. The Realm can also ask the
-protocol to let it know when the connection goes away, so it can then inform
-the Avatar that the client has detached. The third member of the
-<code>requestAvatar</code> return tuple is a callable which will be invoked
-when the connection is lost.</p>
+<p>One common idiom which accomplishes this is to have the Realm tell
+the avatar that a remote client has just attached. The Realm can also
+ask the protocol to let it know when the connection goes away, so it
+can then inform the Avatar that the client has detached. The third
+member of the <code>requestAvatar</code> return tuple is a callable
+which will be invoked when the connection is lost.</p>
 
 <pre class="python">
 class MyPerspective(pb.Avatar):
@@ -722 +748 @@
 
 <h3>Viewable</h3> <a name="viewable" />
 
-<p>Once you have <code>IPerspective</code> objects (i.e. the Avatar) to
-represent users, the <code class="API"
-base="twisted.spread.flavors">Viewable</code> class can come into play. This
-class behaves a lot like <code>Referenceable</code>: it turns into a
-<code>RemoteReference</code> when sent over the wire, and certain methods
-can be invoked by the holder of that reference. However, the methods that
-can be called have names that start with <code>view_</code> instead of
-<code>remote_</code>, and those methods are always called with an extra
-<code>perspective</code> argument that points to the Avatar through which
-the reference was sent:</p>
+<p>Once you have <code>IPerspective</code> objects (i.e. the Avatar)
+to represent users, the <code class="API"
+base="twisted.spread.flavors">Viewable</code> class can come into
+play. This class behaves a lot like <code>Referenceable</code>: it
+turns into a <code>RemoteReference</code> when sent over the wire, and
+certain methods can be invoked by the holder of that
+reference. However, the methods that can be called have names that
+start with <code>view_</code> instead of <code>remote_</code>, and
+those methods are always called with an extra <code>perspective</code>
+argument that points to the Avatar through which the reference was
+sent:</p>
 
 <pre class="python">
 class Foo(pb.Viewable):
@@ -745 +772 @@
 gives them a way to do additional permission checks, do per-user accounting,
 etc.</p>
 
-<p>This is the shortcut which makes per-user-per-group capability objects
-much easier to use. Instead of creating such per-(user,group) objects, you
-just have per-group objects which inherit from <code>pb.Viewable</code>, and
-give the user references to them. The local <code>pb.Avatar</code> object
-will automatically show up as the <q>perspective</q> argument in the
-<code>view_*</code> method calls, give you a chance to involve the Avatar in
-the process.</p>
+<p>This is the shortcut which makes per-user-per-group capability
+objects much easier to use. Instead of creating such per-(user,group)
+objects, you just have per-group objects which inherit
+from <code>pb.Viewable</code>, and give the user references to
+them. The local <code>pb.Avatar</code> object will automatically show
+up as the <q>perspective</q> argument in the <code>view_*</code>
+method calls, give you a chance to involve the Avatar in the
+process.</p>
 
 
 <h3>Chat Server with Avatars</h3>
@@ -764 +792 @@
 
 <a href="listings/pb/chatserver.py" class="py-listing">chatserver.py</a>
 
-<p>Notice that the client uses <code>perspective_joinGroup</code> to both
-join a group and retrieve a <code>RemoteReference</code> to the
-<code>Group</code> object. However, the reference they get is actually to a
-special intermediate object called a <code>pb.ViewPoint</code>. When they do
-<code>group.callRemote("send", "message")</code>, their avatar is inserted
-into the argument list that <code>Group.view_send</code> actually sees. This
-lets the group get their username out of the Avatar without giving the
-client an opportunity to spoof someone else.</p>
+<p>Notice that the client uses <code>perspective_joinGroup</code> to
+both join a group and retrieve a <code>RemoteReference</code> to
+the <code>Group</code> object. However, the reference they get is
+actually to a special intermediate object called
+a <code>pb.ViewPoint</code>. When they
+do <code>group.callRemote("send", "message")</code>, their avatar is
+inserted into the argument list that <code>Group.view_send</code>
+actually sees. This lets the group get their username out of the
+Avatar without giving the client an opportunity to spoof someone
+else.</p>
 
 <p>The client side code that joins a group and sends a message would look
 like this:</p>

doc/core/howto/pb-intro.xhtml

@@ -55 +55 @@
 
 <ul>
 
-  <li><em><code class="API" base="twisted.internet.protocol">Factory</code></em>
+  <li><code class="API" base="twisted.internet.protocol">Factory</code>
   : <code>internet/protocol.py</code></li>
 
-  <li><em><code class="API" base="twisted.spread.pb">PBServerFactory</code></em>
+  <li><code class="API" base="twisted.spread.pb">PBServerFactory</code>
   : <code>spread/pb.py</code></li>
 
-  <li><em><code class="API" base="twisted.spread.pb">Broker</code></em>
+  <li><code class="API" base="twisted.spread.pb">Broker</code>
   : <code>spread/pb.py</code></li>
 
 </ul>
@@ -70 +70 @@
 
 <ul>
 
-  <li> <em><code class="API" base="twisted.spread.pb">RemoteReference</code></em>
+  <li><code class="API" base="twisted.spread.pb">RemoteReference</code>
   : <code>spread/pb.py</code> </li>
 
-  <li> <em><code class="API" base="twisted.spread">pb.Root</code></em>
+  <li><code class="API" base="twisted.spread">pb.Root</code>
   : <code>spread/pb.py</code>, actually defined as
   <code>twisted.spread.flavors.Root</code>
   in <code>spread/flavors.py</code> </li>
 
-  <li> <em><code class="API" base="twisted.spread">pb.Referenceable</code></em>
+  <li><code class="API" base="twisted.spread">pb.Referenceable</code>
   : <code>spread/pb.py</code>, actually defined as
   <code>twisted.spread.flavors.Referenceable</code>
   in <code>spread/flavors.py</code> </li>
@@ -89 +89 @@
 about authorization and security:</p>
 
 <ul>
-  <li><em><code class="API" base="twisted.cred.portal">Portal</code></em>
+  <li><code class="API" base="twisted.cred.portal">Portal</code>
   : <code>cred/portal.py</code></li>
 
-  <li><em><code class="API" base="twisted.cred.portal">IRealm</code></em>
+  <li><code class="API" base="twisted.cred.portal">IRealm</code>
   : <code>cred/portal.py</code></li>
   
-  <li><em><code class="API" base="twisted.spread.pb">IPerspective</code></em>
+  <li><code class="API" base="twisted.spread.pb">IPerspective</code>
   : <code>spread/pb.py</code>, which you will usually be interacting
   with via pb.Avatar (a basic implementor of the interface).</li>
 </ul>
@@ -205 +205 @@
 <p>In addition to returning objects that you can call remote methods on, you
 can return structured copies of local objects.</p>
 
-<p>There are 2 basic flavors that allow for copying objects remotely.  Again,
-you can use these by subclassing them.  In order to specify what state you want
-to have copied when these are serialized, you can either use the Python default
-<code class="python">__getstate__</code> or specialized method calls for that
-flavor.</p>
+<p>There are 2 basic flavors that allow for copying objects remotely.
+Again, you can use these by subclassing them.  In order to specify
+what state you want to have copied when these are serialized, you can
+either use the Python default <code class="python">__getstate__</code>
+or specialized method calls for that flavor.</p>
 
 <p>
 <ul>

doc/core/howto/pb-limits.xhtml

@@ -30 +30 @@
 It's possible to raise this limit by changing this value (but take care to
 change it on both sides of the connection).</p>
 
-  <p>Another limit imposed by Twisted's Banana implementation is a limit on
-the size of long integers.  The purpose of this limit is the same as the
-<code>SIZE_LIMIT</code>.  By default, only integers between -2 ** 448 and 2
-** 448 (exclusive) can be transferred.  This limit can be changed using
-<code class="API">twisted.spread.banana.setPrefixLimit</code>.</p>
+  <p>Another limit imposed by Twisted's Banana implementation is a
+limit on the size of long integers.  The purpose of this limit is the
+same as the <code>SIZE_LIMIT</code>.  By default, only integers
+between -2 ** 448 and 2 ** 448 (exclusive) can be transferred.  This
+limit can be changed
+using <code class="API">twisted.spread.banana.setPrefixLimit</code>.</p>
 
   <h2>Perspective Broker Limits</h2>
 

doc/core/howto/pb-usage.xhtml

@@ -9 +9 @@
 
 <h2>Basic Example</h2>
 
-<p>The first example to look at is a complete (although somewhat trivial)
-application. It uses <code>PBServerFactory()</code> on the server side, and
-<code>PBClientFactory()</code> on the client side.</p>
+<p>The first example to look at is a complete (although somewhat
+trivial) application. It uses <code>PBServerFactory()</code> on the
+server side, and <code>PBClientFactory()</code> on the client
+side.</p>
 
 <a href="../examples/pbsimple.py" class="py-listing" skipLines="5"
 >pbsimple.py</a>
 <a href="../examples/pbsimpleclient.py" class="py-listing" skipLines="5"
 >pbsimpleclient.py</a>
 
-<p>First we look at the server. This defines an Echoer class (derived from
-<code class="API" base="twisted.spread">pb.Root</code>), with a method called
-<code>remote_echo()</code>. 
-<code class="API" base="twisted.spread">pb.Root</code> objects (because of
-their inheritance of 
-<code class="API" base="twisted.spread">pb.Referenceable</code>, described
-later) can define methods with names of the form <code>remote_*</code>; a
-client which obtains a remote reference to that 
-<code class="API" base="twisted.spread">pb.Root</code> object will be able to
-invoke those methods.</p>
-
-<p>The <code class="API" base="twisted.spread">pb.Root</code>-ish object is
-given to a <code class="API"
-base="twisted.spread">pb.PBServerFactory</code><code>()</code>. This is a
-<code class="API" base="twisted.internet.protocol">Factory</code> object like
-any other: the <code class="API"
-base="twisted.internet.protocol">Protocol</code> objects it creates for new
-connections know how to speak the PB protocol. The object you give to
-<code>pb.PBServerFactory()</code> becomes the <q>root object</q>, which
-simply makes it available for the client to retrieve. The client may only
-request references to the objects you want to provide it: this helps you
-implement your security model. Because it is so common to export just a
-single object (and because a <code>remote_*</code> method on that one can
-return a reference to any other object you might want to give out), the
+<p>First we look at the server. This defines an Echoer class (derived
+from <code class="API" base="twisted.spread">pb.Root</code>), with a
+method called <code>remote_echo()</code>. <code class="API"
+base="twisted.spread">pb.Root</code> objects (because of their
+inheritance of <code class="API"
+base="twisted.spread">pb.Referenceable</code>, described later) can
+define methods with names of the form <code>remote_*</code>; a client
+which obtains a remote reference to that <code class="API"
+base="twisted.spread">pb.Root</code> object will be able to invoke
+those methods.</p>
+
+<p>The <code class="API" base="twisted.spread">pb.Root</code>-ish
+object is given to a <code class="API"
+base="twisted.spread">pb.PBServerFactory</code><code>()</code>. This
+is a <code class="API" base="twisted.internet.protocol">Factory</code>
+object like any other: the <code class="API"
+base="twisted.internet.protocol">Protocol</code> objects it creates
+for new connections know how to speak the PB protocol. The object you
+give to <code>pb.PBServerFactory()</code> becomes the <q>root
+object</q>, which simply makes it available for the client to
+retrieve. The client may only request references to the objects you
+want to provide it: this helps you implement your security
+model. Because it is so common to export just a single object (and
+because a <code>remote_*</code> method on that one can return a
+reference to any other object you might want to give out), the
 simplest example is one where the <code class="API"
-base="twisted.spread.pb">PBServerFactory</code> is given the root object, and
-the client retrieves it.</p>
+base="twisted.spread.pb">PBServerFactory</code> is given the root
+object, and the client retrieves it.</p>
 
-<p>The client side uses
-<code class="API" base="twisted.spread">pb.PBClientFactory</code> to make a
-connection to a given port. This is a two-step process involving opening
-a TCP connection to a given host and port and requesting the root object
+<p>The client side uses <code class="API"
+base="twisted.spread">pb.PBClientFactory</code> to make a connection
+to a given port. This is a two-step process involving opening a TCP
+connection to a given host and port and requesting the root object
 using <code>.getRootObject()</code>.</p>
 
 <p>Because <code>.getRootObject()</code> has to wait until a network
@@ -61 +63 @@
 connection succeeds and a reference to the remote root object is
 obtained, this callback is run. The first argument passed to the
 callback is a remote reference to the distant root object.  (you can
-give other arguments to the callback too, see the other parameters for
-<code>.addCallback()</code> and <code>.addCallbacks()</code>).</p>
+give other arguments to the callback too, see the other parameters
+for <code>.addCallback()</code> and <code>.addCallbacks()</code>).</p>
 
 <p>The callback does:</p>
 
@@ -70 +72 @@
 object.callRemote("echo", "hello network")
 </pre>
 
-<p>which causes the server's <code>.remote_echo()</code> method to be invoked.
-(running <code>.callRemote("boom")</code> would cause
-<code>.remote_boom()</code> to be run, etc). Again because of the delay
-involved, <code>callRemote()</code> returns a 
-<code class="API" base="twisted.internet.defer">Deferred</code>. Assuming the
-remote method was run without causing an exception (including an attempt to
-invoke an unknown method), the callback attached to that
-<code class="API" base="twisted.internet.defer">Deferred</code> will be
-invoked with any objects that were returned by the remote method call.</p>
+<p>which causes the server's <code>.remote_echo()</code> method to be
+invoked.  (running <code>.callRemote("boom")</code> would
+cause <code>.remote_boom()</code> to be run, etc). Again because of
+the delay involved, <code>callRemote()</code> returns
+a<code class="API"
+base="twisted.internet.defer">Deferred</code>. Assuming the remote
+method was run without causing an exception (including an attempt to
+invoke an unknown method), the callback attached to
+that <code class="API" base="twisted.internet.defer">Deferred</code>
+will be invoked with any objects that were returned by the remote
+method call.</p>
 
 <p>In this example, the server's <code>Echoer</code> object has a method
 invoked, <em>exactly</em> as if some code on the server side had done:</p>
@@ -100 +104 @@
 breaks down when faced with the asynchronous nature of the network. Using
 Deferreds turns out to be a very clean way to deal with the whole thing.</p>
 
-<p>The remote reference object (the one given to
-<code>getRootObject()</code>'s success callback) is an instance the <code
-class="API" base="twisted.spread.pb">RemoteReference</code> class. This means
-you can use it to invoke methods on the remote object that it refers to. Only
-instances of <code class="API"
-base="twisted.spread.pb">RemoteReference</code> are eligible for
-<code>.callRemote()</code>. The <code class="API"
-base="twisted.spread.pb">RemoteReference</code> object is the one that lives
-on the remote side (the client, in this case), not the local side (where the
-actual object is defined).</p>
-
-<p>In our example, the local object is that <code>Echoer()</code> instance,
-which inherits from <code class="API" base="twisted.spread">pb.Root</code>,
-which inherits from 
-<code class="API" base="twisted.spread">pb.Referenceable</code>. It is that
-<code>Referenceable</code> class that makes the object eligible to be available
-for remote method calls<span class="footnote">There are a few other classes
-that can bestow this ability, but pb.Referenceable is the easiest to
-understand; see 'flavors' below for details on the others.</span>. If you have
-an object that is Referenceable, then any client that manages to get a
-reference to it can invoke any <code>remote_*</code> methods they please.</p>
+<p>The remote reference object (the one given
+to <code>getRootObject()</code>'s success callback) is an instance
+the <code class="API" base="twisted.spread.pb">RemoteReference</code>
+class. This means you can use it to invoke methods on the remote
+object that it refers to. Only instances of <code class="API"
+base="twisted.spread.pb">RemoteReference</code> are eligible
+for <code>.callRemote()</code>. The <code class="API"
+base="twisted.spread.pb">RemoteReference</code> object is the one that
+lives on the remote side (the client, in this case), not the local
+side (where the actual object is defined).</p>
+
+<p>In our example, the local object is that <code>Echoer()</code>
+instance, which inherits from <code class="API"
+base="twisted.spread">pb.Root</code>, which inherits
+from <code class="API"
+base="twisted.spread">pb.Referenceable</code>. It is
+that <code>Referenceable</code> class that makes the object eligible
+to be available for remote method calls<span class="footnote">There
+are a few other classes that can bestow this ability, but
+pb.Referenceable is the easiest to understand; see 'flavors' below for
+details on the others.</span>. If you have an object that is
+Referenceable, then any client that manages to get a reference to it
+can invoke any <code>remote_*</code> methods they please.</p>
 
 <div class="note">
-<p>The <em>only</em> thing they can do is invoke those
-methods.  In particular, they cannot access attributes. From a security point
-of view, you control what they can do by limiting what the
-<code>remote_*</code> methods can do.</p>
-
-<p>Also note: the other classes like 
-<code class="API" base="twisted.spread.pb">Referenceable</code> allow access to
-other methods, in particular <code>perspective_*</code> and <code>view_*</code>
-may be accessed.  Don't write local-only methods with these names, because then
-remote callers will be able to do more than you intended.</p>
-
-<p>Also also note: the other classes like 
-<code class="API" base="twisted.spread">pb.Copyable</code> <em>do</em> allow
-access to attributes, but you control which ones they can see.</p>
+<p>The <em>only</em> thing they can do is invoke those methods.  In
+particular, they cannot access attributes. From a security point of
+view, you control what they can do by limiting what
+the <code>remote_*</code> methods can do.</p>
+
+<p>Also note: the other classes like <code class="API"
+base="twisted.spread.pb">Referenceable</code> allow access to other
+methods, in particular <code>perspective_*</code>
+and <code>view_*</code> may be accessed.  Don't write local-only
+methods with these names, because then remote callers will be able to
+do more than you intended.</p>
+
+<p>Also also note: the other classes like <code class="API"
+base="twisted.spread">pb.Copyable</code> <em>do</em> allow access to
+attributes, but you control which ones they can see.</p>
 </div>
 
-<p>You don't have to be a 
-<code class="API" base="twisted.spread">pb.Root</code> to be remotely callable,
-but you do have to be 
-<code class="API" base="twisted.spread">pb.Referenceable</code>.  (Objects that
-inherit from <code class="API" base="twisted.spread">pb.Referenceable</code>
-but not from <code class="API" base="twisted.spread">pb.Root</code> can be
-remotely called, but only 
-<code class="API" base="twisted.spread">pb.Root</code>-ish objects can be given
-to the <code class="API" base="twisted.spread.pb">PBServerFactory</code>.)</p>
+<p>You don't have to be a <code class="API"
+base="twisted.spread">pb.Root</code> to be remotely callable, but you
+do have to be <code class="API"
+base="twisted.spread">pb.Referenceable</code>.  (Objects that inherit
+from <code class="API" base="twisted.spread">pb.Referenceable</code>
+but not from <code class="API" base="twisted.spread">pb.Root</code>
+can be remotely called, but only <code class="API"
+base="twisted.spread">pb.Root</code>-ish objects can be given to
+the <code class="API"
+base="twisted.spread.pb">PBServerFactory</code>.)</p>
 
 <h2>Complete Example</h2>
 
@@ -166 +174 @@
 handle all the details of waiting for the creation of a connection.
 It returns a <code class="API"
 base="twisted.internet.defer">Deferred</code>, which will have its
-callback called when the reactor connects to the remote server and
-<code class="API" base="twisted.spread">pb.PBClientFactory</code> gets the
-root, and have its <code class="python">errback</code> called when the
-object-connection fails for any reason, whether it was host lookup
-failure, connection refusal, or some server-side error.
+callback called when the reactor connects to the remote server
+and <code class="API" base="twisted.spread">pb.PBClientFactory</code>
+gets the root, and have its <code class="python">errback</code> called
+when the object-connection fails for any reason, whether it was host
+lookup failure, connection refusal, or some server-side error.
 </p>
 
 <p>The root object has a method called <code>remote_getTwo</code>, which
@@ -194 +202 @@
 will be made, depending on whether an error occurred in processing the
 method call.</p>
 
-<p>You can use this technique to provide access to arbitrary sets of objects.
-Just remember that any object that might get passed <q>over the wire</q> must
-inherit from <code class="API" base="twisted.spread.pb">Referenceable</code>
-(or one of the other flavors). If you try to pass a non-Referenceable object
-(say, by returning one from a <code>remote_*</code> method), you'll get an
-<code class="API" base="twisted.spread.jelly">InsecureJelly</code>
-exception<span class="footnote">This can be overridden, by subclassing one of
-the Serializable flavors and defining custom serialization code for your
-class. See <a href="pb-copyable.xhtml">Passing Complex Types</a> for
-details.</span>.</p>
+<p>You can use this technique to provide access to arbitrary sets of
+objects.  Just remember that any object that might get passed <q>over
+the wire</q> must inherit from <code class="API"
+base="twisted.spread.pb">Referenceable</code> (or one of the other
+flavors). If you try to pass a non-Referenceable object (say, by
+returning one from a <code>remote_*</code> method), you'll get
+an <code class="API" base="twisted.spread.jelly">InsecureJelly</code>
+exception<span class="footnote">This can be overridden, by subclassing
+one of the Serializable flavors and defining custom serialization code
+for your class. See <a href="pb-copyable.xhtml">Passing Complex
+Types</a> for details.</span>.</p>
 
 
 <h2>References can come back to you</h2>
 
-<p>If your server gives a reference to a client, and then that client gives
-the reference back to the server, the server will wind up with the same
-object it gave out originally. The serialization layer watches for returning
-reference identifiers and turns them into actual objects. You need to stay
-aware of where the object lives: if it is on your side, you do actual method
-calls. If it is on the other side, you do 
-<code>.callRemote()</code><span class="footnote">The binary nature of this
-local vs. remote scheme works because you cannot give RemoteReferences to a
-third party. If you could, then your object A could go to B, B could give it to
-C, C might give it back to you, and you would be hard pressed to tell if the
-object lived in C's memory space, in B's, or if it was really your own object,
-tarnished and sullied after being handed down like a really ugly picture that
-your great aunt owned and which nobody wants but which nobody can bear to throw
-out. Ok, not really like that, but you get the idea.</span>.</p>
+<p>If your server gives a reference to a client, and then that client
+gives the reference back to the server, the server will wind up with
+the same object it gave out originally. The serialization layer
+watches for returning reference identifiers and turns them into actual
+objects. You need to stay aware of where the object lives: if it is on
+your side, you do actual method calls. If it is on the other side, you
+do <code>.callRemote()</code><span class="footnote">The binary nature
+of this local vs. remote scheme works because you cannot give
+RemoteReferences to a third party. If you could, then your object A
+could go to B, B could give it to C, C might give it back to you, and
+you would be hard pressed to tell if the object lived in C's memory
+space, in B's, or if it was really your own object, tarnished and
+sullied after being handed down like a really ugly picture that your
+great aunt owned and which nobody wants but which nobody can bear to
+throw out. Ok, not really like that, but you get the idea.</span>.</p>
 
 <a href="listings/pb/pb2server.py" class="py-listing">pb2server.py</a>
 <a href="listings/pb/pb2client.py" class="py-listing">pb2client.py</a>
@@ -277 +287 @@
 about when they go wrong? The Python Way is to raise an exception of some
 sort. The Twisted Way is the same.</p>
 
-<p>The only special thing you do is to define your <code>Exception</code>
-subclass by deriving it from <code class="API"
-base="twisted.spread">pb.Error</code>. When any remotely-invokable method
-(like <code>remote_*</code> or <code>perspective_*</code>) raises a
-<code>pb.Error</code>-derived exception, a serialized form of that Exception
-object will be sent back over the wire<span class="footnote">To be precise,
-the Failure will be sent if <em>any</em> exception is raised, not just
-pb.Error-derived ones. But the server will print ugly error messages if you
-raise ones that aren't derived from pb.Error.</span>. The other side (which
-did <code>callRemote</code>) will have the <q><code>errback</code></q>
-callback run with a <code class="API"
-base="twisted.python.failure">Failure</code> object that contains a copy of
-the exception object. This <code>Failure</code> object can be queried to
-retrieve the error message and a stack traceback.</p>
+<p>The only special thing you do is to define
+your <code>Exception</code> subclass by deriving it
+from <code class="API" base="twisted.spread">pb.Error</code>. When any
+remotely-invokable method (like <code>remote_*</code>
+or <code>perspective_*</code>) raises a <code>pb.Error</code>-derived
+exception, a serialized form of that Exception object will be sent
+back over the wire<span class="footnote">To be precise, the Failure
+will be sent if <em>any</em> exception is raised, not just
+pb.Error-derived ones. But the server will print ugly error messages
+if you raise ones that aren't derived from pb.Error.</span>. The other
+side (which did <code>callRemote</code>) will have
+the <q><code>errback</code></q> callback run with a <code class="API"
+base="twisted.python.failure">Failure</code> object that contains a
+copy of the exception object. This <code>Failure</code> object can be
+queried to retrieve the error message and a stack traceback.</p>
 
 <p><code class="API" base="twisted.python.failure">Failure</code> is a
 special class, defined in <code>twisted/python/failure.py</code>, created to
@@ -299 +310 @@
 can't handle the particular type of failure, it can be <q>passed along</q> to a
 errback handler further down the chain.</p>
 
-<p>For simple purposes, think of the <code>Failure</code> as just a container
-for remotely-thrown <code>Exception</code> objects. To extract the string that
-was put into the exception, use its <code>.getErrorMessage()</code> method.
-To get the type of the exception (as a string), look at its
-<code>.type</code> attribute. The stack traceback is available too. The
-intent is to let the errback function get just as much information about the
-exception as Python's normal <code>try:</code> clauses do, even though the
-exception occurred in somebody else's memory space at some unknown time in
-the past.</p>
+<p>For simple purposes, think of the <code>Failure</code> as just a
+container for remotely-thrown <code>Exception</code> objects. To
+extract the string that was put into the exception, use
+its <code>.getErrorMessage()</code> method.  To get the type of the
+exception (as a string), look at its <code>.type</code> attribute. The
+stack traceback is available too. The intent is to let the errback
+function get just as much information about the exception as Python's
+normal <code>try:</code> clauses do, even though the exception
+occurred in somebody else's memory space at some unknown time in the
+past.</p>
 
 <a href="listings/pb/exc_server.py" class="py-listing">exc_server.py</a>
 <a href="listings/pb/exc_client.py" class="py-listing">exc_client.py</a>
@@ -321 +333 @@
 Main loop terminated.
 </pre>
 
-<p>Oh, and what happens if you raise some other kind of exception? Something
-that <em>isn't</em> subclassed from <code>pb.Error</code>? Well, those are
-called <q>unexpected exceptions</q>, which make Twisted think that something
-has <em>really</em> gone wrong. These will raise an exception on the
-<em>server</em> side. This won't break the connection (the exception is
-trapped, just like most exceptions that occur in response to network
-traffic), but it will print out an unsightly stack trace on the server's
-stderr with a message that says <q>Peer Will Receive PB Traceback</q>, just
-as if the exception had happened outside a remotely-invokable method. (This
-message will go the current log target, if <code class="API"
-base="twisted.python">log.startLogging</code> was used to redirect it). The
-client will get the same <code>Failure</code> object in either case, but
-subclassing your exception from <code>pb.Error</code> is the way to tell
-Twisted that you expect this sort of exception, and that it is ok to just
-let the client handle it instead of also asking the server to complain. Look
-at <code>exc_client.py</code> and change it to invoke <code>broken2()</code>
-instead of <code>broken()</code> to see the change in the server's
-behavior.</p>
-
-<p>If you don't add an <code>errback</code> function to the <code
-class="API" base="twisted.internet.defer">Deferred</code>, then a remote
-exception will still send a <code>Failure</code> object back over, but it
-will get lodged in the <code>Deferred</code> with nowhere to go. When that
-<code>Deferred</code> finally goes out of scope, the side that did
-<code>callRemote</code> will emit a message about an <q>Unhandled error in
-Deferred</q>, along with an ugly stack trace. It can't raise an exception at
-that point (after all, the <code>callRemote</code> that triggered the
-problem is long gone), but it will emit a traceback. So be a good programmer
-and <em>always add <code>errback</code> handlers</em>, even if they are just
-calls to <code class="API" base="twisted.python">log.err</code>.</p>
+<p>Oh, and what happens if you raise some other kind of exception?
+Something that <em>isn't</em> subclassed from <code>pb.Error</code>?
+Well, those are called <q>unexpected exceptions</q>, which make
+Twisted think that something has <em>really</em> gone wrong. These
+will raise an exception on the <em>server</em> side. This won't break
+the connection (the exception is trapped, just like most exceptions
+that occur in response to network traffic), but it will print out an
+unsightly stack trace on the server's stderr with a message that
+says <q>Peer Will Receive PB Traceback</q>, just as if the exception
+had happened outside a remotely-invokable method. (This message will
+go the current log target, if <code class="API"
+base="twisted.python">log.startLogging</code> was used to redirect
+it). The client will get the same <code>Failure</code> object in
+either case, but subclassing your exception from <code>pb.Error</code>
+is the way to tell Twisted that you expect this sort of exception, and
+that it is ok to just let the client handle it instead of also asking
+the server to complain. Look at <code>exc_client.py</code> and change
+it to invoke <code>broken2()</code> instead of <code>broken()</code>
+to see the change in the server's behavior.</p>
+
+<p>If you don't add an <code>errback</code> function to
+the <code class="API" base="twisted.internet.defer">Deferred</code>,
+then a remote exception will still send a <code>Failure</code> object
+back over, but it will get lodged in the <code>Deferred</code> with
+nowhere to go. When that <code>Deferred</code> finally goes out of
+scope, the side that did <code>callRemote</code> will emit a message
+about an <q>Unhandled error in Deferred</q>, along with an ugly stack
+trace. It can't raise an exception at that point (after all,
+the <code>callRemote</code> that triggered the problem is long gone),
+but it will emit a traceback. So be a good programmer and <em>always
+add </em> <code>errback</code> <em> handlers</em>, even if they are just calls
+to <code class="API" base="twisted.python">log.err</code>.</p>
 
 <h2>Try/Except blocks and <code class="API"
 base="twisted.python.failure">Failure.trap</code> </h2>
 
-<p>To implement the equivalent of the Python try/except blocks (which can
-trap particular kinds of exceptions and pass others <q>up</q> to
-higher-level <code>try/except</code> blocks), you can use the
-<code>.trap()</code> method in conjunction with multiple
-<code>errback</code> handlers on the <code>Deferred</code>. Re-raising an
-exception in an <code>errback</code> handler serves to pass that new
-exception to the next handler in the chain. The <code>trap</code> method is
-given a list of exceptions to look for, and will re-raise anything that
-isn't on the list. Instead of passing unhandled exceptions <q>up</q> to an
+<p>To implement the equivalent of the Python try/except blocks (which
+can trap particular kinds of exceptions and pass others <q>up</q> to
+higher-level <code>try/except</code> blocks), you can use
+the <code>.trap()</code> method in conjunction with
+multiple <code>errback</code> handlers on
+the <code>Deferred</code>. Re-raising an exception in
+an <code>errback</code> handler serves to pass that new exception to
+the next handler in the chain. The <code>trap</code> method is given a
+list of exceptions to look for, and will re-raise anything that isn't
+on the list. Instead of passing unhandled exceptions <q>up</q> to an
 enclosing <code>try</code> block, this has the effect of passing the
-exception <q>off</q> to later <code>errback</code> handlers on the same
-<code>Deferred</code>. The <code>trap</code> calls are used in chained
-errbacks to test for each kind of exception in sequence. </p>
+exception <q>off</q> to later <code>errback</code> handlers on the
+same <code>Deferred</code>. The <code>trap</code> calls are used in
+chained errbacks to test for each kind of exception in sequence. </p>
 
 <a href="listings/pb/trap_server.py" class="py-listing">trap_server.py</a>
 <a href="listings/pb/trap_client.py" class="py-listing">trap_client.py</a>
@@ -396 +411 @@
 know which local class ought to be used to create an instance that
 corresponds to the remote object<!--   eat breaking space
 
---><span class="footnote"><p>The naive approach of simply doing <code>import
-SomeClass</code> to match a remote caller who claims to have an object of
-type <q>SomeClass</q> could have nasty consequences for some modules that do
-significant operations in their <code>__init__</code> methods (think
-<code>telnetlib.Telnet(host='localhost', port='chargen')</code>, or even
-more powerful classes that you have available in your server program).
-Allowing a remote entity to create arbitrary classes in your namespace is
-nearly equivalent to allowing them to run arbitrary code.</p>
+--><span class="footnote"><p>The naive approach of simply
+doing <code>import SomeClass</code> to match a remote caller who
+claims to have an object of type <q>SomeClass</q> could have nasty
+consequences for some modules that do significant operations in
+their <code>__init__</code> methods
+(think <code>telnetlib.Telnet(host='localhost',
+port='chargen')</code>, or even more powerful classes that you have
+available in your server program).  Allowing a remote entity to create
+arbitrary classes in your namespace is nearly equivalent to allowing
+them to run arbitrary code.</p>
 
 <p>The <code class="API" base="twisted.spread">pb.InsecureJelly</code>
-exception arises because the class being sent over the wire has not been
-registered with the serialization layer (known as <code class="API"
-base="twisted.spread">jelly</code>). The easiest way to make it possible to
-copy entire class instances over the wire is to have them inherit from <code
-class="API" base="twisted.spread">pb.Copyable</code>, and then to use
-<code>setUnjellyableForClass(remoteClass, localClass)</code> on the
-receiving side. See <a href="pb-copyable.xhtml">Passing Complex Types</a>
-for an example.</p></span>.
-
-The receiving end of the connection gets to decide what to accept and what
-to reject. It indicates its disapproval by raising a <code class="API"
-base="twisted.spread">pb.InsecureJelly</code> exception. Because it occurs
-at the remote end, the exception is returned to the caller asynchronously,
-so an <code>errback</code> handler for the associated <code>Deferred</code>
-is run. That errback receives a <code>Failure</code> which wraps the
-<code>InsecureJelly</code>.</p>
-
-
-<p>Remember that <code>trap</code> re-raises exceptions that it wasn't asked
-to look for. You can only check for one set of exceptions per errback
-handler: all others must be checked in a subsequent handler.
-<code>check_MyException</code> shows how multiple kinds of exceptions can be
-checked in a single errback: give a list of exception types to
-<code>trap</code>, and it will return the matching member. In this case, the
-kinds of exceptions we are checking for (<code>MyException</code> and
-<code>MyOtherException</code>) may be raised by the remote end: they inherit
-from <code class="API" base="twisted.spread">pb.Error</code>.</p>
-
-<p>The handler can return <code>None</code> to terminate processing of the
-errback chain (to be precise, it switches to the callback that follows the
-errback; if there is no callback then processing terminates). It is a good
-idea to put an errback that will catch everything (no <code>trap</code>
-tests, no possible chance of raising more exceptions, always returns
-<code>None</code>) at the end of the chain. Just as with regular <code>try:
-except:</code> handlers, you need to think carefully about ways in which
-your errback handlers could themselves raise exceptions. The extra
-importance in an asynchronous environment is that an exception that falls
-off the end of the <code>Deferred</code> will not be signalled until that
-<code>Deferred</code> goes out of scope, and at that point may only cause a
-log message (which could even be thrown away if <code class="API"
-base="twisted.python">log.startLogging</code> is not used to point it at
-stdout or a log file). In contrast, a synchronous exception that is not
-handled by any other <code>except:</code> block will very visibly terminate
-the program immediately with a noisy stack trace.</p>
+exception arises because the class being sent over the wire has not
+been registered with the serialization layer (known
+as <code class="API" base="twisted.spread">jelly</code>). The easiest
+way to make it possible to copy entire class instances over the wire
+is to have them inherit from <code class="API"
+base="twisted.spread">pb.Copyable</code>, and then to
+use <code>setUnjellyableForClass(remoteClass, localClass)</code> on
+the receiving side. See <a href="pb-copyable.xhtml">Passing Complex
+Types</a> for an example.</p></span>.
+
+The receiving end of the connection gets to decide what to accept and
+what to reject. It indicates its disapproval by raising
+a <code class="API" base="twisted.spread">pb.InsecureJelly</code>
+exception. Because it occurs at the remote end, the exception is
+returned to the caller asynchronously, so an <code>errback</code>
+handler for the associated <code>Deferred</code> is run. That errback
+receives a <code>Failure</code> which wraps
+the <code>InsecureJelly</code>.</p>
+
+
+<p>Remember that <code>trap</code> re-raises exceptions that it wasn't
+asked to look for. You can only check for one set of exceptions per
+errback handler: all others must be checked in a subsequent
+handler. <code>check_MyException</code> shows how multiple kinds of
+exceptions can be checked in a single errback: give a list of
+exception types to <code>trap</code>, and it will return the matching
+member. In this case, the kinds of exceptions we are checking for
+(<code>MyException</code> and <code>MyOtherException</code>) may be
+raised by the remote end: they inherit from <code class="API"
+base="twisted.spread">pb.Error</code>.</p>
+
+<p>The handler can return <code>None</code> to terminate processing of
+the errback chain (to be precise, it switches to the callback that
+follows the errback; if there is no callback then processing
+terminates). It is a good idea to put an errback that will catch
+everything (no <code>trap</code> tests, no possible chance of raising
+more exceptions, always returns <code>None</code>) at the end of the
+chain. Just as with regular <code>try: except:</code> handlers, you
+need to think carefully about ways in which your errback handlers
+could themselves raise exceptions. The extra importance in an
+asynchronous environment is that an exception that falls off the end
+of the <code>Deferred</code> will not be signalled until
+that <code>Deferred</code> goes out of scope, and at that point may
+only cause a log message (which could even be thrown away
+if <code class="API" base="twisted.python">log.startLogging</code> is
+not used to point it at stdout or a log file). In contrast, a
+synchronous exception that is not handled by any
+other <code>except:</code> block will very visibly terminate the
+program immediately with a noisy stack trace.</p>
 
 <p><code>callFour</code> shows another kind of exception that can occur
 while using <code>callRemote</code>: <code class="API"
@@ -460 +482 @@
 synchronous <code>try: except pb.DeadReferenceError</code> block. </p>
 
 <p>Yet another kind that can occur is a <code class="API"
-base="twisted.spread">pb.PBConnectionLost</code> exception. This occurs
-(asynchronously) if the connection was lost while you were waiting for a
-<code>callRemote</code> call to complete. When the line goes dead, all
-pending requests are terminated with this exception. Note that you have no
-way of knowing whether the request made it to the other end or not, nor how
-far along in processing it they had managed before the connection was
-lost. XXX: explain transaction semantics, find a decent reference.</p>
+base="twisted.spread">pb.PBConnectionLost</code> exception. This
+occurs (asynchronously) if the connection was lost while you were
+waiting for a <code>callRemote</code> call to complete. When the line
+goes dead, all pending requests are terminated with this
+exception. Note that you have no way of knowing whether the request
+made it to the other end or not, nor how far along in processing it
+they had managed before the connection was lost. XXX: explain
+transaction semantics, find a decent reference.</p>
 
 </body> </html>