1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
++++++++++++++++++
Trollius and Tulip
++++++++++++++++++
Differences between Trollius and Tulip
======================================
Syntax of coroutines
--------------------
The major difference between Trollius and Tulip is the syntax of coroutines:
================== ======================
Tulip Trollius
================== ======================
``yield from ...`` ``yield From(...)``
``yield from []`` ``yield From(None)``
``return`` ``raise Return()``
``return x`` ``raise Return(x)``
``return x, y`` ``raise Return(x, y)``
================== ======================
Because of this major difference, it was decided to call the module
``trollius`` instead of ``asyncio``. This choice also allows to use Trollius on
Python 3.4 and later. Changing imports is not enough to use Trollius code with
asyncio: the asyncio event loop explicit rejects coroutines using ``yield``
(instead of ``yield from``).
OSError and socket.error exceptions
-----------------------------------
The ``OSError`` exception changed in Python 3.3: there are now subclasses like
``ConnectionResetError`` or ``BlockingIOError``. The exception hierarchy also
changed: ``socket.error`` is now an alias to ``OSError``. The ``asyncio``
module is written for Python 3.3 and newer and so is based on these new
exceptions.
.. seealso::
`PEP 3151: Reworking the OS and IO exception hierarchy
<https://www.python.org/dev/peps/pep-3151>`_.
On Python 3.2 and older, Trollius wraps ``OSError``, ``IOError``,
``socket.error`` and ``select.error`` exceptions on operating system and socket
operations to raise more specific exceptions, subclasses of ``OSError``:
* ``trollius.BlockingIOError``
* ``trollius.BrokenPipeError``
* ``trollius.ChildProcessError``
* ``trollius.ConnectionAbortedError``
* ``trollius.ConnectionRefusedError``
* ``trollius.ConnectionResetError``
* ``trollius.FileNotFoundError``
* ``trollius.InterruptedError``
* ``trollius.PermissionError``
On Python 3.3 and newer, these symbols are just aliases to builtin exceptions.
.. note::
``ssl.SSLError`` exceptions are not wrapped to ``OSError``, even if
``ssl.SSLError`` is a subclass of ``socket.error``.
SSLError
--------
On Python 3.2 and older, Trollius wraps ``ssl.SSLError`` exceptions to raise
more specific exceptions, subclasses of ``ssl.SSLError``, to mimic the Python
3.3:
* ``trollius.SSLEOFError``
* ``trollius.SSLWantReadError``
* ``trollius.SSLWantWriteError``
On Python 3.3 and newer, these symbols are just aliases to exceptions of the
``ssl`` module.
``trollius.BACKPORT_SSL_ERRORS`` constant:
* ``True`` if ``ssl.SSLError`` are wrapped to Trollius exceptions,
* ``False`` is trollius SSL exceptions are just aliases.
SSLContext
----------
Python 3.3 has a new ``ssl.SSLContext`` class: see the `documentaton of the
ssl.SSLContext class
<https://docs.python.org/3/library/ssl.html#ssl.SSLContext>`_.
On Python 3.2 and older, Trollius has a basic ``trollius.SSLContext`` class to
mimic Python 3.3 API, but it only has a few features:
* ``protocol``, ``certfile`` and ``keyfile`` attributes
* read-only ``verify_mode`` attribute: its value is ``CERT_NONE``
* ``load_cert_chain(certfile, keyfile)`` method
* ``wrap_socket(sock, **kw)`` method: see the ``ssl.wrap_socket()``
documentation of your Python version for the keyword parameters
Example of missing features:
* no ``options`` attribute
* the ``verify_mode`` attriubte cannot be modified
* no ``set_default_verify_paths()`` method
* no "Server Name Indication" (SNI) support
* etc.
On Python 3.2 and older, the trollius SSL transport does not have the
``'compression'`` extra info.
``trollius.BACKPORT_SSL_CONTEXT`` constant:
* ``True`` if ``trollius.SSLContext`` is the backported class,
* ``False`` if ``trollius.SSLContext`` is just an alias to ``ssl.SSLContext``.
Other differences
-----------------
* Trollius uses the ``TROLLIUSDEBUG`` envrionment variable instead of
the ``PYTHONASYNCIODEBUG`` envrionment variable. ``TROLLIUSDEBUG`` variable
is used even if the Python command line option ``-E`` is used.
* ``asyncio.subprocess`` has no ``DEVNULL`` constant
* Python 2 does not support keyword-only parameters.
* If the ``concurrent.futures`` module is missing,
``BaseEventLoop.run_in_executor()`` uses a synchronous executor instead of a
pool of threads. It blocks until the function returns. For example, DNS
resolutions are blocking in this case.
* Trollius has more symbols than Tulip for compatibility with Python older than
3.3:
- ``From``: part of ``yield From(...)`` syntax
- ``Return``: part of ``raise Return(...)`` syntax
Write code working on Trollius and Tulip
========================================
Trollius and Tulip are different, especially for coroutines (``yield
From(...)`` vs ``yield from ...``).
To use asyncio or Trollius on Python 2 and Python 3, add the following code at
the top of your file::
try:
# Use builtin asyncio on Python 3.4+, or Tulip on Python 3.3
import asyncio
except ImportError:
# Use Trollius on Python <= 3.2
import trollius as asyncio
It is possible to write code working on both projects using only callbacks.
This option is used by the following projects which work on Trollius and Tulip:
* `AutobahnPython <https://github.com/tavendo/AutobahnPython>`_: WebSocket &
WAMP for Python, it works on Trollius (Python 2.6 and 2.7), Tulip (Python
3.3) and Python 3.4 (asyncio), and also on Twisted.
* `Pulsar <http://pythonhosted.org/pulsar/>`_: Event driven concurrent
framework for Python. With pulsar you can write asynchronous servers
performing one or several activities in different threads and/or processes.
Trollius 0.3 requires Pulsar 0.8.2 or later. Pulsar uses the ``asyncio``
module if available, or import ``trollius``.
* `Tornado <http://www.tornadoweb.org/>`_ supports Tulip and Trollius since
Tornado 3.2: `tornado.platform.asyncio — Bridge between asyncio and Tornado
<http://tornado.readthedocs.org/en/latest/asyncio.html>`_. It tries to import
asyncio or fallback on importing trollius.
Another option is to provide functions returning ``Future`` objects, so the
caller can decide to use callback using ``fut.add_done_callback(callback)`` or
to use coroutines (``yield From(fut)`` for Trollius, or ``yield from fut`` for
Tulip). This option is used by the `aiodns <https://github.com/saghul/aiodns>`_
project for example.
Since Trollius 0.4, it's possible to use Tulip and Trollius coroutines in the
same process. The only limit is that the event loop must be a Trollius event
loop.
.. note::
The Trollius module was called ``asyncio`` in Trollius version 0.2. The
module name changed to ``trollius`` to support Python 3.4.
|
