Ticket #1272: interfaces_1272.diff

twisted/internet/interfaces.py

@@ -2 +2 @@
 # See LICENSE for details.
 
 
-"""Interface documentation.
+"""
+Interface documentation.
 
 API Stability: stable, other than IReactorUDP (semi-stable) and
 IReactorMulticast (unstable).
@@ -14 +15 @@
 
 
 class IAddress(Interface):
-    """An address, e.g. a TCP (host, port).
+    """
+    An address, e.g. a TCP (host, port).
 
     Default implementations are in L{twisted.internet.address}.
     """
@@ -23 +25 @@
 ### Reactor Interfaces
 
 class IConnector(Interface):
-    """Object used to interface between connections and protocols.
+    """
+    Object used to interface between connections and protocols.
 
     Each IConnector manages one connection.
     """
 
     def stopConnecting():
-        """Stop attempting to connect."""
+        """
+        Stop attempting to connect.
+        """
 
     def disconnect():
-        """Disconnect regardless of the connection state.
+        """
+        Disconnect regardless of the connection state.
 
         If we are connected, disconnect, if we are trying to connect,
         stop trying.
         """
 
     def connect():
-        """Try to connect to remote address."""
+        """
+        Try to connect to remote address.
+        """
 
     def getDestination():
-        """Return destination this will try to connect to.
+        """
+        Return destination this will try to connect to.
 
         @return: An object which provides L{IAddress}.
         """
 
 
 class IResolverSimple(Interface):
+
     def getHostByName(name, timeout = (1, 3, 11, 45)):
-        """Resolve the domain name C{name} into an IP address.
+        """
+        Resolve the domain name C{name} into an IP address.
 
         @type name: C{str}
         @type timeout: C{tuple}
@@ -68 +79 @@
         """
 
 class IResolver(IResolverSimple):
+
     def lookupRecord(name, cls, type, timeout = 10):
-        """Lookup the records associated with the given name
-           that are of the given type and in the given class.
         """
+        Lookup the records associated with the given name
+        that are of the given type and in the given class.
+        """
 
     def query(query, timeout = 10):
-        """Interpret and dispatch a query object to the appropriate
+        """
+        Interpret and dispatch a query object to the appropriate
         lookup* method.
         """
 
     def lookupAddress(name, timeout = 10):
-        """Lookup the A records associated with C{name}."""
+        """
+        Lookup the A records associated with C{name}.
+        """
 
     def lookupAddress6(name, timeout = 10):
-        """Lookup all the A6 records associated with C{name}."""
+        """
+        Lookup all the A6 records associated with C{name}.
+        """
 
     def lookupIPV6Address(name, timeout = 10):
-        """Lookup all the AAAA records associated with C{name}."""
+        """
+        Lookup all the AAAA records associated with C{name}.
+        """
 
     def lookupMailExchange(name, timeout = 10):
-        """Lookup the MX records associated with C{name}."""
+        """
+        Lookup the MX records associated with C{name}.
+        """
 
     def lookupNameservers(name, timeout = 10):
-        """Lookup the the NS records associated with C{name}."""
+        """
+        Lookup the the NS records associated with C{name}.
+        """
 
     def lookupCanonicalName(name, timeout = 10):
-        """Lookup the CNAME records associated with C{name}."""
+        """
+        Lookup the CNAME records associated with C{name}.
+        """
 
     def lookupMailBox(name, timeout = 10):
-        """Lookup the MB records associated with C{name}."""
+        """
+        Lookup the MB records associated with C{name}.
+        """
 
     def lookupMailGroup(name, timeout = 10):
-        """Lookup the MG records associated with C{name}."""
+        """
+        Lookup the MG records associated with C{name}.
+        """
 
     def lookupMailRename(name, timeout = 10):
-        """Lookup the MR records associated with C{name}."""
+        """
+        Lookup the MR records associated with C{name}.
+        """
 
     def lookupPointer(name, timeout = 10):
-        """Lookup the PTR records associated with C{name}."""
+        """
+        Lookup the PTR records associated with C{name}.
+        """
 
     def lookupAuthority(name, timeout = 10):
-        """Lookup the SOA records associated with C{name}."""
+        """
+        Lookup the SOA records associated with C{name}.
+        """
 
     def lookupNull(name, timeout = 10):
-        """Lookup the NULL records associated with C{name}."""
+        """
+        Lookup the NULL records associated with C{name}.
+        """
 
     def lookupWellKnownServices(name, timeout = 10):
-        """Lookup the WKS records associated with C{name}."""
+        """
+        Lookup the WKS records associated with C{name}.
+        """
 
     def lookupHostInfo(name, timeout = 10):
-        """Lookup the HINFO records associated with C{name}."""
+        """
+        Lookup the HINFO records associated with C{name}.
+        """
 
     def lookupMailboxInfo(name, timeout = 10):
-        """Lookup the MINFO records associated with C{name}."""
+        """
+        Lookup the MINFO records associated with C{name}.
+        """
 
     def lookupText(name, timeout = 10):
-        """Lookup the TXT records associated with C{name}."""
+        """
+        Lookup the TXT records associated with C{name}.
+        """
 
     def lookupResponsibility(name, timeout = 10):
-        """Lookup the RP records associated with C{name}."""
+        """
+        Lookup the RP records associated with C{name}.
+        """
 
     def lookupAFSDatabase(name, timeout = 10):
-        """Lookup the AFSDB records associated with C{name}."""
+        """
+        Lookup the AFSDB records associated with C{name}.
+        """
 
     def lookupService(name, timeout = 10):
-        """Lookup the SRV records associated with C{name}."""
+        """
+        Lookup the SRV records associated with C{name}.
+        """
 
     def lookupAllRecords(name, timeout = 10):
-        """Lookup all records associated with C{name}."""
+        """
+        Lookup all records associated with C{name}.
+        """
 
     def lookupZone(name, timeout = 10):
-        """Perform a zone transfer for the given C{name}."""
+        """
+        Perform a zone transfer for the given C{name}.
+        """
 
 
 class IReactorArbitrary(Interface):
+
     def listenWith(portType, *args, **kw):
-        """Start an instance of the given C{portType} listening.
+        """
+        Start an instance of the given C{portType} listening.
 
         @type portType: type which implements L{IListeningPort}
 
@@ -169 +227 @@
 class IReactorTCP(Interface):
 
     def listenTCP(port, factory, backlog=50, interface=''):
-        """Connects a given protocol factory to the given numeric TCP/IP port.
+        """
+        Connects a given protocol factory to the given numeric TCP/IP port.
 
         @param port: a port number on which to listen
 
@@ -188 +247 @@
         """
 
     def connectTCP(host, port, factory, timeout=30, bindAddress=None):
-        """Connect a TCP client.
+        """
+        Connect a TCP client.
 
         @param host: a host name
 
@@ -212 +272 @@
 class IReactorSSL(Interface):
 
     def connectSSL(host, port, factory, contextFactory, timeout=30, bindAddress=None):
-        """Connect a client Protocol to a remote SSL socket.
+        """
+        Connect a client Protocol to a remote SSL socket.
 
         @param host: a host name
 
@@ -250 +311 @@
 
 
 class IReactorUNIX(Interface):
-    """UNIX socket methods."""
+    """
+    UNIX socket methods.
+    """
 
     def connectUNIX(address, factory, timeout=30, checkPID=0):
-        """Connect a client protocol to a UNIX socket.
+        """
+        Connect a client protocol to a UNIX socket.
 
         @param address: a path to a unix socket on the filesystem.
 
@@ -269 +333 @@
         """
 
     def listenUNIX(address, factory, backlog=50, mode=0666, wantPID=0):
-        """Listen on a UNIX socket.
+        """
+        Listen on a UNIX socket.
 
         @param address: a path to a unix socket on the filesystem.
 
@@ -286 +351 @@
 
 
 class IReactorUNIXDatagram(Interface):
-    """datagram UNIX socket methods."""
+    """
+    Datagram UNIX socket methods.
+    """
 
     def connectUNIXDatagram(address, protocol, maxPacketSize=8192, mode=0666, bindAddress=None):
-        """Connect a client protocol to a datagram UNIX socket.
+        """
+        Connect a client protocol to a datagram UNIX socket.
 
         @param address: a path to a unix socket on the filesystem.
 
@@ -305 +373 @@
         """
 
     def listenUNIXDatagram(address, protocol, maxPacketSize=8192, mode=0666):
-        """Listen on a datagram UNIX socket.
+        """
+        Listen on a datagram UNIX socket.
 
         @param address: a path to a unix socket on the filesystem.
 
@@ -320 +389 @@
 
 
 class IReactorUDP(Interface):
-    """UDP socket methods.
+    """
+    UDP socket methods.
 
     IMPORTANT: This is an experimental new interface. It may change
     without backwards compatability. Suggestions are welcome.
     """
 
     def listenUDP(port, protocol, interface='', maxPacketSize=8192):
-        """Connects a given DatagramProtocol to the given numeric UDP port.
+        """
+        Connects a given DatagramProtocol to the given numeric UDP port.
 
         @return: object which provides L{IListeningPort}.
         """
 
     def connectUDP(remotehost, remoteport, protocol, localport=0,
                   interface='', maxPacketSize=8192):
-        """DEPRECATED.
+        """
+        DEPRECATED.
 
         Connects a L{twisted.internet.protocol.ConnectedDatagramProtocol}
         instance to a UDP port.
@@ -342 +414 @@
 
 
 class IReactorMulticast(Interface):
-    """UDP socket methods that support multicast.
+    """
+    UDP socket methods that support multicast.
 
     IMPORTANT: This is an experimental new interface. It may change
     without backwards compatability. Suggestions are welcome.
@@ -366 +439 @@
 
     def spawnProcess(processProtocol, executable, args=(), env={}, path=None,
                      uid=None, gid=None, usePTY=0, childFDs=None):
-        """Spawn a process, with a process protocol.
+        """
+        Spawn a process, with a process protocol.
 
         @param processProtocol: a L{twisted.internet.protocol.ProcessProtocol} instance
 
@@ -430 +504 @@
         """
 
 class IReactorTime(Interface):
-    """Time methods that a Reactor should implement.
     """
+    Time methods that a Reactor should implement.
+    """
 
     def callLater(delay, callable, *args, **kw):
-        """Call a function later.
+        """
+        Call a function later.
 
         @type delay:  C{float}
         @param delay: the number of seconds to wait.
@@ -452 +528 @@
         """
 
     def cancelCallLater(callID):
-        """This method is deprecated.
+        """
+        This method is deprecated.
 
         Cancel a call that would happen later.
 
@@ -463 +540 @@
         """
 
     def getDelayedCalls():
-        """Retrieve all currently scheduled delayed calls.
+        """
+        Retrieve all currently scheduled delayed calls.
 
         @return: A tuple of all L{IDelayedCall} providers representing all
                  currently scheduled calls. This is everything that has been
@@ -472 +550 @@
 
 
 class IDelayedCall(Interface):
-    """A scheduled call.
+    """
+    A scheduled call.
 
     There are probably other useful methods we can add to this interface;
     suggestions are welcome.
     """
 
     def getTime():
-        """Get time when delayed call will happen.
+        """
+        Get time when delayed call will happen.
 
         @return: time in seconds since epoch (a float).
         """
 
     def cancel():
-        """Cancel the scheduled call.
+        """
+        Cancel the scheduled call.
 
         @raises twisted.internet.error.AlreadyCalled: if the call has already
             happened.
@@ -494 +575 @@
         """
 
     def delay(secondsLater):
-        """Delay the scheduled call.
+        """
+        Delay the scheduled call.
 
         @param secondsLater: how many seconds from its current firing time to delay
 
@@ -505 +587 @@
         """
 
     def reset(secondsFromNow):
-        """Reset the scheduled call's timer.
+        """
+        Reset the scheduled call's timer.
 
         @param secondsFromNow: how many seconds from now it should fire,
             equivalent to C{.cancel()} and then doing another
@@ -524 +607 @@
         """
 
 class IReactorThreads(Interface):
-    """Dispatch methods to be run in threads.
+    """
+    Dispatch methods to be run in threads.
 
     Internally, this should use a thread pool and dispatch methods to them.
     """
 
     def callInThread(callable, *args, **kwargs):
-        """Run the callable object in a separate thread.
         """
+        Run the callable object in a separate thread.
+        """
 
     def callFromThread(callable, *args, **kw):
-        """Cause a function to be executed by the reactor thread.
+        """
+        Cause a function to be executed by the reactor thread.
 
         Use this method when you want to run a function in the reactor's thread
         from another thread.  Calling callFromThread should wake up the main
@@ -554 +640 @@
 
 
 class IReactorCore(Interface):
-    """Core methods that a Reactor must implement.
     """
+    Core methods that a Reactor must implement.
+    """
 
     def resolve(name, timeout=10):
-        """Return a L{twisted.internet.defer.Deferred} that will resolve a hostname.
         """
+        Return a L{twisted.internet.defer.Deferred} that will resolve a hostname.
+        """
 
-
     def run():
-        """Fire 'startup' System Events, move the reactor to the 'running'
+        """
+        Fire 'startup' System Events, move the reactor to the 'running'
         state, then run the main loop until it is stopped with stop() or
         crash().
         """
 
     def stop():
-        """Fire 'shutdown' System Events, which will move the reactor to the
-        'stopped' state and cause reactor.run() to exit. """
+        """
+        Fire 'shutdown' System Events, which will move the reactor to the
+        'stopped' state and cause reactor.run() to exit.
+        """
 
     def crash():
-        """Stop the main loop *immediately*, without firing any system events.
+        """
+        Stop the main loop *immediately*, without firing any system events.
 
         This is named as it is because this is an extremely "rude" thing to do;
         it is possible to lose data and put your system in an inconsistent
@@ -582 +673 @@
         """
 
     def iterate(delay=0):
-        """Run the main loop's I/O polling function for a period of time.
+        """
+        Run the main loop's I/O polling function for a period of time.
 
         This is most useful in applications where the UI is being drawn "as
         fast as possible", such as games. All pending L{IDelayedCall}s will
@@ -596 +688 @@
         """
 
     def fireSystemEvent(eventType):
-        """Fire a system-wide event.
+        """
+        Fire a system-wide event.
 
         System-wide events are things like 'startup', 'shutdown', and
         'persist'.
         """
 
     def addSystemEventTrigger(phase, eventType, callable, *args, **kw):
-        """Add a function to be called when a system event occurs.
+        """
+        Add a function to be called when a system event occurs.
 
         Each "system event" in Twisted, such as 'startup', 'shutdown', and
         'persist', has 3 phases: 'before', 'during', and 'after' (in that
@@ -637 +731 @@
         """
 
     def removeSystemEventTrigger(triggerID):
-        """Removes a trigger added with addSystemEventTrigger.
+        """
+        Removes a trigger added with addSystemEventTrigger.
 
         @param triggerID: a value returned from addSystemEventTrigger.
         """
 
     def callWhenRunning(callable, *args, **kw):
-        """Call a function when the reactor is running.
+        """
+        Call a function when the reactor is running.
 
         If the reactor has not started, the callable will be scheduled
         to run when it does start. Otherwise, the callable will be invoked
@@ -661 +757 @@
 
 
 class IReactorPluggableResolver(Interface):
-    """A reactor with a pluggable name resolver interface.
     """
+    A reactor with a pluggable name resolver interface.
+    """
     def installResolver(resolver):
-        """Set the internal resolver to use to for name lookups.
+        """
+        Set the internal resolver to use to for name lookups.
 
         @type resolver: An object implementing the L{IResolverSimple} interface
         @param resolver: The new resolver to use.
@@ -683 +781 @@
     """
 
     def addReader(reader):
-        """I add reader to the set of file descriptors to get read events for.
+        """
+        I add reader to the set of file descriptors to get read events for.
 
         @param reader: An L{IReadDescriptor} provider that will be checked for
                        read events until it is removed from the reactor with
@@ -693 +792 @@
         """
 
     def addWriter(writer):
-        """I add writer to the set of file descriptors to get write events for.
+        """
+        I add writer to the set of file descriptors to get write events for.
 
         @param writer: An L{IWriteDescriptor} provider that will be checked for
                        read events until it is removed from the reactor with
@@ -703 +803 @@
         """
 
     def removeReader(reader):
-        """Removes an object previously added with L{addReader}.
+        """
+        Removes an object previously added with L{addReader}.
 
         @return: C{None}.
         """
 
     def removeWriter(writer):
-        """Removes an object previously added with L{addWriter}.
+        """
+        Removes an object previously added with L{addWriter}.
 
         @return: C{None}.
         """
 
     def removeAll():
-        """Remove all readers and writers.
+        """
+        Remove all readers and writers.
 
         Should not remove reactor internal reactor connections (like a waker).
 
@@ -725 +828 @@
 
 
 class IListeningPort(Interface):
-    """A listening port.
     """
+    A listening port.
+    """
 
     def startListening():
-        """Start listening on this port.
+        """
+        Start listening on this port.
 
         @raise CannotListenError: If it cannot listen on this port (e.g., it is
                                   a TCP port and it cannot bind to the required
@@ -737 +842 @@
         """
 
     def stopListening():
-        """Stop listening on this port.
+        """
+        Stop listening on this port.
 
         If it does not complete immediately, will return Deferred that fires
         upon completion.
         """
 
     def getHost():
-        """Get the host that this port is listening for.
+        """
+        Get the host that this port is listening for.
 
         @return: An L{IAddress} provider.
         """
 
 
 class IFileDescriptor(Interface):
-    """A file descriptor.
     """
+    A file descriptor.
+    """
 
     def fileno():
         """
@@ -761 +869 @@
         """
 
     def connectionLost(reason):
-        """Called when the connection was lost.
+        """
+        Called when the connection was lost.
 
         This is called when the connection on a selectable object has been
         lost.  It will be called whether the connection was closed explicitly,
@@ -777 +886 @@
                        failure may be of other classes as well.
         """
 
+    def logPrefix():
+        """
+        Prefix used when logging execution of reading or writing from this
+        descriptor.
+        """
+
 class IReadDescriptor(IFileDescriptor):
 
     def doRead():
-        """Some data is available for reading on your descriptor.
         """
+        Some data is available for reading on your descriptor.
+        """
 
 
 class IWriteDescriptor(IFileDescriptor):
 
     def doWrite():
-        """Some data can be written to your descriptor.
         """
+        Some data can be written to your descriptor.
+        """
 
 
 class IReadWriteDescriptor(IReadDescriptor, IWriteDescriptor):
-    """I am a L{FileDescriptor<twisted.internet.abstract.FileDescriptor>} that can both read and write.
     """
+    I am a L{FileDescriptor<twisted.internet.abstract.FileDescriptor>} that can both read and write.
+    """
 
 
 class IHalfCloseableDescriptor(Interface):
-    """A descriptor that can be half-closed."""
+    """
+    A descriptor that can be half-closed.
+    """
 
     def writeConnectionLost(reason):
-        """Indicates write connection was lost."""
+        """
+        Indicates write connection was lost.
+        """
 
     def readConnectionLost(reason):
-        """Indicates read connection was lost."""
+        """
+        Indicates read connection was lost.
+        """
 
 
 class ISystemHandle(Interface):
-    """An object that wraps a networking OS-specific handle."""
+    """
+    An object that wraps a networking OS-specific handle.
+    """
 
     def getHandle():
-        """Return a system- and reactor-specific handle.
+        """
+        Return a system- and reactor-specific handle.
 
         This might be a socket.socket() object, or some other type of
         object, depending on which reactor is being used. Use and
@@ -822 +949 @@
 
 
 class IConsumer(Interface):
-    """A consumer consumes data from a producer."""
+    """
+    A consumer consumes data from a producer.
+    """
 
     def registerProducer(producer, streaming):
         """
@@ -850 +979 @@
         """
 
     def unregisterProducer():
-        """Stop consuming data from a producer, without disconnecting.
         """
+        Stop consuming data from a producer, without disconnecting.
+        """
 
     def write(data):
-        """The producer will write data by calling this method."""
+        """
+        The producer will write data by calling this method.
+        """
 
 class IFinishableConsumer(IConsumer):
-    """A Consumer for producers that finish.
+    """
+    A Consumer for producers that finish.
 
     This interface is semi-stable.
     """
     def finish():
-        """The producer has finished producing."""
+        """
+        The producer has finished producing.
+        """
 
 class IProducer(Interface):
-    """A producer produces data for a consumer.
+    """
+    A producer produces data for a consumer.
 
     Typically producing is done by calling the write method of an class
     implementing L{IConsumer}.
     """
 
     def stopProducing():
-        """Stop producing data.
+        """
+        Stop producing data.
 
         This tells a producer that its consumer has died, so it must stop
         producing data for good.
@@ -891 +1028 @@
     """
 
     def pauseProducing():
-        """Pause producing data.
+        """
+        Pause producing data.
 
         Tells a producer that it has produced too much data to process for
         the time being, and to stop until resumeProducing() is called.
         """
     def resumeProducing():
-        """Resume producing data.
+        """
+        Resume producing data.
 
         This tells a producer to re-add itself to the main loop and produce
         more data for its consumer.
@@ -912 +1051 @@
     """
 
     def resumeProducing():
-        """Produce data for the consumer a single time.
+        """
+        Produce data for the consumer a single time.
 
         This tells a producer to produce data for the consumer once
         (not repeatedly, once only). Typically this will be done
@@ -923 +1063 @@
 class IProtocol(Interface):
 
     def dataReceived(data):
-        """Called whenever data is received.
+        """
+        Called whenever data is received.
 
         Use this method to translate to a higher-level message.  Usually, some
         callback will be made upon the receipt of each complete protocol
@@ -937 +1078 @@
         """
 
     def connectionLost(reason):
-        """Called when the connection is shut down.
+        """
+        Called when the connection is shut down.
 
         Clear any circular references here, and any external references
         to this Protocol.  The connection has been closed. The C{reason}
@@ -949 +1091 @@
         """
 
     def makeConnection(transport):
-        """Make a connection to a transport and a server.
         """
+        Make a connection to a transport and a server.
+        """
 
     def connectionMade():
-        """Called when a connection is made.
+        """
+        Called when a connection is made.
 
         This may be considered the initializer of the protocol, because
         it is called when the connection is completed.  For clients,
@@ -965 +1109 @@
 
 
 class IHalfCloseableProtocol(Interface):
-    """Implemented to indicate they want notification of half-closes.
+    """
+    Implemented to indicate they want notification of half-closes.
 
     TCP supports the notion of half-closing the connection, e.g.
     closing the write side but still not stopping reading. A protocol
@@ -974 +1119 @@
     """
 
     def readConnectionLost():
-        """Notification of the read connection being closed.
+        """
+        Notification of the read connection being closed.
 
         This indicates peer did half-close of write side. It is now
         the responsiblity of the this protocol to call
@@ -988 +1134 @@
         """
 
     def writeConnectionLost():
-        """Notification of the write connection being closed.
+        """
+        Notification of the write connection being closed.
 
         This will never be called for TCP connections as TCP does not
         support notification of this type of half-close.
@@ -996 +1143 @@
 
 
 class IProtocolFactory(Interface):
-    """Interface for protocol factories.
     """
+    Interface for protocol factories.
+    """
 
     def buildProtocol(addr):
-        """Called when a connection has been established to addr.
+        """
+        Called when a connection has been established to addr.
 
         If None is returned, the connection is assumed to have been refused,
         and the Port will close the connection.
@@ -1013 +1162 @@
         """
 
     def doStart():
-        """Called every time this is connected to a Port or Connector."""
+        """
+        Called every time this is connected to a Port or Connector.
+        """
 
     def doStop():
-        """Called every time this is unconnected from a Port or Connector."""
+        """
+        Called every time this is unconnected from a Port or Connector.
+        """
 
 
 class ITransport(Interface):
-    """I am a transport for bytes.
+    """
+    I am a transport for bytes.
 
     I represent (and wrap) the physical connection and synchronicity
     of the framework which is talking to the network.  I make no
@@ -1032 +1186 @@
     """
 
     def write(data):
-        """Write some data to the physical connection, in sequence, in a
+        """
+        Write some data to the physical connection, in sequence, in a
         non-blocking fashion.
 
         If possible, make sure that it is all written.  No data will
@@ -1041 +1196 @@
         """
 
     def writeSequence(data):
-        """Write a list of strings to the physical connection.
+        """
+        Write a list of strings to the physical connection.
 
         If possible, make sure that all of the data is written to
         the socket at once, without first copying it all into a
@@ -1049 +1205 @@
         """
 
     def loseConnection():
-        """Close my connection, after writing all pending data.
+        """
+        Close my connection, after writing all pending data.
 
         Note that if there is a registered producer on a transport it
         will not be closed until the producer has been unregistered.
         """
 
     def getPeer():
-        """Get the remote address of this connection.
+        """
+        Get the remote address of this connection.
 
         Treat this method with caution.  It is the unfortunate result of the
         CGI and Jabber standards, but should not be considered reliable for
@@ -1076 +1234 @@
 
 
 class ITCPTransport(ITransport):
-    """A TCP based transport."""
+    """
+    A TCP based transport.
+    """
 
     def loseWriteConnection():
-        """Half-close the write side of a TCP connection.
+        """
+        Half-close the write side of a TCP connection.
 
         If the protocol instance this is attached to provides
         IHalfCloseableProtocol, it will get notified when the operation is
@@ -1089 +1250 @@
         """
 
     def getTcpNoDelay():
-        """Return if TCP_NODELAY is enabled."""
+        """
+        Return if TCP_NODELAY is enabled."""
 
     def setTcpNoDelay(enabled):
-        """Enable/disable TCP_NODELAY.
+        """
+        Enable/disable TCP_NODELAY.
 
         Enabling TCP_NODELAY turns off Nagle's algorithm. Small packets are
-        sent sooner, possibly at the expense of overall throughput."""
+        sent sooner, possibly at the expense of overall throughput.
+        """
 
     def getTcpKeepAlive():
-        """Return if SO_KEEPALIVE enabled."""
+        """
+        Return if SO_KEEPALIVE enabled.
+        """
 
     def setTcpKeepAlive(enabled):
-        """Enable/disable SO_KEEPALIVE.
+        """
+        Enable/disable SO_KEEPALIVE.
 
         Enabling SO_KEEPALIVE sends packets periodically when the connection
         is otherwise idle, usually once every two hours. They are intended
-        to allow detection of lost peers in a non-infinite amount of time."""
+        to allow detection of lost peers in a non-infinite amount of time.
+        """
 
     def getHost():
-        """Returns L{IPv4Address}."""
+        """
+        Returns L{IPv4Address}.
+        """
 
     def getPeer():
-        """Returns L{IPv4Address}."""
+        """
+        Returns L{IPv4Address}.
+        """
 
 
 class ITLSTransport(ITCPTransport):
-    """A TCP transport that supports switching to TLS midstream.
+    """
+    A TCP transport that supports switching to TLS midstream.
 
     Once TLS mode is started the transport will implement L{ISSLTransport}.
     """
 
     def startTLS(contextFactory):
-        """Initiate TLS negotiation.
+        """
+        Initiate TLS negotiation.
 
         @param contextFactory: A context factory (see L{ssl.py<twisted.internet.ssl>})
         """
 
 class ISSLTransport(ITCPTransport):
-    """A SSL/TLS based transport."""
+    """
+    A SSL/TLS based transport.
+    """
 
     def getPeerCertificate():
-        """Return an object with the peer's certificate info."""
+        """
+        Return an object with the peer's certificate info.
+        """
 
 
 class IProcessTransport(ITransport):
-    """A process transport.
+    """
+    A process transport.
 
     @ivar pid: The Process-ID of this process.
     """
 
     def closeStdin():
-        """Close stdin after all data has been written out."""
+        """
+        Close stdin after all data has been written out.
+        """
 
     def closeStdout():
-        """Close stdout."""
+        """
+        Close stdout.
+        """
 
     def closeStderr():
-        """Close stderr."""
+        """
+        Close stderr.
+        """
 
     def closeChildFD(descriptor):
         """
@@ -1171 +1356 @@
         """
 
     def loseConnection():
-        """Close stdin, stderr and stdout."""
+        """
+        Close stdin, stderr and stdout.
+        """
 
     def signalProcess(signalID):
-        """Send a signal to the process.
+        """
+        Send a signal to the process.
 
         @param signalID: can be
           - one of C{\"HUP\"}, C{\"KILL\"}, C{\"STOP\"}, or C{\"INT\"}.
@@ -1190 +1378 @@
 
 
 class IServiceCollection(Interface):
-    """An object which provides access to a collection of services."""
+    """
+    An object which provides access to a collection of services.
+    """
 
     def getServiceNamed(serviceName):
-        """Retrieve the named service from this application.
+        """
+        Retrieve the named service from this application.
 
         Raise a KeyError if there is no such service name.
         """
 
     def addService(service):
-        """Add a service to this collection.
         """
+        Add a service to this collection.
+        """
 
     def removeService(service):
-        """Remove a service from this collection."""
+        """
+        Remove a service from this collection.
+        """
 
 
 class IUDPTransport(Interface):
-    """Transport for UDP DatagramProtocols."""
+    """
+    Transport for UDP DatagramProtocols.
+    """
 
     def write(packet, addr=None):
-        """Write packet to given address.
+        """
+        Write packet to given address.
 
         @param addr: a tuple of (ip, port). For connected transports must
                      be the address the transport is connected to, or None.
@@ -1221 +1418 @@
         """
 
     def connect(host, port):
-        """Connect the transport to an address.
+        """
+        Connect the transport to an address.
 
         This changes it to connected mode. Datagrams can only be sent to
         this address, and will only be received from this address. In addition
@@ -1233 +1431 @@
         """
 
     def getHost():
-        """Returns IPv4Address."""
+        """
+        Returns IPv4Address.
+        """
 
     def stopListening():
-        """Stop listening on this port.
+        """
+        Stop listening on this port.
 
         If it does not complete immediately, will return Deferred that fires
         upon completion.
@@ -1244 +1445 @@
 
 
 class IUDPConnectedTransport(Interface):
-    """DEPRECATED. Transport for UDP ConnectedPacketProtocols."""
+    """
+    DEPRECATED. Transport for UDP ConnectedPacketProtocols.
+    """
 
     def write(packet):
-        """Write packet to address we are connected to."""
+        """
+        Write packet to address we are connected to.
+        """
 
     def getHost():
-        """Returns UNIXAddress."""
+        """
+        Returns UNIXAddress.
+        """
 
 
 class IUNIXDatagramTransport(Interface):
-    """Transport for UDP PacketProtocols."""
+    """
+    Transport for UDP PacketProtocols.
+    """
 
     def write(packet, address):
-        """Write packet to given address."""
+        """
+        Write packet to given address.
+        """
 
     def getHost():
-        """Returns UNIXAddress."""
+        """
+        Returns UNIXAddress.
+        """
 
 
 class IUNIXDatagramConnectedTransport(Interface):
-    """Transport for UDP ConnectedPacketProtocols."""
+    """
+    Transport for UDP ConnectedPacketProtocols.
+    """
 
     def write(packet):
-        """Write packet to address we are connected to."""
+        """
+        Write packet to address we are connected to.
+        """
 
     def getHost():
-        """Returns UNIXAddress."""
+        """
+        Returns UNIXAddress.
+        """
 
     def getPeer():
-        """Returns UNIXAddress."""
+        """
+        Returns UNIXAddress.
+        """
 
 
 class IMulticastTransport(Interface):
-    """Additional functionality for multicast UDP."""
+    """
+    Additional functionality for multicast UDP.
+    """
 
     def getOutgoingInterface():
-        """Return interface of outgoing multicast packets."""
+        """
+        Return interface of outgoing multicast packets.
+        """
 
     def setOutgoingInterface(addr):
-        """Set interface for outgoing multicast packets.
+        """
+        Set interface for outgoing multicast packets.
 
         Returns Deferred of success.
         """
 
     def getLoopbackMode():
-        """Return if loopback mode is enabled."""
+        """
+        Return if loopback mode is enabled.
+        """
 
     def setLoopbackMode(mode):
-        """Set if loopback mode is enabled."""
+        """
+        Set if loopback mode is enabled.
+        """
 
     def getTTL():
-        """Get time to live for multicast packets."""
+        """
+        Get time to live for multicast packets.
+        """
 
     def setTTL(ttl):
-        """Set time to live on multicast packets."""
+        """
+        Set time to live on multicast packets.
+        """
 
     def joinGroup(addr, interface=""):
-        """Join a multicast group. Returns Deferred of success or failure.
+        """
+        Join a multicast group. Returns Deferred of success or failure.
 
         If an error occurs, the returned Deferred will fail with
         L{error.MulticastJoinError}.
         """
 
     def leaveGroup(addr, interface=""):
-        """Leave multicast group, return Deferred of success."""
+        """
+        Leave multicast group, return Deferred of success.
+        """
+