[Python-modules-commits] [twisted] 01/03: New upstream version 17.5.0
Free Ekanayaka
freee at moszumanska.debian.org
Sun Aug 27 09:28:41 UTC 2017
This is an automated email from the git hooks/post-receive script.
freee pushed a commit to branch master
in repository twisted.
commit 17c33a69cef5b46f5c1a9d285b51851365653b84
Author: Free Ekanayaka <free.ekanayaka at canonical.com>
Date: Sun Aug 27 09:18:34 2017 +0000
New upstream version 17.5.0
---
MANIFEST.in | 5 +-
NEWS => NEWS.rst | 186 ++-
PKG-INFO | 2 +-
README.rst | 8 +-
docs/conch/examples/telnet_echo.tac | 2 +-
docs/core/development/policy/release-process.rst | 12 +-
docs/core/howto/application.rst | 8 +-
docs/core/howto/endpoints.rst | 30 +
docs/core/howto/logger.rst | 145 +--
docs/core/howto/threading.rst | 4 +-
.../tutorial/listings/finger/finger/finger.py | 22 +-
.../howto/tutorial/listings/finger/finger05.py | 2 +-
.../howto/tutorial/listings/finger/finger06.py | 4 +-
.../howto/tutorial/listings/finger/finger07.py | 10 +-
.../howto/tutorial/listings/finger/finger08.py | 10 +-
.../howto/tutorial/listings/finger/finger09.py | 6 +-
.../howto/tutorial/listings/finger/finger10.py | 10 +-
.../howto/tutorial/listings/finger/finger11.tac | 10 +-
.../howto/tutorial/listings/finger/finger12.tac | 12 +-
.../howto/tutorial/listings/finger/finger13.tac | 12 +-
.../howto/tutorial/listings/finger/finger14.tac | 10 +-
.../howto/tutorial/listings/finger/finger15.tac | 21 +-
.../howto/tutorial/listings/finger/finger16.tac | 32 +-
.../howto/tutorial/listings/finger/finger17.tac | 29 +-
.../howto/tutorial/listings/finger/finger18.tac | 12 +-
.../howto/tutorial/listings/finger/finger19.tac | 26 +-
.../howto/tutorial/listings/finger/finger19a.tac | 24 +-
.../tutorial/listings/finger/finger19a_changes.py | 10 +-
.../howto/tutorial/listings/finger/finger19b.tac | 22 +-
.../howto/tutorial/listings/finger/finger19c.tac | 18 +-
.../howto/tutorial/listings/finger/finger20.tac | 16 +-
.../howto/tutorial/listings/finger/finger21.tac | 14 +-
.../howto/tutorial/listings/finger/finger22.py | 20 +-
.../tutorial/listings/finger/fingerXRclient.py | 10 +-
.../howto/tutorial/listings/finger/fingerproxy.tac | 10 +-
docs/fun/Twisted.Quotes | 1 -
docs/historic/Quotes/Twisted-17.5 | 4 +
src/Twisted.egg-info/PKG-INFO | 2 +-
src/Twisted.egg-info/SOURCES.txt | 10 +-
src/Twisted.egg-info/requires.txt | 18 +-
src/twisted/_version.py | 2 +-
src/twisted/application/internet.py | 132 ++-
src/twisted/application/runner/_runner.py | 197 ++--
src/twisted/application/runner/test/mockreactor.py | 40 +
src/twisted/application/runner/test/test_runner.py | 169 ++-
src/twisted/application/service.py | 5 +-
src/twisted/application/test/test_internet.py | 66 ++
src/twisted/application/twist/_twist.py | 42 +-
src/twisted/application/twist/test/test_twist.py | 58 +-
src/twisted/conch/recvline.py | 2 +-
src/twisted/conch/scripts/ckeygen.py | 2 +
src/twisted/conch/ssh/_kex.py | 28 -
src/twisted/conch/ssh/filetransfer.py | 4 +-
src/twisted/conch/ssh/keys.py | 18 -
src/twisted/conch/ssh/transport.py | 2 +-
src/twisted/conch/test/test_conch.py | 46 +-
src/twisted/conch/test/test_openssh_compat.py | 4 +-
src/twisted/conch/test/test_recvline.py | 21 +
src/twisted/conch/test/test_transport.py | 52 +-
src/twisted/internet/_dumbwin32proc.py | 3 +-
src/twisted/internet/_resolver.py | 15 +
src/twisted/internet/_sslverify.py | 2 +
src/twisted/internet/_threadedselect.py | 43 +-
src/twisted/internet/base.py | 2 +-
src/twisted/internet/defer.py | 93 +-
src/twisted/internet/endpoints.py | 141 ++-
src/twisted/internet/process.py | 6 +-
src/twisted/internet/test/test_base.py | 111 +-
src/twisted/internet/test/test_coroutines.py | 9 +-
src/twisted/internet/test/test_endpoints.py | 415 ++++++-
src/twisted/internet/test/test_posixprocess.py | 8 +-
src/twisted/internet/test/test_process.py | 11 +-
src/twisted/internet/test/test_tcp.py | 6 +-
src/twisted/internet/test/test_udp.py | 31 +
src/twisted/internet/test/test_unix.py | 139 ++-
src/twisted/internet/unix.py | 58 +-
src/twisted/internet/wxreactor.py | 10 +-
src/twisted/logger/_global.py | 23 +-
src/twisted/logger/test/test_global.py | 49 +
src/twisted/mail/_cred.py | 1 -
src/twisted/mail/_except.py | 17 +-
src/twisted/mail/protocols.py | 38 +-
src/twisted/mail/smtp.py | 495 +++++---
src/twisted/mail/test/test_imap.py | 16 +-
src/twisted/mail/test/test_mail.py | 65 +-
src/twisted/mail/test/test_smtp.py | 427 +++----
src/twisted/names/dns.py | 10 +-
src/twisted/names/test/test_dns.py | 24 +
src/twisted/persisted/crefutil.py | 6 +-
src/twisted/persisted/sob.py | 70 +-
src/twisted/protocols/finger.py | 20 +-
src/twisted/protocols/ftp.py | 6 +-
src/twisted/protocols/test/test_tls.py | 5 +-
src/twisted/python/__init__.py | 7 +
src/twisted/python/_release.py | 322 +----
src/twisted/python/_setup.py | 30 +-
src/twisted/python/_url.py | 783 +------------
src/twisted/python/compat.py | 13 +
src/twisted/python/deprecate.py | 74 +-
src/twisted/python/failure.py | 15 +-
src/twisted/python/filepath.py | 4 +-
src/twisted/python/rebuild.py | 2 +
src/twisted/python/reflect.py | 7 -
src/twisted/python/release.py | 2 +
src/twisted/python/test/_deprecatetests.py.3only | 56 +
src/twisted/python/test/test_deprecate.py | 74 +-
src/twisted/python/test/test_release.py | 554 +--------
src/twisted/python/test/test_setup.py | 16 +-
src/twisted/python/test/test_url.py | 31 +-
src/twisted/python/test/test_versions.py | 200 ----
src/twisted/python/url.py | 2 +-
src/twisted/python/urlpath.py | 2 +-
src/twisted/python/util.py | 18 +-
src/twisted/runner/inetdconf.py | 47 -
src/twisted/runner/inetdtap.py | 13 -
src/twisted/runner/portmap.c | 57 -
src/twisted/runner/test/test_inetdconf.py | 46 -
src/twisted/runner/test/test_inetdtap.py | 41 -
src/twisted/spread/flavors.py | 5 +
src/twisted/spread/jelly.py | 2 +
src/twisted/spread/pb.py | 6 +-
src/twisted/spread/test/test_pb.py | 34 +-
src/twisted/test/iosim.py | 2 +-
src/twisted/test/proto_helpers.py | 8 +-
src/twisted/test/test_defer.py | 138 ++-
src/twisted/test/test_failure.py | 15 +-
src/twisted/test/test_finger.py | 16 +-
src/twisted/test/test_ftp.py | 16 +-
src/twisted/test/test_iosim.py | 275 ++++-
src/twisted/test/test_log.py | 12 +-
src/twisted/test/test_process.py | 80 +-
src/twisted/test/test_rebuild.py | 2 +-
src/twisted/test/test_reflect.py | 14 -
src/twisted/test/test_sob.py | 135 +--
src/twisted/test/test_ssl.py | 8 +-
src/twisted/test/test_sslverify.py | 2 +-
src/twisted/test/test_stdio.py | 4 +-
src/twisted/test/test_threadpool.py | 9 +-
src/twisted/test/test_threads.py | 8 +-
src/twisted/web/_flatten.py | 2 +-
src/twisted/web/_http2.py | 48 +-
src/twisted/web/_newclient.py | 24 +-
src/twisted/web/client.py | 45 +-
src/twisted/web/distrib.py | 25 +-
src/twisted/web/html.py | 4 +-
src/twisted/web/http.py | 255 +++-
src/twisted/web/microdom.py | 7 +-
src/twisted/web/server.py | 10 +-
src/twisted/web/tap.py | 41 +-
src/twisted/web/test/test_agent.py | 2 +-
src/twisted/web/test/test_cgi.py | 141 ++-
src/twisted/web/test/test_distrib.py | 78 +-
src/twisted/web/test/test_http.py | 320 ++++-
src/twisted/web/test/test_http2.py | 236 ++--
src/twisted/web/test/test_newclient.py | 42 +-
src/twisted/web/test/test_tap.py | 37 +-
src/twisted/web/twcgi.py | 112 +-
src/twisted/words/protocols/irc.py | 12 +-
src/twisted/words/protocols/oscar.py | 1236 --------------------
src/twisted/words/test/test_irc.py | 31 +
src/twisted/words/test/test_oscar.py | 43 -
tox.ini | 10 +-
162 files changed, 4804 insertions(+), 5238 deletions(-)
diff --git a/MANIFEST.in b/MANIFEST.in
index e446c81..4a04f52 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -9,14 +9,15 @@
# Do not include the old topfiles, or news fragments
recursive-exclude src/twisted *.misc *.bugfix *.doc *.feature *.removal
-recursive-exclude src/twisted NEWS README topfiles
+recursive-exclude src/twisted NEWS README newsfragments
exclude src/twisted/topfiles/CREDITS src/twisted/topfiles/ChangeLog.Old
# Include NEWS, READMEs, etc
recursive-include docs README
-include NEWS README.rst INSTALL.rst CONTRIBUTING LICENSE code_of_conduct.md
+include NEWS.rst README.rst INSTALL.rst CONTRIBUTING LICENSE code_of_conduct.md
# Exclude admin scripts and things only useful when running from a source checkout
+exclude pyproject.toml
exclude codecov.yml
exclude appveyor.yml
prune bin
diff --git a/NEWS b/NEWS.rst
similarity index 97%
rename from NEWS
rename to NEWS.rst
index 37bc851..1e94761 100644
--- a/NEWS
+++ b/NEWS.rst
@@ -1,6 +1,190 @@
Ticket numbers in this file can be looked up by visiting
http://twistedmatrix.com/trac/ticket/<number>
+.. towncrier release notes start
+
+Twisted 17.5.0 (2017-06-04)
+===========================
+
+Bugfixes
+--------
+
+- spawnProcess no longer opens an unwanted console on Windows (#5726)
+- The transition to the hyperlink package adds IPv6 support to
+ twisted.python.url.URL. This is now deprecated and new code should use
+ hyperlink directly (see #9126). (#8069)
+- twisted.logger now buffers only 200 events by default (reduced from 65536)
+ while waiting for observers to be configured. (#8164)
+- The transition of twisted.python.url to using the hyperlink package enables a
+ URL.click() with no arguments (or 0-length string argument) to resolve dot
+ segments in the path. (#8184)
+- twisted.protocols.finger now works on Python 3. (#8230)
+- TLS-related tests now pass when run with OpenSSL 1.1.0. This makes tests pass
+ again on macOS and Windows, as cryptography 1.8 and later include OpenSSL
+ 1.1.0. (#8898)
+- UNIX socket endpoints now process all messages from recvmsg's ancillary data
+ via twisted.internet.unix.Server.doRead/twisted.internet.unix.Client.doRead,
+ while discarding and logging ones that don't contain file descriptors.
+ (#8912)
+- twisted.internet.endpoints.HostnameEndpoint and twisted.web.client.Agent work
+ again with reactors that do not provide IReactorPluggableNameResolver. This
+ undoes the changes that broke downstream users such as treq.testing. Note
+ that passing reactors that do not provide IReactorPluggableNameResolver to
+ either is deprecated. (#9032)
+- A Python 3 Perspective Broker server which receives a remote call with
+ keyword arguments from a Python 2 client will now decode any keys which are
+ binary to strings instead of crashing. This fixes interoperability between
+ Python 2 Buildbot clients and Python 3 Buildbot servers. (#9047)
+- twisted.internet._threadedselect now works on both Python 2 and 3. (#9053)
+- twisted.internet.interfaces.IResolverSimple implementers will now always be
+ passed bytes, properly IDNA encoded if required, on Python 2. On Python 3,
+ they will now be passed correctly IDNA-encoded Unicode forms of the domain,
+ taking advantage of the idna library from PyPI if possible. This is to avoid
+ Python's standard library (which has an out of date idna module) from mis-
+ encoding domain names when non-ASCII Unicode is passed to it. (#9137)
+
+
+Improved Documentation
+----------------------
+
+- The examples in Twisted howto "Using the Twisted Application Framework",
+ section "Customizing twistd logging" have been updated to use latest logging
+ modules and syntax (#9084)
+
+
+Features
+--------
+
+- twisted.internet.defer.Deferred.asFuture and
+ twisted.internet.defer.Deferred.fromFuture were added, allowing for easy
+ transitions between asyncio coroutines (which await Futures) and twisted
+ coroutines (which await Deferreds). (#8748)
+- twisted.application.internet.ClientService.whenConnected now accepts an
+ argument "failAfterFailures". If you set this to 1, the Deferred returned by
+ whenConnected will errback when the connection attempt fails, rather than
+ retrying forever. This lets you react (probably by stopping the
+ ClientService) to connection errors that are likely to be persistent, such as
+ using the wrong hostname, or not being connected to the internet at all.
+ (#9116)
+- twisted.protocols.tls.TLSMemoryBIOProtocol and anything that uses it
+ indirectly including the TLS client and server endpoints now enables TLS 1.3
+ cipher suites. (#9128)
+
+
+Misc
+----
+
+- #8133, #8995, #8997, #9003, #9015, #9021, #9026, #9027, #9049, #9057, #9062,
+ #9065, #9069, #9070, #9072, #9074, #9075, #9111, #9117, #9140, #9144, #9145
+
+
+Deprecations and Removals
+-------------------------
+
+- twisted.runner.inetdconf.InvalidRPCServicesConfError,
+ twisted.runner.inetdconf.RPCServicesConf, twisted.runner.inetdtap.RPCServer,
+ and twisted.runner.portmap, deprecated since 16.2.0, have been removed.
+ (#8464)
+- twisted.python.url and twisted.python._url were modified to rely on
+ hyperlink, a new package based on the Twisted URL implementation. Hyperlink
+ adds support for IPv6 (fixing #8069), correct username/password encoding,
+ better scheme/netloc inference, improved URL.click() behavior (fixing #8184),
+ and more. For full docs see hyperlink.readthedocs.io and the CHANGELOG in the
+ hyperlink GitHub repo. (#9126)
+
+
+Conch
+-----
+
+Bugfixes
+~~~~~~~~
+
+- History-aware terminal protocols like twisted.conch.manhole.Manhole no longer
+ raise a TypeError when a user visits a partial line they added to the command
+ line history by pressing up arrow before return. (#9031)
+- The telnet_echo.tac example had conflicting port callouts between runtime and
+ documentation. File was altered to run on documented port, 6023. (#9055)
+
+
+Deprecations and Removals
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Remove diffie-hellman-group1-sha1 from twisted.conch. See https://weakdh.org/
+ (#9019)
+- Removed small and obscure elliptic curves from conch. The only curves conch
+ supports now are the ones also supported by OpenSSH. (#9088)
+
+
+Mail
+----
+
+Bugfixes
+~~~~~~~~
+
+- twisted.mail.smtp has been ported to Python 3. (#8770)
+
+
+Names
+-----
+
+Bugfixes
+~~~~~~~~
+
+- RRHeader now converts its ttl argument to an integer, raising a TypeError if
+ it cannot. (#8340)
+
+
+Web
+---
+
+Bugfixes
+~~~~~~~~
+
+- twisted.web.cgi now works on Python 3 (#8009)
+- twisted.web.distrib now works on Python 3 (#8010)
+- twisted.web.http.HTTPFactory now propagates its reactor's callLater method to
+ the HTTPChannel object, rather than having callLater grab the global reactor.
+ This prevents the possibility of HTTPFactory logging using one reactor, but
+ HTTPChannel running timeouts on another. (#8904)
+
+
+Improved Documentation
+~~~~~~~~~~~~~~~~~~~~~~
+
+- twisted.web.template.flattenString docstring now correctly references
+ io.BytesIO (rather than NativeStringIO). (#9028)
+
+
+Features
+~~~~~~~~
+
+- twisted.web.client now exposes the RequestGenerationFailed exception type.
+ (#5310)
+- twisted.web.client.Agent will now parse responses that begin with a status
+ line that is missing a phrase. (#7673)
+- twisted.web.http.HTTPChannel and twisted.web._http2.H2Connection have been
+ enhanced so that after they time out they wait a small amount of time to
+ allow the connection to close gracefully and, if it does not, they forcibly
+ close it to avoid allowing malicious clients to forcibly keep the connection
+ open. (#8902)
+
+
+Misc
+~~~~
+
+- #8981, #9018, #9067, #9090, #9092, #9093, #9096
+
+
+Words
+-----
+
+Deprecations and Removals
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- twisted.words.protocols.oscar, which is client code for Oscar/ICQ, was
+ deprecated in 16.2.0 and has now been removed. (#9024)
+
+
Twisted Core 17.1.0 (2017-02-04)
================================
@@ -1380,7 +1564,7 @@ Bugfixes
Deprecations and Removals
-------------------------
- - twisted.web.http.Request's headers and request_headers attributes,
+ - twisted.web.http.Request's headers and received_headers attributes,
deprecated since Twisted 13.2, have been removed. (#8136)
- twisted.web.static.addSlash is deprecated. (#8169)
diff --git a/PKG-INFO b/PKG-INFO
index 53a86c1..b7c8598 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,6 +1,6 @@
Metadata-Version: 1.1
Name: Twisted
-Version: 17.1.0
+Version: 17.5.0
Summary: An asynchronous networking framework written in Python
Home-page: http://twistedmatrix.com/
Author: Glyph Lefkowitz
diff --git a/README.rst b/README.rst
index 074ec67..09da0e4 100644
--- a/README.rst
+++ b/README.rst
@@ -1,4 +1,4 @@
-Twisted 17.1.0
+Twisted 17.5.0
==============
|pypi|
@@ -8,9 +8,11 @@ Twisted 17.1.0
.. code::
- <hawkowl> we have always been at war with 16.7
+ <lukasa> Shhh
+ <lukasa> Don't think about it
+ <lukasa> Just let the asynchrony wash over you
-For information on what's new in Twisted 17.1.0, see the `NEWS <NEWS>`_ file that comes with the distribution.
+For information on what's new in Twisted 17.5.0, see the `NEWS <NEWS>`_ file that comes with the distribution.
What is this?
diff --git a/docs/conch/examples/telnet_echo.tac b/docs/conch/examples/telnet_echo.tac
index f765663..67e86c2 100644
--- a/docs/conch/examples/telnet_echo.tac
+++ b/docs/conch/examples/telnet_echo.tac
@@ -41,7 +41,7 @@ class TelnetEcho(TelnetProtocol):
factory = ServerFactory()
factory.protocol = lambda: TelnetTransport(TelnetEcho)
-service = TCPServer(8023, factory)
+service = TCPServer(6023, factory)
application = Application("Telnet Echo Server")
service.setServiceParent(application)
diff --git a/docs/core/development/policy/release-process.rst b/docs/core/development/policy/release-process.rst
index 43a86ee..8a2a272 100644
--- a/docs/core/development/policy/release-process.rst
+++ b/docs/core/development/policy/release-process.rst
@@ -110,13 +110,13 @@ How to do a release candidate
3. In your Git repo, fetch and check out the new release branch.
4. Run ``python -m incremental.update Twisted --rc``
5. Commit the changes made by Incremental.
-6. Run ``./bin/admin/build-news .``
-7. Commit the changes made by build-news - this automatically removes the NEWS topfiles (see #4315)
+6. Run ``towncrier``.
+7. Commit the changes made by towncrier - this automatically removes the NEWS topfiles.
8. Bump copyright dates in ``LICENSE``, ``twisted/copyright.py``, and ``README.rst`` if required
9. Push the changes up to GitHub.
10. Run ``python setup.py sdist --formats=bztar -d /tmp/twisted-release`` to build the tarballs.
-11. Copy ``NEWS`` to ``/tmp/twisted-release/`` as ``NEWS.txt`` for people to view without having to download the tarballs.
- (e.g. ``cp NEWS /tmp/twisted-release/NEWS.txt``)
+11. Copy ``NEWS.rst`` to ``/tmp/twisted-release/`` for people to view without having to download the tarballs.
+ (e.g. ``cp NEWS.rst /tmp/twisted-release/NEWS.rst``)
12. Upload the tarballs to ``twistedmatrix.com/Releases/rc/$RELEASE`` (see #4353)
- You can use ``rsync --rsh=ssh --partial --progress -av /tmp/twisted-release/ t-web at dornkirk.twistedmatrix.com:/srv/t-web/data/releases/rc/<RELEASE>/`` to do this.
@@ -176,7 +176,7 @@ Prepare the branch
1. Have the release branch, previously used to generate a release candidate, checked out
2. Run ``python -m incremental.update Twisted``.
3. Revert the release candidate newsfile changes, in order.
-4. Run ``./bin/admin/build-news .`` to make the final newsfile.
+4. Run ``towncrier`` to make the final newsfile.
5. Add the quote of the release to the ``README.rst``
6. Make a new quote file for the next version
@@ -219,7 +219,7 @@ Update documentation
2. Build the documentation
- - ``./bin/admin/build-news .``
+ - ``./bin/admin/build-docs .``
- ``cp -R doc /tmp/twisted-release/``
3. Run the build-apidocs script to build the API docs and then upload them (See also #2891).
diff --git a/docs/core/howto/application.rst b/docs/core/howto/application.rst
index af3f199..0058442 100644
--- a/docs/core/howto/application.rst
+++ b/docs/core/howto/application.rst
@@ -104,10 +104,10 @@ Given a file named ``my.py`` with the code:
.. code-block:: python
- from twisted.python.log import FileLogObserver
+ from twisted.logger import textFileLogObserver
def logger():
- return FileLogObserver(open("/tmp/my.log", "w")).emit
+ return textFileLogObserver(open("/tmp/my.log", "w"))
Invoking ``twistd --logger my.logger ...`` will log to a file named ``/tmp/my.log`` (this simple example could easily be replaced with use of the ``--logfile`` parameter to twistd).
@@ -120,12 +120,12 @@ Here is an example of how to use :api:`twisted.python.logfile.DailyLogFile <Dail
.. code-block:: python
from twisted.application.service import Application
- from twisted.python.log import ILogObserver, FileLogObserver
+ from twisted.logger import ILogObserver, textFileLogObserver
from twisted.python.logfile import DailyLogFile
application = Application("myapp")
logfile = DailyLogFile("my.log", "/tmp")
- application.setComponent(ILogObserver, FileLogObserver(logfile).emit)
+ application.setComponent(ILogObserver, textFileLogObserver(logfile))
Invoking ``twistd -y my.tac`` will create a log file at ``/tmp/my.log``.
diff --git a/docs/core/howto/endpoints.rst b/docs/core/howto/endpoints.rst
index 586ff93..523e961 100644
--- a/docs/core/howto/endpoints.rst
+++ b/docs/core/howto/endpoints.rst
@@ -152,6 +152,36 @@ Keep in mind that you may need to wrap this up for your particular application,
For example, that little snippet is slightly oversimplified: at the time ``connectedNow`` is run, the bot hasn't authenticated or joined the channel yet, so its message will be refused.
A real-life IRC bot would need to have its own method for waiting until the connection is fully ready for chat before chatting.
+Reporting an Initial Failure
+----------------------------
+
+Often times, a failure of the very first connection attempt is special.
+It may indicate a problem that won't go away by just trying harder.
+The service may be configured with the wrong hostname, or the user may not have an internet connection at all (perhaps they forgot to turn on their wifi adapter).
+
+Applications can ask ``whenConnected`` to make their ``Deferred`` fail if the service makes one or more connection attempts in a row without success.
+You can pass the ``failAfterFailures`` parameter into ``ClientService`` to set this threshold.
+
+By calling ``whenConnected(failAfterFailures=1)`` when the service is first started (just before or just after ``startService``), your application will get notification of an initial connection failure.
+
+Setting it to 1 makes it fail after a single connection failure.
+Setting it to 2 means it will try once, wait a bit, try again, and then either fail or succeed depending upon the outcome of the second connection attempt.
+You can use 3 or more too, if you're feeling particularly patient.
+The default of ``None`` means it will wait forever for a successful connection.
+
+Regardless of ``failAfterFailures``, the ``Deferred`` will always fail with :api:`twisted.internet.defer.CancelledError <CancelledError>` if the service is stopped before a connection is made.
+
+.. code-block:: python
+
+ waitForConnection = myReconnectingService.whenConnected(failAfterFailures=1)
+ def connectedNow(clientForIRC):
+ clientForIRC.say("#bot-test", "hello, world!")
+ def failed(f):
+ print("initial connection failed: %s" % (f,))
+ # now you should stop the service and report the error upwards
+ waitForConnection.addCallbacks(connectedNow, failed)
+
+
Retry Policies
--------------
diff --git a/docs/core/howto/logger.rst b/docs/core/howto/logger.rst
index 8c9e333..945fc9e 100644
--- a/docs/core/howto/logger.rst
+++ b/docs/core/howto/logger.rst
@@ -19,7 +19,7 @@ For example: a web server might emit an event after handling each request that i
All of that information might be contained in a pair of objects representing the request and response, so logging this event could be as simple as:
.. code-block:: python
-
+
log.info(request=request, response=response)
The above API would seem confusing to users of many logging systems, which are built around the idea of emitting strings to a file.
@@ -27,7 +27,7 @@ There is, after all, no string in the above call.
In such systems, one might expect the API to look like this instead:
.. code-block:: python
-
+
log.info(
"{uri}: status={status}, bytes={size}, etc..."
.format(uri=request.uri, status=response.code, size=response.size)
@@ -51,7 +51,7 @@ Events-as-strings do have the advantage that it's obvious what an observer that
We can solve this more flexibly by providing an optional format string in events that can be used for this purpose:
.. code-block:: python
-
+
log.info(
"{request.uri}: status={response.status}, bytes={response.size}, etc...",
request=request, response=response
@@ -69,22 +69,22 @@ The first thing that an application that emits logging events needs to do is to
A :api:`twisted.logger.Logger <Logger>` may be created globally for a module:
.. code-block:: python
-
+
from twisted.logger import Logger
log = Logger()
-
+
def handleData(data):
log.debug("Got data: {data!r}.", data=data)
A :api:`twisted.logger.Logger <Logger>` can also be associated with a class:
.. code-block:: python
-
+
from twisted.logger import Logger
-
+
class Foo(object):
log = Logger()
-
+
def oops(self, data):
self.log.error(
"Oops! Invalid data from server: {data!r}",
@@ -150,28 +150,28 @@ Log levels
These methods all have the same signature, but each will attach a specific ``log_level`` key to events.
Log levels are defined by the :api:`twisted.logger.LogLevel <LogLevel>` constants container.
These are:
-
-:api:`twisted.logger.LogLevel.debug <debug>`
-
+
+:api:`twisted.logger.LogLevel.debug <debug>`
+
Debugging events: Information of use to a developer of the software, not generally of interest to someone running the software unless they are attempting to diagnose a software issue.
-:api:`twisted.logger.LogLevel.info <info>`
-
+:api:`twisted.logger.LogLevel.info <info>`
+
Informational events: Routine information about the status of an application, such as incoming connections, startup of a subsystem, etc.
-:api:`twisted.logger.LogLevel.warn <warn>`
-
+:api:`twisted.logger.LogLevel.warn <warn>`
+
Warning events: Events that may require greater attention than informational events but are not a systemic failure condition, such as authorization failures, bad data from a network client, etc.
Such events are of potential interest to system administrators, and should ideally be phrased in such a way, or documented, so as to indicate an action that an administrator might take to mitigate the warning.
-:api:`twisted.logger.LogLevel.error <error>`
-
+:api:`twisted.logger.LogLevel.error <error>`
+
Error conditions: Events indicating a systemic failure.
For example, resource exhaustion, or the loss of connectivity to an external system, such as a database or API endpoint, without which no useful work can proceed.
Similar to warnings, errors related to operational parameters may be actionable to system administrators and should provide references to resources which an administrator might use to resolve them.
-:api:`twisted.logger.LogLevel.critical <critical>`
-
+:api:`twisted.logger.LogLevel.critical <critical>`
+
Critical failures: Errors indicating systemic failure (ie. service outage), data corruption, imminent data loss, etc. which must be handled immediately.
This includes errors unanticipated by the software, such as unhandled exceptions, wherein the cause and consequences are unknown.
@@ -207,28 +207,28 @@ When writing a format string, take care to present it in a manner which would ma
Particularly, format strings need not be written with an eye towards parseability or machine-readability.
If you want to save your log events along with their structure and then analyze them later, see the next section, on :ref:`"saving events for later" <core-howto-logger-saving-events-for-later>` .
-Format strings should be
+Format strings should be
``unicode`` , and use `PEP 3101 <http://www.python.org/dev/peps/pep-3101/>`_ syntax to describe how the event should be rendered as human-readable text.
For legacy support and convenience in python 2, UTF-8-encoded ``bytes`` are also accepted for format strings, but unicode is preferred.
There are two variations from PEP 3101 in the format strings used by this module:
-#.
+#.
Positional (numerical) field names (eg. ``{0}`` ) are not permitted.
Event keys are not ordered, which means positional field names do not make sense in this context.
However, this is not an accidental limitation, but an intentional design decision.
As software evolves, log messages often grow to include additional information, while still logging the same conceptual event.
By using meaningful names rather than opaque indexes for event keys, these identifiers are more robust against future changes in the format of messages and the information provided.
-#.
+#.
Field names ending in parentheses (eg. ``{foo()}`` ) will call the referenced object with no arguments, then call ``str`` on the result, rather than calling ``str`` on the referenced object directly.
This extension to PEP 3101 format syntax is provided to make it as easy as possible to defer potentially expensive work until a log message must be emitted.
For example, let's say that we wanted to log a message with some useful, but potentially expensive information from the 'request' object:
-
+
.. code-block:: python
-
+
log.info("{request.uri} useful, but expensive: {request.usefulButExpensive()}",
request=request)
-
+
In the case where this log message is filtered out as uninteresting and not saved, no formatting work is done *at all* ; and since we can use PEP3101 attribute-access syntax in conjunction with this parenthesis extension, the caller does not even need to build a function or bound method object to pass as a separate key.
There is no support for specifying arguments in the format string; the goal is to make it idiomatic to express that work be done later, not to implement a full Python expression evaluator.
@@ -241,36 +241,36 @@ All event keys that are inserted by the logging system with have a ``log_`` pref
Applications should therefore not insert event keys using the ``log_`` prefix, as that prefix is reserved for the logging system.
System-provided event keys include:
-``log_logger``
-
+``log_logger``
+
:api:`twisted.logger.Logger <Logger>` object that the event was emitted to.
-``log_source``
-
+``log_source``
+
The source object that emitted the event.
When a :api:`twisted.logger.Logger <Logger>` is accessed as an attribute of a class, the class is the source.
When accessed as an attribute of an instance, the instance is the source.
In other cases, the source is ``None`` .
-``log_level``
-
+``log_level``
+
The :api:`twisted.logger.LogLevel <LogLevel>` associated with the event.
-``log_namespace``
-
+``log_namespace``
+
The namespace associated with the event.
-``log_format``
-
+``log_format``
+
The format string provided for use by observers that wish to render the event as text.
This may be ``None`` , if no format string was provided.
-``log_time``
-
+``log_time``
+
The time that the event was emitted, as returned by :api:`time.time <time>` .
-``log_failure``
-
+``log_failure``
+
A :api:`twisted.python.failure.Failure <Failure>` object captured when the event was emitted.
@@ -309,7 +309,7 @@ You can also, of course, feel free to access any of the keys in the ``event`` ob
.. literalinclude:: listings/logger/loader-math.py
-.. TODO: command-line option for twistd to do this
+.. TODO: command-line option for twistd to do this
Implementing an observer
@@ -319,10 +319,10 @@ An observer must provide the :api:`twisted.logger.ILogObserver <ILogObserver>` i
That interface simply describes a 1-argument callable that takes a ``dict`` , so a simple implementation may simply use the handy :api:`zope.interface.provider <provider>` decorator on a function that takes one argument:
.. code-block:: python
-
+
from zope.interface import provider
from twisted.logger import ILogObserver, formatEvent
-
+
@provider(ILogObserver)
def simpleObserver(event):
print(formatEvent(event))
@@ -339,10 +339,10 @@ Specifically, a log observer:
- must be prepared to be called from threads other than the main thread (or I/O thread, or reactor thread)
- must be prepared to be called from multiple threads concurrently
-- must not interact with other Twisted APIs that are not explicitly thread-safe without first taking precautions like using :api:`twisted.internet.interfaces.IReactorThreads.callFromThread <callFromThread>`
+- must not interact with other Twisted APIs that are not explicitly thread-safe without first taking precautions like using :api:`twisted.internet.interfaces.IReactorFromThreads.callFromThread <callFromThread>`
Keep in mind that this is true even if you elect not to explicitly interact with any threads from your program.
-Twisted itself may log messages from threads, and Twisted may internally use APIs like :api:`twisted.internet.interfaces.IReactorThreads.callInThread <callInThread>` ; for example, Twisted uses threads to look up hostnames when making an outgoing connection.
+Twisted itself may log messages from threads, and Twisted may internally use APIs like :api:`twisted.internet.interfaces.IReactorInThreads.callInThread <callInThread>` ; for example, Twisted uses threads to look up hostnames when making an outgoing connection.
Given this extra wrinkle, it's usually best to see if you can find an existing log observer implementation that does what you need before implementing your own; thread safety can be tricky to implement.
Luckily, :api:`twisted.logger <twisted.logger>` comes with several useful observers, which are documented below.
@@ -417,7 +417,7 @@ Log messages are therefore a stream-of-consciousness commentary on what is going
``extractField`` lets you acknowledge the messy reality of how log messages are written, but still take advantage of structured analysis later on.
Just always be sure to use event format fields, not string concatenation, to reference information about a particular event, and you'll be able to easily pull apart hastily-written ad-hoc messages from multiple versions of a system, either as it's running or once you've saved a log file.
-.. TODO: explain filtering
+.. TODO: explain filtering
Registering an observer
@@ -426,12 +426,12 @@ Registering an observer
One way to register an observer is to construct a :api:`twisted.logger.Logger <Logger>` object with it:
.. code-block:: python
-
+
from twisted.logger import Logger
from myobservers import PrintingObserver
-
+
log = Logger(observer=PrintingObserver())
-
+
log.info("Hello")
This will cause all of a logger's events to be sent to the given observer.
@@ -453,14 +453,14 @@ What this means is that the global log publisher accepts events like any other o
Observers can be registered to be forwarded events by calling the :api:`twisted.logger.LogPublisher <LogPublisher>` method :api:`twisted.logger.LogPublisher.addObserver <addObserver>` , and unregister by calling :api:`twisted.logger.LogPublisher.removeObserver <removeObserver>` :
.. code-block:: python
-
+
from twisted.logger import globalLogPublisher
from myobservers import PrintingObserver
-
+
log = Logger()
-
+
globalLogPublisher.addObserver(PrintingObserver())
-
+
log.info("Hello")
The result here is the same as the previous example, except that additional observers can be (and may already have been) registered.
@@ -484,46 +484,55 @@ When the global log publisher is created, it uses a :api:`twisted.logger.Limited
Logging is started by registering the first set of observers with the global log publisher by calling :api:`twisted.logger.LogBeginner.beginLoggingTo <beginLoggingTo>` :
.. code-block:: python
-
+
from twisted.logger import globalLogBeginner
from myobservers import PrintingObserver
-
+
log = Logger()
-
+
log.info("Hello")
-
+
observers = [PrintingObserver()]
-
+
globalLogBeginner.beginLoggingTo(observers)
-
+
log.info("Hello, again")
-What this does is add the given observers (in this example, the ``PrintingObserver`` ) with the global log observer, then forwards all of the events that were stored in memory prior to calling :api:`twisted.logger.LogBeginner.beginLoggingTo <beginLoggingTo>` to these observers, and gets rid of the :api:`twisted.logger.LimitedHistoryLogObserver <LimitedHistoryLogObserver>` , as it is no longer needed.
+This:
+
+* Adds the given observers (in this example, the ``PrintingObserver`` ) to the global log observer
+* Forwards all of the events that were stored in memory prior to calling :api:`twisted.logger.LogBeginner.beginLoggingTo <beginLoggingTo>` to these observers
+* Gets rid of the :api:`twisted.logger.LimitedHistoryLogObserver <LimitedHistoryLogObserver>` , as it is no longer needed.
+
It is an error to call :api:`twisted.logger.LogBeginner.beginLoggingTo <beginLoggingTo>` more than once.
+.. note:: If the global log publisher is never started, the in-memory event buffer holds (a bounded number of) log events indefinitely.
+ This may unexpectedly increase application memory or CPU usage.
+ It is highly recommended that the global log publisher be started as early as feasible.
+
Provided log observers
----------------------
This module provides a number of pre-built observers for applications to use:
-
-:api:`twisted.logger.LogPublisher <LogPublisher>`
-
+
+:api:`twisted.logger.LogPublisher <LogPublisher>`
+
Forwards events to other publishers.
This allows one to create a graph of observers.
-:api:`twisted.logger.LimitedHistoryLogObserver <LimitedHistoryLogObserver>`
-
+:api:`twisted.logger.LimitedHistoryLogObserver <LimitedHistoryLogObserver>`
+
Stores a limited number of received events, and can re-play those stored events to another observer later.
This is useful for keeping recent logging history in memory for inspection when other log outputs are not available.
-:api:`twisted.logger.FileLogObserver <FileLogObserver>`
-
+:api:`twisted.logger.FileLogObserver <FileLogObserver>`
+
Formats events as text, prefixed with a time stamp and a "system identifier", and writes them to a file.
The system identifier defaults to a combination of the event's namespace and level.
-:api:`twisted.logger.FilteringLogObserver <FilteringLogObserver>`
-
+:api:`twisted.logger.FilteringLogObserver <FilteringLogObserver>`
+
Forwards events to another observer after applying a set of filter predicates (providers of :api:`twisted.logger.ILogFilterPredicate <ILogFilterPredicate>` ).
:api:`twisted.logger.LogLevelFilterPredicate <LogLevelFilterPredicate>` is a predicate that be configured to keep track of which log levels to filter for different namespaces, and will filter out events that are not at the appropriate level or higher.
diff --git a/docs/core/howto/threading.rst b/docs/core/howto/threading.rst
index 8d0108e..19528a5 100644
--- a/docs/core/howto/threading.rst
+++ b/docs/core/howto/threading.rst
@@ -32,7 +32,7 @@ This means that if you start a thread and call a Twisted method, you might get c
So don't do it.
The right way to call methods on the reactor from another thread, and therefore any objects which might call methods on the reactor, is to give a function to the reactor to execute within its own thread.
-This can be done using the function :api:`twisted.internet.interfaces.IReactorThreads.callFromThread <callFromThread>`::
+This can be done using the function :api:`twisted.internet.interfaces.IReactorFromThreads.callFromThread <callFromThread>`::
from twisted.internet import reactor
def notThreadSafe(someProtocol, message):
@@ -53,7 +53,7 @@ Running Code In Threads
-----------------------
Sometimes we may want to run code in a non-reactor thread, to avoid blocking the reactor.
-Twisted provides an API for doing so, the :api:`twisted.internet.interfaces.IReactorThreads.callInThread <callInThread>` method on the reactor.
+Twisted provides an API for doing so, the :api:`twisted.internet.interfaces.IReactorInThreads.callInThread <callInThread>` method on the reactor.
For example, to run a method in a non-reactor thread we can do::
diff --git a/docs/core/howto/tutorial/listings/finger/finger/finger.py b/docs/core/howto/tutorial/listings/finger/finger/finger.py
index 61e1738..c084217 100755
--- a/docs/core/howto/tutorial/listings/finger/finger/finger.py
+++ b/docs/core/howto/tutorial/listings/finger/finger/finger.py
@@ -14,12 +14,12 @@ class IFingerService(Interface):
def getUser(user):
"""
- Return a deferred returning a string.
+ Return a deferred returning a L{bytes}.
"""
def getUsers():
"""
- Return a deferred returning a list of strings.
+ Return a deferred returning a L{list} of L{bytes}.
"""
@@ -41,7 +41,7 @@ class FingerProtocol(basic.LineReceiver):
d = self.factory.getUser(user)
d.addErrback(catchError)
def writeValue(value):
- self.transport.write(value+'\n')
+ self.transport.write(value + b'\n')
self.transport.loseConnection()
d.addCallback(writeValue)
@@ -50,12 +50,12 @@ class IFingerFactory(Interface):
def getUser(user):
"""
- Return a deferred returning a string.
+ Return a deferred returning L{bytes}.
"""
def buildProtocol(addr):
"""
- Return a protocol returning a string.
+ Return a protocol returning L{bytes}.
"""
@@ -92,12 +92,12 @@ class IFingerSetterFactory(Interface):
def setUser(user, status):
"""
- Return a deferred returning a string.
+ Return a deferred returning L{bytes}.
"""
def buildProtocol(addr):
"""
- Return a protocol returning a string.
+ Return a protocol returning L{bytes}.
"""
@@ -141,7 +141,7 @@ class IIRCClientFactory(Interface):
def getUser(user):
"""
- Return a deferred returning a string.
+ Return a deferred returning L{bytes}.
"""
def buildProtocol(addr):
@@ -284,16 +284,16 @@ class FingerService(service.Service):
def _read(self):
self.users = {}
- with open(self.filename) as f:
+ with open(self.filename, "rb") as f:
for line in f:
- user, status = line.split(':', 1)
+ user, status = line.split(b':', 1)
user = user.strip()
status = status.strip()
self.users[user] = status
self.call = reactor.callLater(30, self._read)
... 16725 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/twisted.git
More information about the Python-modules-commits
mailing list