Merge trunk.

samantehrani · Jul 20, 2016 · e9b254c · e9b254c
2 parents fed94e8 + a2b5087
commit e9b254c
Show file tree

Hide file tree

Showing 149 changed files with 772 additions and 591 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -1,47 +1,64 @@
+#
+# This is the Travis-CI configuration.
+#
+# The actual dependency installation and test execution is done via tox as a
+# way to share the same process between Travis-CI and Buildbot.
+#
 language: python
 sudo: false
 
-addons:
-  apt:
-    packages:
-    - libssl-dev
-    - libssl1.0.0
-
-cache:
-  directories:
-    - $HOME/.cache/pip
-
-python:
-  - "2.7"
-  - "3.3"
-  - "3.4"
-  - "3.5"
+env:
+  global:
+    - TRIAL_REPORTER=text
 
 matrix:
   include:
+    - python: 2.7
+      env: TOXENV=py27-coverage-posix,codecov-publish
+    # FIXME: https://twistedmatrix.com/trac/ticket/8633
+    # Coverage should also be reported for nomodules tests so that we also
+    # get report for those conditional branches.
+    - python: 2.7
+      env: TOXENV=py27-nomodules-posix
+    - python: 3.3
+      env: TOXENV=py33-coverage-posix,codecov-publish
+    - python: 3.4
+      env: TOXENV=py34-coverage-posix,codecov-publish
+    - python: 3.5
+      env: TOXENV=py35-coverage-posix,codecov-publish
+    # For now all non-trial tests are in a single job to reduce the time spent
+    # on starting separate jobs.
+    - python: 2.7
+      env: TOXENV=narrativedocs,pyflakes,topfile,manifest-checker
+    #
+    # OSX 10.10
+    #
     - language: generic
       os: osx
       # 7.1 is OS X 10.10.x
       # see: https://docs.travis-ci.com/user/languages/objective-c/#Supported-OS-X-iOS-SDK-versions
       osx_image: xcode7.1
       python: 2.7
       env: TOXENV=py27-coverage-posix,codecov-publish
+
   allow_failures:
     # For now, OSX run on Travis-CI has a few failures.
     - language: generic
       python: 2.7
 
-env:
-  global:
-    - TRIAL_REPORTER=text
+addons:
+  apt:
+    packages:
+    - libssl-dev
+    - libssl1.0.0
+
+cache:
+  directories:
+    - $HOME/.cache/pip
 
-# Install packages in a virtualenv.
-# Install the virtualenv if required.
-# Install Python version if required.
 install:
   - ./.travis/install.sh tox tox-travis
 
-
 # FIXME: https://twistedmatrix.com/trac/ticket/8373
 # By default, Travis only clones one branch.
 # Some tests require the presence of the `trunk` branch so here we are, also

diff --git a/NEWS b/NEWS
@@ -4487,7 +4487,7 @@ Bugfixes
    intermittent error, crashing at startup with a ZeroDivisionError
    while trying to report progress. (#4463)
  - twisted.conch.ssh.connection.SSHConnection now replies to requests
-   to open an unknown channel with a OPEN_UNKNOWN_CHANNEL_TYPE message
+   to open an unknown channel with an OPEN_UNKNOWN_CHANNEL_TYPE message
    instead of closing the connection. (#4490)
 
 Deprecations and Removals

diff --git a/appveyor.yml b/appveyor.yml
@@ -11,7 +11,7 @@ build: off
 # AppVeyor.
 test: off
 
-# Don't build branch if there is a open PR, to prevent double builds.
+# Don't build branch if there is an open PR, to prevent double builds.
 # For now, Appveyour will only build PR commits and not commits to master or
 # commits on random branches without an associated PR.
 skip_branch_with_pr: true

diff --git a/docs/conch/howto/conch_client.rst b/docs/conch/howto/conch_client.rst
@@ -148,7 +148,7 @@ The ``agentEndpoint`` argument gives the ``SSHCommandClientEndpoint`` an opportu
 The agent may already be loaded with keys, or may have some other way to authenticate a connection.
 Using the agent can mean the process actually establishing the SSH connection doesn't need to load any authentication material (passwords or keys) itself (often convenient in case keys are encrypted and potentially more secure, since only the agent process ever actually holds the secrets).
 The value for this argument is another ``IStreamClientEndpoint`` .
-Often in a typical *NIX desktop environment, the *SSH_AUTH_SOCK* environment variable will give the location of a AF_UNIX socket.
+Often in a typical *NIX desktop environment, the *SSH_AUTH_SOCK* environment variable will give the location of an AF_UNIX socket.
 This explains the value ``echoclient_ssh.py`` assigns this parameter when *--no-agent* is not given.
 
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -302,7 +302,7 @@
 # The scheme of the identifier. Typical schemes are ISBN or URL.
 #epub_scheme = ''
 
-# The unique identifier of the text. This can be a ISBN number
+# The unique identifier of the text. This can be an ISBN number
 # or the project homepage.
 #epub_identifier = ''
 

diff --git a/docs/core/development/policy/compatibility-policy.rst b/docs/core/development/policy/compatibility-policy.rst
@@ -304,7 +304,7 @@ How to deprecate APIs
 Classes
 ^^^^^^^
 
-Classes are deprecated by raising an warning when they are access from within their module, using the :api:`twisted.python.deprecate.deprecatedModuleAttribute <deprecatedModuleAttribute>` helper.
+Classes are deprecated by raising a warning when they are access from within their module, using the :api:`twisted.python.deprecate.deprecatedModuleAttribute <deprecatedModuleAttribute>` helper.
 
 .. code-block:: python
 

diff --git a/docs/core/development/policy/writing-standard.rst b/docs/core/development/policy/writing-standard.rst
@@ -311,7 +311,7 @@ that they will see the document do. For example:
       backend;
     - creating an anonymous access read-only SFTP server using a proxy
       backend connecting to an HTTP server; and
-    - creating a anonymous access read and write SFTP server using a
+    - creating an anonymous access read and write SFTP server using a
       filesystem backend.
 
 

diff --git a/docs/core/examples/courier.py b/docs/core/examples/courier.py
@@ -4,7 +4,7 @@
 # See LICENSE for details.
 
 """
-Example of a interfacing to Courier's mail filter interface.
+Example of an interface to Courier's mail filter.
 """
 
 LOGFILE = '/tmp/filter.log'
@@ -24,7 +24,7 @@
 ALLFILTERS='/var/lib/courier/allfilters'
 FILTERNAME='twistedfilter'
 
-import os, os.path 
+import os, os.path
 from syslog import syslog, openlog, LOG_MAIL
 from rfc822 import Message
 
@@ -38,6 +38,7 @@ def trace_dump():
     # just to be safe
     del tb
 
+
 def safe_del(file):
     try:
         if os.path.isdir(file):
@@ -48,23 +49,29 @@ def safe_del(file):
         pass
 
 
+
 class DieWhenLost(Protocol):
     def connectionLost(self, reason=None):
         reactor.stop()
 
 
+
 class MailProcessor(basic.LineReceiver):
-    """I process a mail message.
-    
-    Override filterMessage to do any filtering you want."""
+    """
+    I process a mail message.
+
+    Override filterMessage to do any filtering you want.
+    """
     messageFilename = None
     delimiter = '\n'
-
+
+
     def connectionMade(self):
         log.msg('Connection from %r' % self.transport)
         self.state = 'connected'
         self.metaInfo = []
 
+
     def lineReceived(self, line):
         if self.state == 'connected':
             self.messageFilename = line
@@ -78,6 +85,7 @@ def lineReceived(self, line):
                     return
                 self.filterMessage()
 
+
     def filterMessage(self):
         """Override this.
 
@@ -89,7 +97,7 @@ def filterMessage(self):
         except:
             trace_dump()
             self.sendLine('435 %s processing error' % FILTERNAME)
-        
+
 
 def main():
     # Listen on the UNIX socket

diff --git a/docs/core/howto/glossary.rst b/docs/core/howto/glossary.rst
@@ -230,7 +230,7 @@ Daemon
 
 
 
-  A instance of :api:`twisted.internet.defer.Deferred <twisted.internet.defer.Deferred>` , an
+  An instance of :api:`twisted.internet.defer.Deferred <twisted.internet.defer.Deferred>` , an
   abstraction for handling chains of callbacks and error handlers
   ("errbacks" ).
   See the :doc:`Deferring Execution <defer>` HOWTO.

diff --git a/docs/core/howto/tutorial/client.rst b/docs/core/howto/tutorial/client.rst
@@ -44,6 +44,13 @@ using the factory directly, it's also more convenient.
 
 
 
+Additionally, because this code now programmatically receives its host and
+port, it's a bit less convenient to use clientFromString. Instead, we move to
+using the specific endpoint we want. In this case, because we're connecting as
+a client over IPv4 using TCP, we want the ``TCP4ClientEndpoint``.
+
+
+
 
 
 

diff --git a/docs/core/howto/tutorial/factory.rst b/docs/core/howto/tutorial/factory.rst
@@ -36,8 +36,21 @@ Support HTTPS
 
 All we need to do to code an HTTPS site is just write a context factory (in
 this case, which loads the certificate from a certain file) and then use the
-twisted.application.internet.SSLServer method. Note that one factory (in this
-case, a site) can listen on multiple ports with multiple protocols.
+``twisted.internet.endpoints.serverFromString`` method to build a SSL endpoint.
+Note that one factory (in this case, a site) can listen on multiple ports with
+multiple protocols.
+
+Of course, this endpoint doesn't work without a TLS certificate and a private
+key. You'll need to create a self-signed cert and key. This will obviously not
+be trusted by your web browser, so you'll see a warning when you connect. In
+this case, don't worry: you're not at risk.
+
+To create a certificate and key that can be used by this tutorial, run the
+following:
+
+.. code-block:: bash
+
+    openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365
 
 
 

diff --git a/docs/core/howto/tutorial/intro.rst b/docs/core/howto/tutorial/intro.rst
@@ -22,7 +22,7 @@ This is the first part of the Twisted tutorial :doc:`Twisted from Scratch, or Th
 
 
 If you're not familiar with 'finger' it's probably because it's not used as
-much nowadays as it used to be. Basically, if you run ``finger nail`` 
+much nowadays as it used to be. Basically, if you run ``finger nail``
 or ``finger nail@example.com`` the target computer spits out some
 information about the user named ``nail`` . For instance:
 
@@ -32,7 +32,7 @@ information about the user named ``nail`` . For instance:
 
 .. code-block:: console
 
-    
+
     Login: nail                           Name: Nail Sharp
     Directory: /home/nail                 Shell: /usr/bin/sh
     Last login Wed Mar 31 18:32 2004 (PST)
@@ -44,10 +44,10 @@ information about the user named ``nail`` . For instance:
 
 
 If the target computer does not have
-the ``fingerd`` :ref:`daemon <core-howto-glossary-daemon>` 
+the ``fingerd`` :ref:`daemon <core-howto-glossary-daemon>`
 running you'll get a "Connection Refused" error. Paranoid sysadmins
 keep ``fingerd`` off or limit the output to hinder crackers
-and harassers. The above format is the standard ``fingerd`` 
+and harassers. The above format is the standard ``fingerd``
 default, but an alternate implementation can output anything it wants,
 such as automated responsibility status for everyone in an
 organization. You can also define pseudo "users", which are
@@ -58,7 +58,7 @@ essentially keywords.
 
 This portion of the tutorial makes use of factories and protocols as
 introduced in the :doc:`Writing a TCP Server howto <../servers>` and
-deferreds as introduced in :doc:`Using Deferreds <../defer>` 
+deferreds as introduced in :doc:`Using Deferreds <../defer>`
 and :doc:`Generating Deferreds <../gendefer>` . Services and
 applications are discussed in :doc:`Using the Twisted Application Framework <../application>` .
 
@@ -140,9 +140,20 @@ Do Nothing
 .. literalinclude:: listings/finger/finger02.py
 
 
-Here, ``reactor.listenTCP`` opens port 1079. (The number 1079 is a
-reminder that eventually we want to run on port 79, the standard port for
-finger servers.)  The specified factory, ``FingerFactory`` , is used to
+Here we use ``endpoints.serverFromString`` to create a Twisted endpoint. An
+endpoint is a Twisted concept that encapsulates one end of a connection. There
+are different endpoints for clients and servers. One of the great advantages of
+endpoints is that they can be described textually using a kind of
+domain-specific language. For example, here, we ask Twisted to create a TCP
+endpoint for a server using the string ``"tcp:1079"``. That, along with the
+call to ``serverFromString``, tells Twisted to look for a TCP endpoint, and
+pass it the port 1079. The endpoint returned from that function can then have
+the ``listen()`` method invoked on it, which causes Twisted to start listening
+on port 1079. (The number 1079 is a reminder that eventually we want to run on
+port 79, the standard port for finger servers.) For more detail on endpoints,
+check out the :doc:`Getting Connected With Endpoints <../endpoints>`.
+
+The factory given to the ``listen()`` method, ``FingerFactory`` , is used to
 handle incoming requests on that port.  Specifically, for each request, the
 reactor calls the factory's ``buildProtocol`` method, which in this
 case causes ``FingerProtocol`` to be instantiated. Since the protocol
@@ -212,7 +223,7 @@ look something like this:
 
 .. code-block:: console
 
-    
+
     $ telnet localhost 1079
     Trying 127.0.0.1...
     Connected to localhost.localdomain.
@@ -334,7 +345,7 @@ Deferred, to which we start to attach *callbacks* .  The
 deferred action in ``FingerFactory`` is actually a
 fast-running expression consisting of one dictionary
 method, ``get`` . Since this action can execute without
-delay, ``FingerFactory.getUser`` 
+delay, ``FingerFactory.getUser``
 uses ``defer.succeed`` to create a Deferred which already has
 a result, meaning its return value will be passed immediately to the
 first callback function, which turns out to
@@ -423,7 +434,7 @@ run a finger server with root privileges? Well, the common solution
 is "privilege shedding" : after binding to the network, become a different,
 less privileged user. We could have done it ourselves, but Twisted has a
 built-in way to do it. We will create a snippet as above, but now we will define
-an application object. That object will have ``uid`` 
+an application object. That object will have ``uid``
 and ``gid`` attributes. When running it (later we will see how) it will
 bind to ports, shed privileges and then run.
 
@@ -457,7 +468,7 @@ networking code.
 
 .. code-block:: console
 
-    
+
     root% twistd -ny finger11.tac # just like before
     root% twistd -y finger11.tac # daemonize, keep pid in twistd.pid
     root% twistd -y finger11.tac --pidfile=finger.pid
@@ -484,18 +495,19 @@ Configuration <core-howto-glossary-tac>` file).
 .. literalinclude:: listings/finger/finger11.tac
 
 
-Instead of using ``reactor.listenTCP`` as in the above
+Instead of using ``endpoints.serverFromString`` as in the above
 examples, here we are using its application-aware
-counterpart, ``internet.TCPServer`` .  Notice that when it is
+counterpart, ``strports.service`` .  Notice that when it is
 instantiated, the application object itself does not reference either
-the protocol or the factory.  Any services (such as TCPServer) which
-have the application as their parent will be started when the
-application is started by twistd.  The application object is more
-useful for returning an object that supports the :api:`twisted.application.service.IService <IService>` , :api:`twisted.application.service.IServiceCollection <IServiceCollection>` , :api:`twisted.application.service.IProcess <IProcess>` ,
-and :api:`twisted.persisted.sob.IPersistable <sob.IPersistable>` 
+the protocol or the factory.  Any services (such as the one we created with
+``strports.service``) which have the application as their parent will be
+started when the application is started by twistd.  The application object is
+more useful for returning an object that supports the
+:api:`twisted.application.service.IService <IService>` , :api:`twisted.application.service.IServiceCollection <IServiceCollection>` , :api:`twisted.application.service.IProcess <IProcess>` ,
+and :api:`twisted.persisted.sob.IPersistable <sob.IPersistable>`
 interfaces with the given parameters; we'll be seeing these in the
-next part of the tutorial. As the parent of the TCPServer we opened,
-the application lets us manage the TCPServer.
+next part of the tutorial. As the parent of the endpoint we opened, the
+application lets us manage the endpoint.
-Original file line number
+Diff line change
@@ Expand Up / @@ -304,7 +304,7 @@ How to deprecate APIs @@
     Classes
     ^^^^^^^
-    Classes are deprecated by raising an warning when they are access from within their module, using the :api:`twisted.python.deprecate.deprecatedModuleAttribute <deprecatedModuleAttribute>` helper.
+    Classes are deprecated by raising a warning when they are access from within their module, using the :api:`twisted.python.deprecate.deprecatedModuleAttribute <deprecatedModuleAttribute>` helper.
     .. code-block:: python
@@ Expand Down @@