From 66f8828bfce4a05cb5e27ed89bba46cdfc64f995 Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Wed, 24 Jun 2015 11:04:15 -0400 Subject: [PATCH] Issue #24439: Improve PEP 492 related docs. Patch by Martin Panter. --- Doc/glossary.rst | 21 ++++---- Doc/library/asyncio-task.rst | 86 +++++++++++++++++++------------ Doc/library/collections.abc.rst | 19 +++---- Doc/library/dis.rst | 8 +-- Doc/library/exceptions.rst | 6 ++- Doc/library/sys.rst | 5 +- Doc/library/tulip_coro.png | Bin 45565 -> 45021 bytes Doc/library/types.rst | 20 ++++--- Doc/reference/compound_stmts.rst | 25 +++++---- Doc/reference/datamodel.rst | 73 ++++++++++++++++++++++---- Doc/reference/expressions.rst | 1 + Objects/genobject.c | 10 ++-- 12 files changed, 184 insertions(+), 90 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index bdbb272051d0..d00185e386f0 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -169,18 +169,19 @@ Glossary statement by defining :meth:`__enter__` and :meth:`__exit__` methods. See :pep:`343`. - coroutine function - A function which returns a :term:`coroutine` object. It is defined - with an :keyword:`async def` keyword, and may contain :keyword:`await`, - :keyword:`async for`, and :keyword:`async with` keywords. Introduced - by :pep:`492`. - coroutine Coroutines is a more generalized form of subroutines. Subroutines are - entered at one point and exited at another point. Coroutines, can be - entered, exited, and resumed at many different points. See - :keyword:`await` expressions, and :keyword:`async for` and - :keyword:`async with` statements. See also :pep:`492`. + entered at one point and exited at another point. Coroutines can be + entered, exited, and resumed at many different points. They can be + implemented with the :keyword:`async def` statement. See also + :pep:`492`. + + coroutine function + A function which returns a :term:`coroutine` object. A coroutine + function may be defined with the :keyword:`async def` statement, + and may contain :keyword:`await`, :keyword:`async for`, and + :keyword:`async with` keywords. These were introduced + by :pep:`492`. CPython The canonical implementation of the Python programming language, as diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index e7ff7d2e2d4e..fa9e96a3dc67 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -8,17 +8,23 @@ Tasks and coroutines Coroutines ---------- -A coroutine is a generator that follows certain conventions. For -documentation purposes, all coroutines should be decorated with -``@asyncio.coroutine``, but this cannot be strictly enforced. - -Coroutines use the ``yield from`` syntax introduced in :pep:`380`, +Coroutines used with :mod:`asyncio` may be implemented using the +:keyword:`async def` statement, or by using :term:`generators `. +The :keyword:`async def` type of coroutine was added in Python 3.5, and +is recommended if there is no need to support older Python versions. + +Generator-based coroutines should be decorated with :func:`@asyncio.coroutine +`, although this is not strictly enforced. +The decorator enables compatibility with :keyword:`async def` coroutines, +and also serves as documentation. Generator-based +coroutines use the ``yield from`` syntax introduced in :pep:`380`, instead of the original ``yield`` syntax. The word "coroutine", like the word "generator", is used for two different (though related) concepts: -- The function that defines a coroutine (a function definition +- The function that defines a coroutine + (a function definition using :keyword:`async def` or decorated with ``@asyncio.coroutine``). If disambiguation is needed we will call this a *coroutine function* (:func:`iscoroutinefunction` returns ``True``). @@ -30,27 +36,28 @@ different (though related) concepts: Things a coroutine can do: -- ``result = yield from future`` -- suspends the coroutine until the +- ``result = await future`` or ``result = yield from future`` -- + suspends the coroutine until the future is done, then returns the future's result, or raises an exception, which will be propagated. (If the future is cancelled, it will raise a ``CancelledError`` exception.) Note that tasks are futures, and everything said about futures also applies to tasks. -- ``result = yield from coroutine`` -- wait for another coroutine to +- ``result = await coroutine`` or ``result = yield from coroutine`` -- + wait for another coroutine to produce a result (or raise an exception, which will be propagated). The ``coroutine`` expression must be a *call* to another coroutine. - ``return expression`` -- produce a result to the coroutine that is - waiting for this one using ``yield from``. + waiting for this one using :keyword:`await` or ``yield from``. - ``raise exception`` -- raise an exception in the coroutine that is - waiting for this one using ``yield from``. + waiting for this one using :keyword:`await` or ``yield from``. -Calling a coroutine does not start its code running -- it is just a -generator, and the coroutine object returned by the call is really a -generator object, which doesn't do anything until you iterate over it. -In the case of a coroutine object, there are two basic ways to start -it running: call ``yield from coroutine`` from another coroutine +Calling a coroutine does not start its code running -- +the coroutine object returned by the call doesn't do anything until you +schedule its execution. There are two basic ways to start it running: +call ``await coroutine`` or ``yield from coroutine`` from another coroutine (assuming the other coroutine is already running!), or schedule its execution using the :func:`async` function or the :meth:`BaseEventLoop.create_task` method. @@ -60,9 +67,15 @@ Coroutines (and tasks) can only run when the event loop is running. .. decorator:: coroutine - Decorator to mark coroutines. + Decorator to mark generator-based coroutines. This enables + the generator use :keyword:`!yield from` to call :keyword:`async + def` coroutines, and also enables the generator to be called by + :keyword:`async def` coroutines, for instance using an + :keyword:`await` expression. + + There is no need to decorate :keyword:`async def` coroutines themselves. - If the coroutine is not yielded from before it is destroyed, an error + If the generator is not yielded from before it is destroyed, an error message is logged. See :ref:`Detect coroutines never scheduled `. @@ -84,8 +97,7 @@ Example of coroutine displaying ``"Hello World"``:: import asyncio - @asyncio.coroutine - def hello_world(): + async def hello_world(): print("Hello World!") loop = asyncio.get_event_loop() @@ -111,20 +123,30 @@ using the :meth:`sleep` function:: import asyncio import datetime - @asyncio.coroutine - def display_date(loop): + async def display_date(loop): end_time = loop.time() + 5.0 while True: print(datetime.datetime.now()) if (loop.time() + 1.0) >= end_time: break - yield from asyncio.sleep(1) + await asyncio.sleep(1) loop = asyncio.get_event_loop() # Blocking call which returns when the display_date() coroutine is done loop.run_until_complete(display_date(loop)) loop.close() +The same coroutine implemented using a generator:: + + @asyncio.coroutine + def display_date(loop): + end_time = loop.time() + 5.0 + while True: + print(datetime.datetime.now()) + if (loop.time() + 1.0) >= end_time: + break + yield from asyncio.sleep(1) + .. seealso:: The :ref:`display the current date with call_later() @@ -139,15 +161,13 @@ Example chaining coroutines:: import asyncio - @asyncio.coroutine - def compute(x, y): + async def compute(x, y): print("Compute %s + %s ..." % (x, y)) - yield from asyncio.sleep(1.0) + await asyncio.sleep(1.0) return x + y - @asyncio.coroutine - def print_sum(x, y): - result = yield from compute(x, y) + async def print_sum(x, y): + result = await compute(x, y) print("%s + %s = %s" % (x, y, result)) loop = asyncio.get_event_loop() @@ -550,12 +570,14 @@ Task functions .. function:: iscoroutine(obj) - Return ``True`` if *obj* is a :ref:`coroutine object `. + Return ``True`` if *obj* is a :ref:`coroutine object `, + which may be based on a generator or an :keyword:`async def` coroutine. -.. function:: iscoroutinefunction(obj) +.. function:: iscoroutinefunction(func) - Return ``True`` if *func* is a decorated :ref:`coroutine function - `. + Return ``True`` if *func* is determined to be a :ref:`coroutine function + `, which may be a decorated generator function or an + :keyword:`async def` function. .. coroutinefunction:: sleep(delay, result=None, \*, loop=None) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index 8c710ef38075..0653d4e35c86 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -154,21 +154,22 @@ ABC Inherits from Abstract Methods Mixin .. class:: Awaitable - ABC for classes that provide ``__await__`` method. Instances - of such classes can be used in ``await`` expression. + ABC for :term:`awaitable` objects, which can be used in :keyword:`await` + expressions. Custom implementations must provide the :meth:`__await__` + method. - :term:`coroutine` objects and instances of - :class:`~collections.abc.Coroutine` are too instances of this ABC. + :term:`Coroutine` objects and instances of the + :class:`~collections.abc.Coroutine` ABC are all instances of this ABC. .. versionadded:: 3.5 .. class:: Coroutine - ABC for coroutine compatible classes that implement a subset of - generator methods defined in :pep:`342`, namely: - :meth:`~generator.send`, :meth:`~generator.throw`, - :meth:`~generator.close` methods. :meth:`__await__` must also be - implemented. All :class:`Coroutine` instances are also instances of + ABC for coroutine compatible classes. These implement the + following methods, defined in :ref:`coroutine-objects`: + :meth:`~coroutine.send`, :meth:`~coroutine.throw`, and + :meth:`~coroutine.close`. Custom implementations must also implement + :meth:`__await__`. All :class:`Coroutine` instances are also instances of :class:`Awaitable`. See also the definition of :term:`coroutine`. .. versionadded:: 3.5 diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 836c4c1ef7ce..7a214edcc789 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -516,12 +516,14 @@ the original TOS1. Implements ``del TOS1[TOS]``. -**Coroutines opcodes** +**Coroutine opcodes** .. opcode:: GET_AWAITABLE - Implements ``TOS = get_awaitable(TOS)``; where ``get_awaitable(o)`` - returns ``o`` if ``o`` is a coroutine object; or resolved ``o.__await__``. + Implements ``TOS = get_awaitable(TOS)``, where ``get_awaitable(o)`` + returns ``o`` if ``o`` is a coroutine object or a generator object with + the CO_ITERABLE_COROUTINE flag, or resolves + ``o.__await__``. .. opcode:: GET_AITER diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 2209f167ea37..1a9d0299d5fd 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -162,7 +162,8 @@ The following exceptions are the exceptions that are usually raised. .. exception:: GeneratorExit - Raised when a :term:`generator`\'s :meth:`close` method is called. It + Raised when a :term:`generator` or :term:`coroutine` is closed; + see :meth:`generator.close` and :meth:`coroutine.close`. It directly inherits from :exc:`BaseException` instead of :exc:`Exception` since it is technically not an error. @@ -306,7 +307,8 @@ The following exceptions are the exceptions that are usually raised. given as an argument when constructing the exception, and defaults to :const:`None`. - When a generator function returns, a new :exc:`StopIteration` instance is + When a :term:`generator` or :term:`coroutine` function + returns, a new :exc:`StopIteration` instance is raised, and the value returned by the function is used as the :attr:`value` parameter to the constructor of the exception. diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 144c986ab19a..545e6742c135 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1080,7 +1080,7 @@ always available. :func:`types.coroutine` or :func:`asyncio.coroutine` will not be intercepted). - *wrapper* must be either: + The *wrapper* argument must be either: * a callable that accepts one argument (a coroutine object); * ``None``, to reset the wrapper. @@ -1096,7 +1096,8 @@ always available. return wrap(coro) sys.set_coroutine_wrapper(wrapper) - async def foo(): pass + async def foo(): + pass # The following line will fail with a RuntimeError, because # `wrapper` creates a `wrap(coro)` coroutine: diff --git a/Doc/library/tulip_coro.png b/Doc/library/tulip_coro.png index 65b6951550e1e5313bdfad671ff6fd5538f24f1a..36ced8ddbfd91da7ac5cc1cba217c1ab185f9f05 100644 GIT binary patch literal 45021 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 literal 45565 zc-q9f1yq&qw&=YCX$1*sM3;1TNU1D9Iv2g@?p!p8AS_zCK|w%Tx+Tb3V^}=KRetNI_2GF(xS{2n2d8`3|B40zISwfsh`c zBLROx`kj6j_<`*BR#F8W9erj=eh~zE4w8htQE^S#o^#P7n5+@GG7TxOo6er6R(Xww z{^^_e`xmH2Ou>eR$y93{#bo{1aJ*acl&#t1S#7dTdidF$hCKgI zAdCn3^D`D9sx$K<;-rOeHLb6(!k*J3oZdcu(*ctH?KIPYM3V3+D?qNhUwexewMh3* zY;iAs{q<+8Z@V7cKj`>>LcV{fM}L8K|KN)I7W@8TAM8(l|F9^A&VT>V9P-5B{^32* zKQGjFYNT)L?@`J{>^;bHQHyFrsuno=?Q$#BZe??kWX8@S^Z_5G1XhX-n>z98fBy2X z;UH*1-?$DvVf|OT^kPdkBg3;#WXL|LxHgX{1r5pM!q_p^SGxR19|t_j{GUkme@(sr zrG-3o)!rk_R-|K*3#Si~&z1_hKeNjcGgnXyl9O8%e7U8t7i@mru~TBdZzS<1_oST` zJVnjAQ;?oW_}$=3Utk3iv4>sJk1l^jYzdx5l?^GJr=aE;@#D!zP0LrF;%@7Yf>v8T zCPvMAW{F$=ffjX}fnX2ZMP{NM+n?04U5p#zk0jqH}mVa<;+yhirF_O@>W+q^Ab{9{}( zWpo0a19jk~Sh7WheOAOq({V2@%6rqadU!1-vNnCPpc8t#rqbDse7JT*YtGf;uFYJ3)ywFdN*Xs6w)4VWPkmQZm=!a(se`OdhqzR&(n&z z;OX7u@wtd=Hlruqh~Iu*h39JSO2A4dYtAZT&LR~&ePpqeYBzu0AYaxfTQ@3X)VP;z zwbQ;7MZT1a^K#p{l&71zg?|f;FS2BTP5#_Lg6GN3h*;J_Gx0ARCyFsrUkx*&5kKN2 zl5ak3vZ--`tw{OKpS^O}dhOgUa$1qXvT5$@oOxrbTP}EuzSl)!{3bU}Lw&*E=lR~6 zo*P7|;C;U{Y*-A!zBFMkfZHB$$&NAf_`{Fx{=KV1v*eo7Y2ZXzYQHeoelf;znDl{~ zf0y8Eoe}9Nalx>d zyUEHux9TK)+2^|-f)R0ZFJK&Mq;yNp&dIi_Ta5w>=31K8%BM5wToq2lqQ9=vulbl> z^$oB-2o(oxIO{2ljPg-x6deI(N}s`T$7JLdT3!gt!jQ0=&pY?hcln&xTd%jqwO~G% z^;2dXWmvavpLeF2ca}I)lPNd1KF#G#;3}$oOZ7|FP}j*NbBfgyWXvC9Kj^48U(RyO z!hPYH8Dyin6`s1q-!*pu&HC|d=~2WL9gb6W-Oq*}HK;GAepko8eBG8DNvOv&nwZgO z`4sRheI`9JPf-x=;w*{jBeZ)ssoeap@tTj0R;b!BCl)BBASfp+TsOaWo2QhKko;$d zUf%$R67)`SawqJ9lZe%kuqS>Xwuefv#y?(2zE)6L972mVzDr|RpiXBP)lF3oNXCz~ zYK6f@pyiF1md1pKQSI%Wf)RNmKT9M9nY3}4%9fEPK$Ub8d?vxPESFB@ezIhj|B#xu zqIlQBY=ezP{IY4^_2F_@Nn1O3Y$DKuL1Et6)#AXK;-5uEsukiM50YuJMC&`?)qJhP@`usGX+n?@zv zqq{ix_=!V~?6$z)x2^bw?r(dBPP%I6d2I7Wy!jmOIJb8*1;qh7u+PLmT!cuyFAum{ zFEb`@rd~s~DU|wLEkhbc`y57)I5l)fjY$m{xAO}2XfoWCFJYTqJx?eFrxc+JJ2o60 z6w2+_w`AX0iyKC0NUFDLGq!$D$%(H+&VjP7(6am%q#v`qDOt- zyjz@KWiJHcVBTcw`y3#KrsKO5A>9&gq-tQG;-l`5c>M!Dyfe>G18zD8BX+Sd zu?_{4zZTj2ZdA;zQ_L0ctTpVFZ&6;pd|bg9xZGC`Y9lj@2%-I~y}kLal(#WlTTlUJ zsv-F-f^+C?-9i<_1iXd+V>@e4o0xJ8W&*~1Ol}97D%6FNPUG&5QyTNu@d6=~ij?~W zT3~N?&yziodHXzt*rexzUK(PMBTlL~oK*BD4p7pSUU`W?)UX10kiT}t#MrQTd4YOe z&pQY>BzYPp(_zO>Qf++Oja`;V*dN1GCrZk+etE$Es^L6QEx#bjz9z-kg&JC=C(IX)II9kyphGxQEfX#FCcH64fDnzcoW9k^!tXRCv{{S04mUMym6uzA%1 z@y?cbv%fiI8Dws?j#S{B+=)L3(j|*-6^76dLhr+C|U~6|I@v*q0 zXvhu3cXJ%}82Rbed+iqLj4Q@Xo9j;*;V6j);8#wiE5B>xvU8xC-klVag2B4=K=g;FjQ|TgB zd|CzO%A_(hWlF|^4&ss!Pmi)3?|MPAVVR&QnOni3i|da+MCj4Qla@ptpdC2>>hVo_ zvMLWrr!cp+;Wcy44w>Xie`bDa)t~6C?^Tv+qW~-OMMSL#&Yt_(8%zn31d0L<^Y+wP z8tPS5H1l~;= zmtbn0eFgZ?dW|(LrV1^lpq(N=C--9AQR?lhp`H@~iiH(n1^hL+r@AboI@NjS+wW#f zC8mEu9dm-27wCQ&aCG!>4bukB2=mXzGrbh!qNRAz`DvD4`EYgkL^LO+uNVclKbd8K zwbc7N1}F2p#S)$e>)DFk@1+#IvP3z8Z^Ad({d#Py$+Sn}{rU-yZ!v!FPU6}Z;Fe~<|>MOy{@NuWGqKItD$TCL(dn<0F~Y0%!#LpvsFo$n^*i)ooV z=W1iy0_;pR$N8@ya!vT!f|J{68!Yg@BZOMtJFF)m(_@;^>TUfpWk*p3K#aj(c_=Z+ zV5{QH2t~z?$0z*FORbT>?ZpQ3<(5Wr(`H~AuXH9wt9~&8m7gc#px1HTblAgE5WOPo z`^1!_4`U>X#vQ(`dPT+6#oF|4{0j%F)VT&pl*d{xUv;dZSzLcKZlIjDQU#nC*|@%7 zBkC#E*UA^26P;i=!aQkPmkMXn_O~`h-xhF8qzmSiyO-_E=7RO26Xl-f3Ex&W%)DkK z1aA@_2i!g+Z<~x{MB5w-$^c@mkX>nJ$@p`8N1}mGMe1}%R$c7;io|rQu%@}=R?4nI zRajltwrBTSZIR!3Na^hc8yg23x1)wGVST)H#xx`Xt6&KBx_Fw``z3V@uivQpNYf zW>XYOK0X8IH>Z6w4fpvEFyzd7%z^2Cc`>jdP06|ptkmP zzCa6iB{t#v1uV7?3MJ>Gd>~FVEB)~QMGpGU3mr5lSu6<`6JW7DA$MRi<8uXxW2Z!b z3<<>fXTRI~1Qh3k8UtHF;#lPQAYp&}C(U?&Uo}Fmz`b%fIxFn;Wm%^;nFLY#6~7&E z=;M{82!!EN@ep>m&&v-Vet)m{KhbA7q2EMz@-Lk_m_q-L^_~6BE-*6*1ueAdgECRV zp&-f@40Jt=|Fu1GO_R%+t@Anh(%SS#MG>v(oIld-cUFz@-c7&9sqM41Fzf-kJchfM z`2ZXFhRNbn?Q*-ORTWVp9n(V!j*>JC(5V(vO!*RzdS7C>I%_Oy{x&(E{T!Ug6bBpm zQc$VMVfKuv2XWW)Vzq{_V#`N=lwyz z?KRzsfxl}MH#PxNqC0%`DzDE7FXUwuo_90BmTRG0j$le%Z10k6imQv4S7c@WxD`)e zplqV>j=qmi$+-Bjd;gc#!GrS;PfxEZOoQHNY1S4O-IU7Z5MZvd4?EJx)z3t*mL^B` zF12^Ee#>Y5y{n3bLerO8cAorl@bVnx7t<|PbU~fgaew6c^;t%WhmK*X9pCI&Ol+8} z8u#X!O@k&~Oip$|a7b!r9KQlmeqODTX7@O&#TKRvjUNOL_i3VrCj9mDPt1ef&QJb2 zyK1CNaz7$mcI%1IPFBKtRy-6_Rflj6{*B+MW6en_e_|3_(iFJEO@COHrDAFB9;q4{yuh>6ZxSc*O z#$xgLwqqfm7_;KatQ_8LRgllx*XIhM31ewW)Y7a>?_C{CIY<~6=blyt;{|<~q81aY zv$SCCOFy-;+lOS8W*1y3cqD_FtV-uXY04Bc%{4w9r$F%J+RV*s-awQjjdVF=v2cTs z-u`4VDa*~>aPKI0#*>6dTb^%l784QqbUefe$5)4r+Z#l8C-|Hc%0cI5r;`0X;B9V( zU}Cyx?CRXxFY0VBJC%hj=kZ=yk_>8WUK)aflM>^x3DCk@6dEQ)0Vg?_1xD25zgqwT)X>ffPVnca!67!>jNTZp!4w@ zqVFLyOT16#Y&r@G&A#hRx1@B?x03FG?8HycUlX*jm|HQu0M`hn^{%3!$|VSRL|fPY zFd;zyT4q`p{|=mRDgO%U455mI98-^0K2ZeWJD6!Ax(4M1T?S}!xq@4lf{|Mgh(RLF zzYhPEoHjIdVWQ}rlr|}8QqKy8f#Dj&U!Iz>U+eDD6N|9*+$oEX+im3K5}dDc3~Vgb zBTOt=!#F4S1a71XsTkzx)6Sr88HYw1QPLP!^c->xp|K6>yADx+L;!pz* zC#NxloN)>3HnVJR7tn%p$J}H5g76cV6eCHt$2g2lAJ^5T(0tF!TWJdp76b=}r*%)X znT_B_YCkibA-q2;0)KMR3`JhW+dyS!I!go{8=Ehz#h)BclBy1V+~dMWzP=(&acv4^ zfB96&oGbbDl!i3KK_e76gtojc#3Oj2<{XggB&N>82is^v6vO*AwlFb8#^4oD=(-y4 zQB6xqKMwKbkYZX>P~4*n95aX!EwuT1lSyv%{>`;Z{OChfsB=ofc^`HV@go>B^QwOk z^xmfi1VKed1bT)iO`#`(hItFsXvZghi5?Xd(>!XJY9~J0PaRj&3=hg@50fPjboBN? zD;3+?tY7F5FfC~6;95mS3CSw@V_B`rKdWL`x(Nv>vJIkWMMhNM*gV@$frvg6e9q*M zAbj^yb${Ntx?XdneCAhj+v}5i-lvDjH8jy_okv6=FSmK_FSsBQK!LxHNjF7=f;Pgn z2F5oU5?@3ifUAqAI2DGBDyrsEm6v_e(*EHTjUk0TI7}xYP!+~HR}4V!tJT=$K~gel zJpA3@phV#2a=r;c1c!+1sEjAeTx=#C1qZJzEp5b=g{rIaz9Z1N*{=i_OHZ;yw+94f zDc=s`p^=cF`h_DlH?d@Cywub#W0&PCrd2mZdR~+wlwLuPjW~PQ6_Dyq9UjFboHm~mgI;@^5o8V** zT>OEPgk7bN+4-Cwi@VQ3QKl#vErUAH@E%qEuEZaPW%zGjGp z^e0xlV6X@%-a@&HuqQ8m5nslc-VRSf_k~#E(>dtTlzZ=13817=eenOw5@w-I@hfr5 zFLl*^G=BAWZY;X*jWpXe)BQVM*c;i10m8qq(^-6D5rVslp%MuC4VSzgbyA{VhPn3U zn$GQZRpH%T#hiC!z^*gji%UtlwZ-rR7pkgyS&O*{Lx~qD$a}@fef{NY8+9LER%rmj zNNKSCdam;7%~o!L6(ogJbaIA#aNG3GiasCUIe;ETobaF=?{&Jc+4`I+49){@8Zywh z6n^tiySDzV^@qXOl=*mp^JUWj@RgN^fSiM7X4MWSSMaqXz)tWZ)yXUW6fH2ujzhkV zSFWZ0%vJ*K0_qnwHfCdIZEZr_#C{sF_JiOaWeaEIbk<<>^f+PTuyoz`TdQg+X|>va zSi#G7eBR#6Kv<=Z-UGaPVvM_AWx10s?Akb0j-H^$Fk@XN#kGo37XsnWOw{V6JC%AHavY#>RIu;}$&0t*zNI z=_lWtnts~PB!)TsYetZO0H(6t@g*;h6IP4u`VPaXXsW+BJB_*6Pnw zXubVFo7fis@I_1S?U;oY5vzNohL%cs9dNg=+y+t6d!hl+1_~bk_|Y9VGj668^o|PCB%Y6M6i>PFzru}`N=`EFWLa6+NzUxT=yzaE z&0hI*w}$Govg)61CS~Wd=S{ray1jj_R5b3{nsc66XVGzSWDu(8j_HXhdvls-_SalU6rv$s;_)ecYW2c`L#$IHbE=(Y>o>Pw~->Xyt*FbrSa(kMVAbtaefQj(Ej1 zAs7=K-Ci^Msmbz${~5}IhRnw%WkHBg@zhb^3rZ zc6r#wk8x2@X}(J*eDbRy9xQ-098zF+W*vyn92OJ!C@H!zuZ! zHumyb{g=#v1s?^hc=`QzfDfjp8Ox{Pz3N%EnMs6TJdIF?M=F3m22djiY8|A|2Dp9h z;WGnPF&G%cahG8j#7vf2lXi(r9n=Mzfc$Hm0#pWUP8H=b`1g+66&v{BDziri(N(KB zCEW2|c{Vn4ZM>T?VKIXW^OoHa11F`x(-r7wmsKWHGH>G7MMX#Bn7!PFTZm|AOqFd- z8;T7^5&+K?652PkH4Y?IlUv-CWaB^Y1*3+GCn^xMu@vMD(1ONt5lm}RC)cmCxyv0{fF$x+tJ73skm#dq z0UHuzHXK!hqGAb&eyWU8GPFklMY}do*`1FeD0_8K;dIvL850x9b8~s-?+#1u97amVVxWBt#)H!Q1_(qaeqZY4*a5zenMJLt_92NQ zBad|c2Cu>5XBp|f`rLm>KhKx>tm`J$(wt-S!sl$2M=1?#3~Jms)u=GTgZotSNo7r5 z3M3gpO*^x)TB4(CqRJ5iMzODd-=>2L2wtByQ zer7b&3x-Sk-{KBiww}TG_m;N13IvGQmaPQyzpaQ2iRLKp0&p_4qbi^tf|%o3=XBDW_5=)ru-m5b^k3p(j+}@nf}tw1ojr zVXrl3FkVP&-2Ab}+D8UWYs>i{YX)dTx6uHD%o*~|!#x$rri@eAvIUruW( zC0n(t&ZTE0OD?h)>z{M4P@t2S)p$xIFjyGCDON&_A36V-nR!l4%||0g8S~>|!f$?j z+WDPMqN#qf@%uyl2*xYqvH zgJ#!{pIRTwv-)hLwl*C&GdFkYz?v+#JR&Y?2|)wa_mpkv0)@1dYj8emQr~ZUN08F+ z#~9AfS(2BTY0(iX;pZ2Xlq`KT*x;4*tE{@3348>Q&DJI+M|N>YcoG!mSoyoB)4joD zVEZwgR}sE4bUflE8RWv8R6DUCudU^hTUqoTS&gp`-Zr3)Xq+aH+P zmmJMn@F^2$ao|3Ex>Je zpGF*O>0bHDP+pglwa=gZYcDcBw7?)#l#a*-&wedFd`KMl#G(0YIWqn&cEgjCtWTiE zj0rB~Tb9gjBZb_}AUe*Y$e~XJU_9xTAVdw7u12h`mWTb@tCq9sa|i(?ZxgUTvi)j1 zg!4n{o()d6PJaq=H*nacmkrk0uNRY&jxfb^jN1O>ZdfKlqm}odbcZ&Kjlj0FI_07u zZES07oqIlrZnlq;gHqs1QYmgvaQ_v@Nxo(EsUksM#N8er;SZ*k1(DP}LG#DOO=oqg zT2iIPS2Q%l!0lc=&}I=~vul~1N+vfdx2Rsp<}a!oeQ2}epSO7hBt$)5pMLq03n3um z%&9zi>m@q;GuaOfr1JqtUGxN%ERzuLXtwHhkOLkxWd#N|=tx5}t+8;${N)Yn=H$wp;1l?fDi%Tn&G2k%t-Kw| zXtvvX^pFD319j3aKPsqeP`7~Btm*RRR9`>3wS@+VbiW*St`4WI{~`awzoCew0oO(l zK!Ig-lps*Sb07;Nj`(K=5d{YsO%~~#1HtD?F>q(+sg*cm-&dMkt|VB-b^$fGhAF_k zZcLSg!c;#1=_{e=0}JPu8cu+K)0{%Nwy81m1w<=I0F*1D^sx zZjmh_WaEFow-47i$=XT&UISU=5TqgkwsW)LWMR@+$JFs7_jYsQulp&r?iY$nuxzDMHriBOBaCXGf@WkwDh;kOy!sbqtI;y0v~nGZssB| zAe&k1;xOYQtBlM*_WT!QHI7%-Nh=ltvWpXP`$t7OE9W8YxJBE9Akdx1 zUWwExegV!@>}1h*Z;ewncHg5$P-Xo7mIzUSue|>;G(K0Dm)l@hvUu%_84;E!4FN*! zxW!DUxR>&1Mbb1@U!FgP3*PYY$hEtlYL2oF{Y^nh2^ISi%i4g$jK_-<6Lw-Jh>Du7 z8OKIl?KD7pdE=E)Vy4rTS#Vp!CmK$t0?=bW%W7!%e_{~`0ZHVNlz6~D_A&b~I2d2t z&;{!3?RKtzSNY~kY2qmr=vTAmAfzot+jA)j{=XqKhS-HB1&ZFYohW-A?b(EWt{e61+Xw^sBXE@i_)KI8t zxYwhSe_BP_24KFbhU*4RD@@9xlW{<} zcXyVb3KLy^KeWH^gdJ$flZ@n^-flFblwW9OU3)3iinYr-oA=8fBgA%ISQEbTS*I8m z6B)=lva$;ts52R59ks1pnuAe)35XDYt6NK@*ScklJzn>u}PNsv#uGSsRw zI7n@Z>s|4JB}QWX#S9-xObjbi1An#|#mADgR0_33ASuHrz z(@(p*rx3j4t$&qNw!5{360|>F3c_%RLxJ=~X3V$P1N8pO(J4`{vAyX)W9}$D3R12L z9=GX4z_)KCjYUMDP#Sc8y}q}L4?t{AfDbZOlI!_OuB-MCB+d>`H+ z63k;8%0TuIFQ-@-AQtU>3!_&BMEH z6LGJ$=UbL+%{vfv#i3DkOS4R!gv}SBR)?Io?x;IY*_Tq}Bj(+^%*_Ls(><~^*;v{; zJH!1Q7#Q<~lpX_KW*u02Xt3j&gzVJxtoFVJYltS!54x~_)pK6~vU$_BV8^i{|IsZC_{_OJ3yd}~OAu7aBG&|D!lri^;^ zq8pk;>sC^r!?o~6~(AJ9EVKT zA^}=PLLg!$ad8w+(2aV_be-+a!d~Cm-5ZfdAdn{*Y%pCw5~0iFs!N4ApmV`dmy)PH zKCH-X*pd0;jbwj+*7^E;qtc;2@I~zT>|9Ku#NQ>xIWj%N zW?DgAMm!c=%vhyq(eGM<_`=KnYEa;H+h}H*zW^(~?t0B^jOqx_DLFps5oj*IMu(I6w`3;>yY1eD?KU;1Wwb zYn(qmuA^jQDMM4`iGktnB`CYIzopX$cT;p5-hCy+orWpiYB9@0}mY4yHca= zt+(i3Q^q^hL59pdYd=b^He-%d1%C^KBCR?wy}h}a8AAjuA}kRfS2$LDom?=~p}G3| zaf5^x4CTEy{MQ6@5HMU!*ji+$SE%M#sbzrZK|#{&^TUBRF^k zqN3#EcX1<40HX}8ZI~~!Dv0Wqj07ZLC5b#QrGrZONkm>SoskFZpk?~Mp16WS8A+Y- zkA3){fk6I-gpB`_TBhqoB&5_*t=KcL)n1r0tD)gTzuCvcF{)VcGU=Gq3Shl<1>5*( zhRhYFK85#V26V3rZKy&9%B`h6vT2W-ng>tD0!QvdrE|Qf{m_C_0kejVp97!R*qk-f zYlF|Bs*hb}xjM(;NzH|+&7LNie12c@v$9fvtW*y&6`34jLmp}r*SX%YZ6#BIM2zEJ ze0}On5-SvuzsbA%reRLO$A=x)yu!MOU_hIGZ&&qkd9Wxs9D|dpMX*uTkW*@rD@1CX zmp~L^QkGk?!Eld!78S8+x0-Djem2$C*Z;BJvp3|+NRrCaZ(os0V`oWwc79y9&~Rl^ z)ctk+;HrHYT@Bug0NA-BDQs#AokuUm-TAsmZF29>nHkg^^2hx#E=kxcIL0VhWeUTn z2kRRufMEZ*h=ZfzYSpI=u2nkBRh=>6+DuL=8XwcqQ>B)vjz$#4?@p4Hze+unIxr0j zqYlDwVRwm}na5h<3iL8Pe9JKkdGm zC^V`+)cy33#c@xo+iPQl#3Yq+a2v;ttYwiiK#`Ay+06kM z6HM~~)B=)X*8TW^KzYf;a)ZSdpWl0|xp}V~w=WkC&Vfv+AV!ig5ej6)A6uGdg6m(_ zu-fqp)(G016dcP`r6I~m1&A&wOcRqDE6c5J$MZdUY{>D@`~w1W9Qm}%rU-^EnP_I> zG_A!fN9XoPbnKdd1c+8f-Sg;V7}(om_b>(Ggp_h7KsH7anEBrb`Ca<{6(O z)go;|%4cah3kn1TF?>Vb#NB_xEjX%=XZ?|+?N!yY&GVQVcQ!J{+0HA=pNHqKB>@yj z#F50i6x4jSw8t9PyF8HMrJSRT`A{jB%3`44v7#cUC#?9*T_0-E5We^O`^RP=o4Z1P`WOo)uPUl9KkBaMFy{Z4K?ttx{8K>3C1kYWZxn6Vb}0CLKkmpBZg|7KQE# zKH}+Nmz-S{&4yHlD-Q-6qkoOM%%4Z3-wIlHJi>O-UMS{6%)~pxU<8*-)$=AekP@C{vpvB(=T&9R&0}IJ@?F2R zq_}a!yduJS?v>ZPph?ZJ-kHm(cUM^?P{z#+77qZRmHG6 zuj>oZWZuC&<|*G6*U*KTtoKxPGET(y&Hhck`ktMIKaJ5I(u%7y-=%dAp zV=FpiZiN21E?ng24L|wqi{OEj#0J+A>yWg|Ufq<+X|X2vmB%NJt}=b{KIgr<#agHP zoP*!7Oqq4Go!0sQVcac3Kx}w->GnQ5(MlMu!^&ApN(vw<`wNMK^P`P2Q>`N7+DcXC zTGuPr?(?I&^%P$>1NvVc7r_8=;I&^?(6CivVy{mcPGx9DMReTSV{1#aD9sX9M-Em7 zt!8K*V_tMJ7Jq-yS>khBr~2h=$73(Ce=T*U((CkiQhKsLU$tMi(G#!@U0qlG-d@&A ztcR2h2LYp>GJp3a%2(OmZm{|!3K~mkIUYq0ikOOq|FHhH_^X?!%68q3@78rSHaZY{ zuEt^Y^Qqsc2t-U{%1d5wsoWE1)6DvDIO4lD2fNU9bJGoXinCsct=%D_a8GD67s=ip zvjY?=fD8(C+9SW|M-SpfnC(VUi=CgN`uQTHtlnbRHC`X~I*Z)8y@NpBtGM6d%UAPR zueJT~!?F7Lgn*C`5BH$?;#jnh7Z+FPs*iIR14F6iYTf4yxsFYQH-1XN&h-p=YcgHf zGXWMG70GTt%>|a~?~_RptjQ`F-k`zuI_!=}_jd0o&_If$<6zm1)V*;)kh$x%1}yIH zfBycR8~8Gxs~ugx%SGUCGfS*T7$wP*WVOz~BP7w@idH0LyBDAJYh?{iAZYAijhiV!m4Ne=3=;&J37SK}E|(IOMl zM>^uCVYjDqHW8a)%&93Fa1iZ3KHg>!@$u=!aZerCpvkkDHwt(!Sn;Ki2?Im6qC$>w zv3c?4iB87G_Uz5fg4{dVRL4n}Z~-bH#9dwDE?s#)`neI7a z0rhY!6Qt{!d1}WbEId*5RPVdX^@Gp{3F;`IMNW7iUuEOz?|0$62s-17KOLK!A#QF( zeR<%FuIlQU$zp+bi?mOE*VPpg26VQKsj9H0TiPr<(}u!u@kqLDzNvme4+|xiGPm#U z<}K1bSPZZr2u@>q`c!{-c>53(1eu%a_AJUTDDUrDJt%mKo8yDPpr;2MX3>}hofH<< z?RVo|oZSYO{)^+vm(0Ag{idC_r#s*zrxftufy03=z}c>1l_aw)1tIxa=X zoy%*0Tn*0@xbT-@yaZWU7rVP!YQ>F5y0^x$&spd<`XXPd#_to&Iu53#3d|%WX_Aqh zZqII%=9e~2MTGk-qjA5a+M<6!$sYZ{PGMv7Hyn^lR zOplW`8fp!ea;wPI6%A7+^`WVWO2?VXiH?qhHpmR^{LPuE$Yqn7?%efSa@-!4Zn*_i z)cN?fKzDHENUcaqO-Fk>tCFea_9lCJdO_%%3b!9tYV^72dq}paF^O#UT|k+hsmglu zCg0~`^o0!_U>vt|<=tj%eSqT_&Vz0rQVJc96^Y!Q-wOS?zjtIj+6}J53@d(Qyxx^w zmjl)_KN~jx;IJPJ2#DNXE^OuJfiIhqS~qj+win)wPDw)I3|ZxNypLqT7mM;fcfSpY z8gItc9^hf%jzd)$q@;OoPJQZh78TUF(LnWqt+V1hswGVeMSZ=$Jbv?^1~8}N#5}Y$ z+<*FafOrzwuscBaN}-sDAf>zCYg?^}v~S{vv7f8o*%OM3vz5c;WoFitG#+!>? zmxZ~DwPe5&pG{q8-JYl8=g9V+cgqVZB^jz_k_$LE&TVo&LcUUJR{wA}GD}H(Q}h*W zqpt4Md;dr2yo*$``m(Ca?bsJlk*U&l#53qWwDx&px1(YWd|FptYQ1frJw-( zySeCn-(fP_C&O{j{Hu>GeJEI-Fx>r;g{$km?GS7Uin{g1{4JNea*drDiXQp>cuV#A zo<#UrE#^x5H*8snVt{fWFE8JWgEFzj?T!7ZzX;#tERzm9fUS~W zZZf8-UjCdY99{1>jOU~*$hdo5{(A6sd#a`^tAw3}|9p5oJpvI{(ZiuIpTTKr!m6`v zP=Vufu@U+aOHJeu{b=FWpFgIz`)F%r_q+i&8CnU?lD?xG?Pn2FyW8y{#X9xXziuvV zb?e}l7sr7-wrM`6bKx!@#(%N*-o7#$2BNFT#cKTAtGPb~1%XvoxCjVKC6@MI15nM4 zxKFLV0~_LLe+kD9Jc>}$;dlEzl**{4S=8Wkb;dbUDe3p&=Aehss_Vy}!kqy1g}u4U zKhmt-NXVzRN9pN}M+2P2^#-xVpGzVEJiJVEZE1f+l=iA(!=LiiuCyP*|5T&Ub!+106>?fLWdr9fNVrd@aLSJTr-qHnF@IVs%pZM+=4yv$T$ z<{ST5rE?IqFR|@Xu6`TKU7T|Jxsn2o}5yquHj8DTxX@G~9WMNr2NkdZ$)im1cCpO4c z$y9pW;0_01%U6|qa{Rc0j=iL&F%7o5zGr*>rg*d@pM39O)tH*<%}GgT0%=me33ec7 z%t-UyqymVI_}|Z=rIEdk{cC95QFkBq*c&|g_2$h^fBzCY%g#9vbk=HX-%ajvyTtFv{noJIs*Or*U8=9Kr6ikw&#MQd zP|d#$)$20^7!2)B!#$)tl0P7fO4Z?#e=mB1YhA_{>bagQHAG2p7@IObK3OD@(wPXK zomC{T9it=Y3!DxP{{Gvn*e0ZR+)+eIjZUXC`10Q49zva z)-pG5u-}>}nW)sdu&GcdPvfAcr7^)S%d6atdK)=8tY}OVtxg^pvyW_o@7}OBw6tDL zuH$+2q4wg#u8p&TUP}wgpg`BiT;au9*O9mP1ODFIkut{wYEQ)hq2ej)jf{`1{}`s5 z`mYA%)>T^*Gk!(|y|W#Pi`&i5Zz>q2|M=ET=1)ox{@%&Tj9XmzT#QNd@S81iBQBET zK*uTv{(9iAii%lB;1x;zYy02nM{|U>_gGChUYW&@dKqw#02zH=-mB59ttaS4k+`D* zcZ1#W?R;~F;YYPy4v5yW!7z$v9`hc1LAtj|2!LX0*l0WRXE4J;>z$U{`ou!2wYRp$ z0OlC*Ii>IrsWLphI_vatT_bsxE@C@X+WhI$W-{-o*V$5>^$fyH2Y!-vI`47ykqBWn zIFRbXq_uW`s%_=vqIE9C7aQ^dGc!#;OIl+IjsGI9XV>G!26*`SJ-s+yR|liFmrX@u zzU~p!brQp`^T~}!TJN0rdyoG#{pV#%VX{``9Vp6p9(__0d^>_@FmEi3&&k(l!2#buD?7R&g=Q??fp ziU+iqVt{$VI86lyRxWkxZk&It;#9zPfaIR*uGX6vMk?F;p}2d8 z72<%l7sVEP*7T~Dz7g6&DX3|RNU^bCE?QWxJjYRs=;`E zpPO5oX(KM;JI`%4&XBXgELz~3<|^hc6g{Sy04@|igI>W_|^ZW|i&dSW+} z9^iE!6*p9#`r+LC3DI?`tO}HnC{~|5YDuR)U06`jx~!v3r^)~*8URIaH3ps`xwBzq z`JIcS^xFkd9F)MoyUcq$gebMrtm6YpsCx~{0r@AhlHedYEu;F@)s-o5)+q6PilRG;OOG?f?5$gr6fg6?ybvdxT=3FCu|C%v~9=RxZOQ*GKoME_mmf1=n8 zo}#2^KWo2*+N18x8IP#ezM*jRA$*QWlkw|o7I0W($?g`r)xb$f%I6yF>F4onfh&A0bjpflJnr!kzc_nD{NlpoGC%(%)Nd)l(1hsRi4 zRaIOyZm#|Y=|?Hrv$Lx`pM}H2UO2vbBr0l=$H|oQps-~{%HaA8Y(TZ+1o?42K6rV# zvhg6m`UO)Rvu3$PEaQ)4=E>7SMvV@(yI8WwQ;{8XvG6_rzbl=W?rlUP`Oexbt@1`Z z8E&Hza5#iqdwGkY`S<(34CHQRn$f@U0hc(?<6LV`Na5b$l#RRo50#1XOxeW7Io8kc}MwqM~sZ} z{eu@D=j!3gudL@@lO*yxMB6N)T_&iQ?!Lq`F z@=@Xo+_i&>%CdkI6UE$%00Tsq6%V^(AY>wwoDe_%!ZvHYiO{~~GntLn?a)xUv9zvE z`TobC?y0evrONw#E=!I~eMw7zQqm1*F_pSjekWzbx;(@R@@2SOMKvvBzIwpEJNzgd zpE&Eqw!h-tgj#d;imppyy340@-m}x=&12Hi1QXE)FYTK8J(iLA87goP9dMMmv2%QS zY);ND`4$$e+DxuKpIZzK*YJk_Kjz*#Dz4^P8yz6QHE4oMAUJ{GmcRhPgS#b2@SuZB z65K*?5AGJ+-Q9f%?(Y8WA@6(6`Q3ZIb^pCQbDh8JOawQdO_N{#L zK}Lp9Kfi1Vi6KLFKC74&_g0I|$-RSMad%hOj+v8#SQ*6a27^x6sNtLaePG_;Kb8Mm zDu^QHV=73@|0NaV%aZWvMU1ja67Tul!KIslo3?6iMpS{#c4Z!{-UBNs_h6 zxLqe*vLd9wnjuLFm|YrKS;frEbDn40$-jyH+Tl`{mbOSRr!2TiFW9DG!6}*vJlQ4| zEqA_JQHlRcFectjRTXCBsOiqGaX~&SP1^q&a`_9|Le;frTQ8rLC2R;F18cJXN5CZq zc)i-N%Nb6;eVNDU;g;x&^byVpr4aP$4C`J?FibqPf8yJW`jXJPUR(4Kl9Zx`#(>*< zDRu5x*=GG34;u6~gSR}-^g&i6ISmMS-&~0)_^JC!oSOGpm)?>VOBH!IpG;Pn=3ZpU z9Pgu%i@zY0Z(h2Jqe%2(tAxQ#5a`rkz1v_OfZu;ZB2TyCs7;Q7SwUWutqp+EN)IzQ zLRFga!eWId3S67uU;RkkX47%S=YB6JARI)N%P*%Ozq4#q< zU}2@VIZ_Gub~qWtDwoK2_F!@#hY-&<*66K=LRnydGlK$8l|w_b`r#mGNoWHaijv59VT;%?rT{}Q==`=1>Q+y(20-YLcz)}>xueFpGNZnO zWM|{u_5hN7P`vD?%)#HApRFGj@9$XM4!s?hD}o5IZg=!D#l(z#1UEcxkA^+(l~@VF zPA@$5I|3!kj9+g_s}Up42Ta;^zIU^ z`WgkLkDZ+)F)>&*LpAsQX2wL={h@(0jN5vKU1>He*Zs`>;><$a#rAkvB|ns$XP7cV zu+hW4zuZ*DC0nt^WM@(@jGQjbb-myDGB>;0(Xsz3BI0L}ZZ(_hQmfWf(L$|vK4s+InPp~ z7#-3I`b-98lGFQc|^U z>-~au>#S#yjg2cU6y-&ag#~eBQ{|pTD;!)UX~lgv$t7v`?;gH1yn!$}v(br?H(R@kTf_Mc`_^!aSb5EjjL~g&y2|>JDfMW2(cP(QKEeM+#mbHYeV?TJg?Kg4^qz=}V`Pvz>4o8}Tybn5c&H z%a#7IlnFCVzqZ$zX@E)hQb>=T@=i^4H!TzQYP8*M|F{>*CS-7B{}!oX0>bQPM+ z%!a6BA&=3FKZl13;o&RGDwU&L@+^K27auA z)HY<#U9WjS=rSDZ12;!=*1XzQU%=n#^VxYw28FRmN9P;ou)|Ew_=h_3RTnrQR+1hb z8j_Odo)5&rcIyYp?$Ls1eP^%lMst-JlJFq%Ls_+aDb0;mSexrxGs=3xtzCXsrMZo| zf3|XYXO-19iq2NNeEw#Mev<^t$jFLy_#~1j8LQxgr+jeQxps)g-6bW#v#pU!lh@Z* zF{MALJ)SIta!%msdU(VK=7H0~Jv`i*09d%ojU{k6Z8y|#+(XxNf0;fwlAL5zBeWY+ zq)78oS2-%$1!+@A&`uc)mb{o$bjRUy+y&GYr?76r7fOqHo`EoKR8(;>@M!~qxo9^W zo7d@_@e&BcmLr=acoReJq3`&boxyo)bb;KRhJi`BdyTtTcj0)dX*-bu9gW{^H+Jyi zbnKwX^C6Tpq@n_Ylk*0$TcSSZ8XKKh?|F0HIXesd-SIol12WT-x;gA1Jn_7%5T!Mb zks32VSO19kq`EQ|5#b6&nZNn-4asr0+GRr;y1A)xgLJFE60Uj3++g0?Ubwg01Nz;-Hcy97vx+`n}w}!NdKp61F|?UY*L` zf-Rj~3Uqe5`qNmJZ+v|7@NhCeROmQc*!^g~uI}MVes9BPNJ_d+N8zZmH_A}}db`#q zeSA_l9y5bRIH{`AaNi~TY-D_<%!E~YI%ag8MKiL(WQeY~X@7P38L-E@V)Q0?Q%y`X zim+}ngQR8L%+I#vGTC3hG*Z=!mlHeUFxkI39os&(6)u#p`+Tn_^H4{QgL`r~TcPKE zYop_E_TKYBf}Q;h|7u`gFWARt%kw57fUwJ#r~hkg>UP#=!V@YUp6<<_`T^-$-45nW zS)&-t*AEOF=g;{v3ktqE;}HC==T>=Z9d|Fc=~o4}a3?o>kLLa3Q!K|yh*|6LQE)IT zm$irX0c9gkm~%^GG(yvFef8Hz2-CuzwB6H4hb~t8al5-+dQPd_mLTc(@^W0)YB!rP zdeN&JCKmIbGr250uGS7wa23hj$EDV^umOW(vAz%$2aby;$FcU>ij+K27K^I1dJ3BM z6=4y+Jn$Tvh}S_th^YAH9W0wrpxOA8aurnK4N)_mtwmuweg0yZf~v-oi94-0AqV7D zXqb^15)u}cAha-v0mp_fg6ZW^!DaLfYL9LM0(k`p2|D&q%7Si}xUgU!eS9_jn4tkv zhw4cq`Us1WFs+a6`vajlknK0jdk)ZyW(FB7F1B{K2K`>z8d#xFSPmzew6Fz~nIf47 z)7`FA&#Y%RMiYeSGi_<=42C3^z=6bJ-HbiOFalrpK7UL>($?Yz>2FS-n|+y5(}Vr& zFh)8Fh@cZpnk8S{s);#VO+VXFkBo`=QFtt}f&|dbL@qBV^ycx286(z9#}!poTk4U~ zGzOt$UX;!4SQM-q$O;0_wIn-^;o86P7!b9-Lh@3v=y7q7p3Kim45)yW&0s4xhy;cb zn}eXW_O*jPVm&vI!Eyl=#73-_D6uTS&ee&`)~*jU*$xhM(*K2U9XBtm8utbZA^>zx z7?8>-?pQV~z%w>KJ$>!Z5~oC2a+!nZbz4iDIVPDdN3|4LcgAS#H@_)Eqv9%EU4U@j z^?vx{?G0$dckklf$nTSzpJaboU*8jOavB)W>f)qlW{v`{(h`}OkGY=XF%|6$tV||w zhXpv7Mk6#MPFm}|10NLims@gxK>9z-%=k`|lLcRi=DDikTU#r}lj{u* za_sP+po>J;MGMnh3aYpQ%8hZ_fDFw{MLs^4;1G2RJX-8<&BA9<$xO^QxrKXNVH>ME z9F%6aRIaWjq7~!Zc#HMU^{Gc$BGC2aW!%@aoNQlE?Q*2t6li))tyt6|dOJF}nO3=F z@KJqEKTn=$hw6Mew6}36(uS^Y;jn+Y=8I;sty#VKw6nXHq@)D>gnA&g#G46yXoMyY z#vd(@6l^#P_&HyA=Hy1UEs2Zw7w0xGSmsAC&XSNWP*ab7e>c{@&7%~VWk{v?%E-sZ zuYJOql$1F%bl)3JskQB(Y=d{JC;vdEA}=Bn!t`7vDX?Jo4CsW@rTfH0jL{y3S;cIZ zt6TqfBezDhi1183@!|lfOeO{)O$MsZ5F4oH?$gbsHm2SpN(8Nt4dsO$T{cdS9hcc?+!gb{z#1-H5z*3fRW&uI z^Qo|6yj^@$T>o)GTVcW=yHB5@kuK%)a&Fg-qge4#w<3G;PgNC^-A-MWQcH$iO~hE& z=IWFKSXBe;;(n~y-m6h5$f<8O9O0&vtQ-~VJaBPaXBRZkf0W5no_q^taL88H6c$`^ zR#PLV!gP(ERDF$uqJ8&9MLP2gyt=w;l#|`B9~v>{Uvy%G0nSj(H#0Bpl2hN`-qu?D zaC{Pnb$oJx`YkJN!Y1pLY!BG}>Uh65?<8RCUf?6xNm|-Sp=TsZJiO|nI@$Rwxo7QI z-KFbiIB$j`Bru<~qeEz&7Wq|8xQ@DgY~NakyrGCjrAMhAZiVLEPK~_zP7%<8fCzhW zQWf&@A^-aNBb6=glhPOqCRXBtH4qVYrICqs-=O#(xVvwxgDYz!Bkjx}w(4@p9sh0} zbA}+P%*gk70k2s0OT%?>v{{BaCj9(ki&y)4hg4N`kO^oJ(Qtu??z zf4k#@gaE&so*vD^>oPlYjM zp9h&%UUO@EyRV&iS0k3STSw=PvqIVkklwtz60|H^hIvpDGg3kbP@|Qe__w^pFc%a zhd+tC{9g&k45{h&zt|s1-!M}gH^axF$784Z*|QzcJ!JwPwxRzqdUDc?>KU?q7u=hR zJ3&{5x|^b;tC2-kRgRPF%!=O-(wH-Uq}?kP)Xd#3Tx%ECu#$tPcta53nu)?rqQE_eA76myZ2>TaXmxxlJqvOhXJvra5&UGk| zhcnou{oa&D zSDJ*X>)KS-FI#BL$OoVdZ4c!CSGPAdi1VXLqk(z*-XFGm_pymq=5lFyxsaEkF-c-! zr)dW0ZXYIY{v#EP*gv>GnBSRW&a<;y}-u5tIUoqd+^40~3ZL+UipgA)}4!@XRt1<<)Dl?~Qa538KRU(LB- z`%L{XnaSyy+?>J&RSkz^UOaX)S{xl#fr1ace0-Wks|SU-^vD=BF&Y|ByU8CTOj1Tj zI05;rxypg(=UI$bu7)kjC9{0(rk`+>!IXMD!41!xLxcJ!ELxzS2gg2Z947JWXU4wFB zN=jR-8~^Ik3~cf0>Pujrc$IG*m0m-=@e4e{uyPrZ3!@| zSn}uLlcOuCB+q&*x1lVi^V3LsyO+S&n}jO|y;%>Bo|C`s)Zbg_ypJA&FtZBV-L~%t zB!4Plqx{(Kw*JAe-AzIwOe-z%(+sOEujBrHYfpqKJ9jRaCSv>fn*Pu;(u(qu&BKZO zo1nn3TAr}eqk!cv)n*k^WxlB<@(yO{)p9+Q=|8RJuTyg_{Y5Ap>`#eE zxwzS>WUa+TOHqp9$F;=2L2q}8hR+OU zk7{goJ3}l0vvTiYWBKz%RBgm_s=sp|s#(b8GWy3ssXWLThr~kUvcg$%D!=+^L+RcFR*Epzlgg?K;+@Ej6@kv892 zo>F#!zM8NDZ=rwb&2YATP#5sQEyyqrO`Igt6GfP`MMst?@qTOoLN}rB@vL&dEr6%= z3o$T!ENSA)^__$(9oItN9|0u8jZG$w2x_3X2;($5LG+?Tr1Zn6uVasRHP#sd(8_+Q zIeT~jgCSE&G`T>Gvi_o30H}WO`H`MdAUmVKLkns?Y(4&f3EJeu&E{N2K>me6={NBl z1BP2+O+|@BFd19BAM3V&L@@K&1gD#^kwB+k*-ex4az-Z$L7*~&6GWn9Y+H5p>m_wQ zi_SlY$$hU6+pVPgsHtl0yC<39N(d~*P(YwN6iUC24D!zX%g4Lb0$)Ktnc#uP0?;xg z`q&FN7dT2kA4};zCF9*T%~0?4|E3*MjNGs;=&LWy*20O7MHi@588(>p#;Nzc-qfdN zCt?C7r^EplJ`7!>~8 zu$${|w!G>h?G1LXw1W4Nbzl9oLx7IuSybwP2KsfuR*3V9knL|06iD^oGB^dufL8wH zSN*ios^x>>Na3LquS6^%u=dah&_I*E1H}4Hu#jc8UHt?(5NJ~#rbPa^K^wZc64!Js zioUB8F*=KEVbYG!a9Nd%wAO~*fy$|;>$Q@2Cn3<2X6*Jp-d4g5K(4#lOR#kW{A4qY zCHurx{%D!ntW?J_*2A;*s*UMdG1}bfLgeF$sRWksn4%S7znyQlmltvb>Zzu{Z?-)J zxLq@i-ovo+Vu6e-9Y>;QZby_Ia(K+%A`UFksF zACa7B0W4^A*}2i$4HP11>GnpSWmMIg^iRPvvZ%^@OcLu_Z6@=GTq+4(ruWClD4Vr< zO-?%T4p|k)mGdLsxTO2_hDClsxH10YX1z7TE(}$LwQ@`Qy*g}tf|Qd{{^Ja1xzd)r z8(P-f3_3}>v|*5I%b$J?f)cYuE?X&4JNJKFcV(mvO#Q&KTY|0k;dn!(l%Xp2~r zWVu6Y|J;qzPs1wE@ipt$Z{MzUXJ;cZw0`UENuwAU>DYC(0s5^$P@fO25%>C@>lfUO z+^~TA{Fm-<=NwAM;Fb2$TF7CrrQXz4Sa}MEN^@EI{Lb&ROL7!;1;&Sm3)C-=7JrdZ<6C>s>XtS$PN&F&CFHr$?npX=Z9n91PJOM!-Ozfd z>`n2P%3tGeEOIrs^l}uBZoGA?vAh`ZJ?)@Qm*BT?2}LmF>fyXSwJC$XXuXfMn;>W`~hJlp(iode~foT0eXRG`YSnRXCIO=I71L3F6-w zl0__X+DJkW&0sWK>s9=o?HBl-F4J^xyoRbaoRD{;XtWSgEepq~`Vz*HU6`e4p}7pYSAGIfi98B{wm=OuMG_A&t4O@2B%fEXyxT zN+LDsf7LZvDMtk?Uq%*ly|VGS#W`ql7YfE7;l$Wm z%`Xy2uA%7&ChOp-+AKNRhBVE=cA6JV?v!b1qoFlQPjOq%I*4K0jVL+{!7Fz=fq!q8 z2cGboo(eeFcD^K?&oNl3pQsDvQ(_$d!AeslUbLe?MXn4-TApe|8Fh@m?O+v4?AqYk zHZ(P*{?(P`PyV5OxxjP;wNzyeOMmhWf!4dhgQ9I0pW+xn9MXphhb0U7z1C`yW8$8w zvN7hSTHV*9-@3|H0M?u-lr-gdt*B-BEloCyib{3~pEFRusZInlx)EC;JV$T^$6AyS z3FM1tG%Aq(DH!w%ff5N6n^#gUsJ+>2+Zz9p`oy|iZL+(m-;B>ytk&%4J=L>-HS(rc zt7p{*bZNiMoMRhbNBo|%9iYPQEbI-{7j~t}vsOfOS>!ZRP+-P7UB?+I%nS8bfN-)F zzb9Bthtx6D(7MYzDv6dIFWm^-*6${fR1+3S%IlepMG6@B*1;ClI5&iWf8rk6326bW z0Ff12X)n5aN(+`~^A`_dyeP*KKN4*gI^$raZTpKeMmIF8-dJ!lX;r0y>En5g|HBgjX$+zlai)R1pCHUnhy_{HMRrW zp(!V`_a)7YOv5cR;rX=JN80&|{zV5L8O-rp>m+#9uNBp2$zJ#ViR4Jo*8nv7q%RhQ zS7i%#?`vhpg5Gim1bwe=;Q#(~wDIb9Dg{@ww0k<`aw(O$iz(*VErJ)T6ybTl2g}<- zZ9ZalggNvIj30guH2D?gZbBCo$ZyN?o-BUnb!!s0NBIi$Q%KN;Q#Id=4y$F8PI01Z zn3q3ohyyfXq1q|bueqbBK-1%o(+M&JDmcOdR$j~?*|M2pEef0qjQt`(^@4c2nlAq+ z{6-KE?UZ%Txe+&x-**=YUb9HMY)2m?coQq#Qj1=mjd=03D!TaI{57RC?O4$y1_vec z?B=UMH4Y|sdWJoJWG++wg_bL6rm;y35RomH&YP=onVkxFU#?yC33;ZvPb!NB7bsdS z{4F%TkOIw%cSh1$+3Q{98vAI*3!E$OGqX}`UuLsNwV$DSb3jI&VxE@G$8|woMQ$H> zTJfq;SbkQWJ>fC%zFm~TkwJz~rE$fXEk4AfN*V6iPJI88?WZKLptI-yzUYJJ$)_vt^bgN+#kQ|$oD+Gz@ElYP%yoD;2%|A%s4$;9*Cpjam}>6XMz~_E#Pjv z^poeTsLWM-wm>j&u7A+imyi$Wiv$gov=lK&0lUo*iKxsxhly9C0$f4cDV9F@lx^&9 zJrck!i=v5ydidy(SAK^!~K4ojCSY>MitW4Wg9C|Ymfi=Q_hzU_Y0Lj=+4M8=Y1p#R4 zaK9k`;+Vfh`|uy5C_&B2v6INdXvn;vUkOVaVvpyNFaD#A{$Wd7Hwcmb5y3s4mLS1U z?OV@(%H#mO3bu_k*c1+dlkuv8Lnm;e1$lAC@)Y8bzXe(T`|u&ge@g?ZJ|gmOSO9Ql zd;bq|g`K?uPzwaQ#{Iu_ulA6Owe&qNfVv3iA8YaGe{ODPAmSU1h`33OuAnErP9^Ya z?CZX4os577}GThnyr7EjiMwNqYLG~I6zbWt7j5`rP&A-AEs!ska zadKOePGyvrD?bZQ(9ao2+?`P((uQUJcYJ+(D%9PtTm>-L%IaNwA%p;T{Z2yA*;rZq@9~6QJV!y?{icoJgSicwi_%)AXhY9aeIbEhbp0Q{$Ja5c zto5$e=2h3vhD?Mgs0axUcrO}fMit+I*)>E5b7h~wxVSyQO^Hk2zLKG!s?dDNAgG~v zuB0_*NjB6oWg;?uDRzE7=xdg1{i@OV#7T5T)~9};ql50FjG6u)y!8)Jmuc@K$L6(* zXrqFHtkt`%V;S&Jw?+y!YDnt-{MlOG)~=}^7^61qJau5wShelB=$f3FprTP7Y< z1ME~7GV}9`oAk5|Mj)7&R`fjw@kfI@%->1a-oz1E>)+55C0{NJJlntt2RLBi96YFD zX@}onw4IJ+)nkA44VCktxGWz>XChf-KOcBZ?cIPN4LttQ-E~@|@fy+U`W~Q5K48u_egAEI=t@hx96iqJ* zS_8MoGOnY*eZ|h=`ubjE1-DqRWK{19|M!{uky1O^bOHz4+oJ6TL!+|{v{c^tDOqN@ z<;nhui4EvykMB3n~Y_T3qGvyDY~xZC|~VOv_ht$6wL$}kMLsp zeK9gi%*OJzD7atk*l5ipKab@J8tylr0D)xD61H%Evz?-C=37VE`?J<>aBxQ>3et%r zf_uA{t-nnB1zn8Rc*9?H4RO=*ndPRZ*9i`pYOf-I?WOI%)>`M1l01o^E3|hwGg`(t zXDWR58mFfA+T1LrcRQeaW~T3he4J)tQhm8+c@-p%<!r|1^A=%XkV1+3FW7~gjO|;G9IyIeOdHSS`MZ~#drju4deKRqfntE@S^WARLwnENhhtTi^l{;h4Nw}M8KU&6=))gsbV^Znna z{=f;BQI!Wb3gJ2lAmNskSE}NMzx~CJ_p2sue@1C$;Wf%hdXrv(agnmLxzPb1%)dEv zqJt+j6GjI;Jty1P6J%)?PVSqqdnl+{+12@ET{(i=UyGbJN_1hWp_EBM1%aeO zcl2$LdG(1jn%u>{9DdMJ0Cay_M0sKKJ~T0}CiADifPlywdYSH}?d@#dTK#(h%&tqC zn5-;CS#i?-3|eoBw-KYGnquI6EAMf4>B5L`K{O6Lis2WipUv|r3lp}I1^42U?Jo## zAr*`Tp3ZwfuH+2vERl&?Ub1Dm*`|lR2Qr#M*U0ow&CUfra8z})Tm6T*# zqn&n_)Uf_RLITZ?CmzrEJq?pR*I6vCkrY9|>fi@-oZN{#K(Ayta4eK%^Htd2<>1qu z)~*Q73EQqt*Vu7!amT0xutv^z8~b9)^n5Ni-yPs``Km$K0)+z0QN=E2RlHIvv!raL zuKMyt11*6!uo>Dd`v$p=Bv(P-`~l@LFHA6}0vFqNI)GmI{qJE$|KK*7kBAf)AU*MT z>sIQnc`_H8@WNE6hhcPSY0C$Zy^b~7iW(00fEMvZ#X?P#0;{2(cN>NzB?ZpTnn$T@ z#EDX-8$TO4Yi&c#EJ#mZle&k-$A2CE;TjjUCO9QRG?1q3h#g*i{ZlIQv$b{Y&n5|4 zbBf2Qn5YYGk=$`?Qc+x}3*Cuyqqp8*R*-X*h)B@-5eC7-xw_hZ=*a({>qTZoEHj&r ze{BulL|W>%f43}l_tJa-LLn+(t}{MAFu%)y)A!G;+miSh`DCL&6V%EUij1#?84<{gga&n;A-e z$!BJ2FtU`dc0q_w?qEZ<%I-o}M$k1+DX5@p&tvNF>lNt~J+GniXo!|D z9zMCktBlZ4vh=ofaq*0}pCge)rQCCyD8@S9bB==WQDJu^<}O=U`0DPKmS?SZeu~a% zPs$XUu9|;S`1>9L^RXJ(BR(XVG@tExqXVFc$z-X9WYTyOD&^;A8MB?5IeFm`WuktExJ^E=5mgB0yK|t@; zF8@3rP5`G%&|PTNzXNvkt9SJP&}(RZLN@*Ri7$iDV#k84(|U}jqkTCK5Au_udnMY! zoJ1Siws!+#Psy>HM#_? z6<->z)1htXVTW^kgB4seo_ZggzVo^pW3*|5ar5DqQu!M0xLCn5`3exaM?dR1vqtgg z8fz@x{TehnO3bhoHxcCf?C(Q1Vht^OeNWq_%ix+V{=#6kp6CKK=Y*K)T6_Qj16aC` zqqgp&hQ`wqDkj64vjl{1ow6e=>tbKN{1}M{5qjXEUO|hdLx}w?O9xEN>X{p#AEk>& zX%_%nqhc`6XbGDs{2o1wzSOuY7(0UL2>O?Qa|eGReZ>Gtzk7V$hIxYxyX^Z5!H13R z&hfLDvfx2wj}_zG{`w+4cc)PFxf(=CcB+auFML7hgs^-a*9%7!j85S4Sz1&Q1kBr0-5)vRAqGLO}7!rgKNJ9|O|2YNg?1-RCftGI# z^!KkUx}{6je>pa6sj*{qJ00mv;@{idZ5-$~9IXP>mR(#dq49wEs1^=R5|7iDJztE6 zD#*d+(aMFz%tvn)4GBBZHe@|Ltt$B1#~F}|cn2LhO1W4}X>zM6B!<^1aU%gp;?f$4fo}JmD~DQ(qV0(z zpeX}FHJ=giB}kf@=F(7cw|vk_fR<&0DxYD$nB^#~E!eH-B3H|wfF1Ail7vPvP*Dk| z{%~HR!hZkqXQSG91fZd^utwf%X;n3z&*pS@(_cW%uR7lqKMv9HzYwslUa#q6w29Ua z+RU0v5jvyKn=?vOE);vXj4CD#KbfttIUTzH9G%YB+wdfMlJOZ1ZCn(|sF-92;N##- z4HiKvV&!mkPCphG#^>dQ={dh-d2O>q{_xo+>mBQ3Vf(U$M)$QCJFU1W;gl;ce{Jph zjrkj6Y3ZjpJ%$*(*<3Ir6*W3C^2wqdK9voIZliKe4NYg{EiJ2@1?corP!v`O0U|-1 zm)V$lxjwLh5yFjs%tc6;;{Q6=+gmACRAo7cNbI5vg8fh z-LK!WgYxaxj=AK+emozWDm4u6dkNSk6YGP-_+v69CpFX|`m_6svvd2&V8SqC!J!r2 z{<;TI*-R2lZuXBJvU@6~T1na?>j3w79!`rMZ>-uCm-gl*Zny|NBa;A4(csSJXB&Ha zEcDoCWF9GkLz33wNulydzkM^!#S;cRzRD@d(ii^O_RMdu0Y*77F}28ARIkkV|gEU(-HsaFCx-A26LQanQ=Z3|21_y3_d_o_coc8Nhj)J11!`)(X zz?3lJ(PHPau6nQ#Y;<-qVI8I@D_r%hG3qhkjnYS)Stn`y|2-Imr{TE+pRS%>|0w6D z0WMoWuruA~GxY0R_AvP>+WnQ3Dew7e?| z7D!I70bo#^znK}TfA@l5Y~Px*Q*b<=Gp97LD9a!r4Kw2MY&%quYKfK>&%}b`xNQw- zaGpMu%gy7{bH6zrPWWcRh?^~MZD}!IYN{kEE35x`v)-t$JWMDuxe>B6Nt(cwJ7G2; zkm;A=!f^6%f50jo9ejACQExUefks#`B{1NEzV5SSm)Re$QgM^=K$GVAutNTD-zDs# z2LBi<4B8CgGG)f8saepVX9-u%A5W4CO@>l;vD51yAj5l7F)#~Cf-{Y>rTg}GGgtm2 zuqFDI+nSUv?SBhx`MO>?_xaz@7C-nm++(oN7Jga-kJF2wiT)@v)52YyE(a-ED%Zv! z5&D~>_5>(&rM{u->1CH)jmy2`&fb3$!>>7S{QTkJmpPfYl<5I6>f~JTc~LTP50{OO z8fRv13F0OEz)tw_D`JxoujpZuTJ$AxUU&Q0w4DY@T97w7<^QnFmc$vB74{eF$^)?A zza^YBNdpl~H8tUZk*6nBUwAq%OsvfqCJe`0WXzr+!@r?tE>r=p?i0LUs2b;cK2ydf z3I|`9>Q!0!Vzd_Eg=0lqk`T|9;u@s`Y1m-Ws$5qXat<=`1;_50 zX9|j=1RICH-$(C&g%9TCHb`m0grBGM{|bEhWM`)lbt%#lVqv`592qQL*9o;qr;ByK z+1*Rx|*S4QRMZwx|99!F$j`lH|lpe~k&hVT%{b-KC(iIeQr;H3Eg&zw``~nSA?q2$1LBA}04d z@-u27z^1xVgbr$@C7y@Ua#vB1AH1SEKACu+A!r~qIe6h(7Lu$#DW?B|l|gV~hMu*U zM@#Xi7})CT+aLiUco3ox4A8!{4ko_Qw~lOFD;`H&i$yG-2LiN47{ea?Me<<@BKd= zB{LJB+lp~zomNTe)uqY5u>fK6%4d6h$;sC#Z;(KuSbokQ);|0js$y9A%Gz!!>lI$r zFK$j9zV_Sv{^>4T)qh~Sv$dHwl>I1aSlAk&l^+hB?M{sV=gfxLj~+MwQ2go6hZMfM zi%wdF(f*kEg>RM%vHXWI@XaoNOUoDJG&Eez`wY?ioMVXkt)l3DG}`o+CSm0`A%F@{ zVZmI8pt^(5B(lq-rt5GHW1w8tF;tTQf5p{c<=m&NXh)$JG$9g9ni4nUuU|T z4Ozg6|NA(@FACoDqY)9MI6_1nYsXZb8REf`6%L}HX5+`4?U{b}?`*I*7l7peB+JOq z%^>9CSVTk|ta5%c_>r|lY=U19EdwubAJGssTLFOV-5EIMYVEtD_drC-hp*m(yq3^7a)G;% zKO)0Mm;-%>7P!-}-{VPx#{5_4>S#Q6E0`1*<(I#cO44o{|6A_`!ebCM2=rNcGM_fo zNuL>Dfw5>XE@=N+@Q^4E`@ht?sO09+&x%=tA94TNpxym&K6VL9S76I+>rb{ zK9e=GJ@UQN>7Qq28X6sSj2xB=KRk@~5?0((JT&!`%04deE&lq28CO6f{BTp;IEu;3 z;xeL%0>^66AG0%2VmWBH8@WL#EdxWIX$3AXP7n zT)5oML{xTQGbcy*c8yiHu`!;hA1%paBA`RhdQsPHEl`FE1s$W|VMJoZWN@5Bu+n-F zOV5+}VAEgny?S)`(x26KXh}-r!~LF4UE))Cs^yuvE?U}7TH5V5zf7e0qIw0js_tEG zd2kjuOa|NJ1v@IrJ`HNu8V`go)bU64Zsq1;6>9e^y+~mlP{ffAyS9})Q_bKW0pP|- zipxsK9lzuF)Ht$4m~kuDo`;T*ow2RrPsd)qLL4ksy~V{M^`lnmu+J%M^z>WDaU80s zypvfLMC)UCaODQDl|fX>%AtEGi z+G)e$-15D?obkm7x3RG{GWNLKtCCJ}*)Evm1(X~U4`kmbOlY>+E;}h{p(-v;Tx)H0 zThnpH7b+T$$i`YuY4o^qY#fh7B zaa_Y(+$CLA!H6t8(((bD?JeKTxh*c68eAp9$eT?12$JeE#l+In)6X0=CT29~2o4rY zso7cN_yq+Rq?DC2xY0oB1Tav;7BDEd4AL`g*xkxT5D|H@zduxe66)x3y?DP)jMonN z65H^_;3$ewyf2r9H7uELqNk%Hc?c^k)MI;qo6`@VA5(oP&YgWzQyLWNm#YzgK!}+w zx8gbHpiZCW60DPXoJ#65+S?lw2L^TP&7!iaE|AGnIvCaN6QeSD%bh0j0GgZ(g$Ah> z2{^3!2Rwbz3Z<6TQ6yjze3|w#U+w0}6COVPY!)rYook1r`hk!TGF@H4J{fsAUAu?7 zVuADN0rRP3x2>0ZqOklj3=DTuHc%`q=nB+~9*+-SY2}XtmzpYwOKfI#ZaJr#7&A3H zZ}E{A;HK7@*{x+csxaR9g|%NKMR$I;c^t}SFI zuB`5~U3Z|&FcHDpfQLuWnVc`jgh|91=uArVLQ_r0Jv$-(^v93cJO*5TBV^YwCI?B4 zlG8~4+uAA9YUC%10qyPV0HtS)k}7>)Zn85e$`28`9anO_0;Of=i?CVuoa^yb|Rc25jm)1WB&tx$zHl1|XT-)E8 zQC8c)C7M3L4(r18^%K4tl?G&D?nff);IN;Z9Busybm|4uq{Gq(Tu`>v$+I1RYc$OH zYriuvXmbAJ-IeURA0;nzb=F1Bx#b~ZFtjCT{9M>nQB*d>5p`-%Zek|a zEjo=qTWzwhJwUm4`aCx`>(oCpP4~2W^W}tA zI3<%HCj%|zl89WWV=oeG{f~>2q0vcIA8lP#?c0vU2cf-v6z>f?+mFwl$rQtbTwsxT zApPpgwpxb==Z8B$D*+tD`SU~`v*!(QL{Y;VF_V+YnjiwBy_u7qonro)YH(-A-O*YM zr-@vmP(wwjO;?sI1}7)L3QwY$IcB|_!-THeyb<^pJ@s;xT|!BCO(zSS`(n&f4nMeD zLkqPa7PA0v<^1*@pxyWhO(q)gSCUv_CFu<*Pv$q5|mY%l4DUGs+|i z2Y*C9&W31AWCN8bVPa;sc*js;&B2&_eqSG_w9u%>!_6nx3y-6VrhGnriR&A>tc-q- z!*>H$%fHzb3=CYt5D~mMzr?D16rK3TrHOqL_g~3tvi~Hnl_skEn;m8QLOt=nebXQh zBX14FW6c){JlAV6FR!ki6LZJg9{o;-F6vFLQwP}J`q zb3Zzfe`Y)~=ybI^a~39WJbJwLbYoB>H%T1hI{<^GQDHgUzf#m4{i!cbw|;cL*GnDV zjH?s6{W78VAO)V|wsJGMutKYBu}4V70D&qW`_=y=IkDb;AfCDo0!-kTk`lRQ&Cj+q zGjbh((jFlo@frT^nko*9L zyFw}xSTFRYtY7_x9(!C3y{@vvJ4rm6L~tJA3iwv_Q;f&@6la{5Q? z&*SNnp_AP`>7c;Sy#@0SevfFb(;_$*)-0p0aL_+a{#X+Lxlp^g`F|eijnZ?!EtTso z{cH97H{&4C*O}#i?G3iV_HUzNq4U_SfzMVJr-#Seaf9=Y=8JA!G6@7H6KY^(EtRt? z{sSJgCt-JMtnd)X`ez4c=hN|AITjW$9vLYq8L6cUu}s&fFO(BB(g8A=^!y+pA+37u z;_8|`9(hqXl>xW>XNePh`gWEMq0%t7eBZO{Vf)XY=%2SmFK3^Effb2}7j&?JppOBU zF8-PoUR1;^KhHkQ*Ee1zUhm=~I-&PlhVat{XBWx%gr>O)>CyT6KUkjnR3sr8<>ghQ zV_ov`cqC*(4D7brZUTO72CTBK-&=<3S;yvvgAkj4MJH61)!)k4kN+$go{^D~mVSv- zg92|k%hIV^{=MFLr00b{M?;7)W^>E)pr7}k)myY^x`dTZ>c625H`v6!8 zA@5FWG+X(UdtOHK`{OmrPhGk~uICLK$t$xnclR|Lo$~QuaFAMIt;zoU&)eJIKY#8% z+;e-Z_b&?GFu8iihvjYQ;g*!A5@Jxu6ujtlT%j_aG3-71qteYCl2_uN`2ng^9#K9*qte&6Nq?GnA2Rfj>x^IA)(zm}k zkJ1~oG}3)=TSuU>wK+<*J4j$=#s||xaIPlK(u6DLD@#d8gq7l;eQ$k2rI@dhHX4y> zBwSIkuzr;2=1vO^(KEC@u*iwN_FYck4�URqmeC)^-E<7b2pZ0j5d-Yap0+U|`Km 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 diff --git a/Doc/library/types.rst b/Doc/library/types.rst index d7b14e7a3d9a..ff75de1ef555 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -281,15 +281,23 @@ Additional Utility Classes and Functions .. versionadded:: 3.4 -Coroutines Utility Functions ----------------------------- +Coroutine Utility Functions +--------------------------- .. function:: coroutine(gen_func) - The function transforms a generator function to a :term:`coroutine function`, - so that it returns a :term:`coroutine` object. + This function transforms a :term:`generator` function into a + :term:`coroutine function` which returns a generator-based coroutine. + The generator-based coroutine is still a :term:`generator iterator`, + but is also considered to be a :term:`coroutine` object and is + :term:`awaitable`. However, it may not necessarily implement + the :meth:`__await__` method. - *gen_func* is modified in-place, hence the function can be used as a - decorator. + If *gen_func* is a generator function, it will be modified in-place. + + If *gen_func* is not a generator function, it will be wrapped. If it + returns an instance of :class:`collections.abc.Generator`, the instance + will be wrapped in an *awaitable* proxy object. All other types + of objects will be returned as is. .. versionadded:: 3.5 diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index c73e8862a648..76b3850543a6 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -666,15 +666,9 @@ can be used to create instance variables with different implementation details. Coroutines ========== -.. index:: - statement: async def - statement: async for - statement: async with - keyword: async - keyword: await - .. versionadded:: 3.5 +.. index:: statement: async def .. _`async def`: Coroutine function definition @@ -683,14 +677,23 @@ Coroutine function definition .. productionlist:: async_funcdef: "async" `funcdef` +.. index:: + keyword: async + keyword: await + Execution of Python coroutines can be suspended and resumed at many points -(see :term:`coroutine`.) :keyword:`await` expressions, :keyword:`async for` -and :keyword:`async with` can only be used in their bodies. +(see :term:`coroutine`). In the body of a coroutine, any ``await`` and +``async`` identifiers become reserved keywords; :keyword:`await` expressions, +:keyword:`async for` and :keyword:`async with` can only be used in +coroutine bodies. However, to simplify the parser, these keywords cannot +be used on the same line as a function or coroutine (:keyword:`def` +statement) header. Functions defined with ``async def`` syntax are always coroutine functions, even if they do not contain ``await`` or ``async`` keywords. -It is a :exc:`SyntaxError` to use :keyword:`yield` expressions in coroutines. +It is a :exc:`SyntaxError` to use :keyword:`yield` expressions in +``async def`` coroutines. An example of a coroutine function:: @@ -699,6 +702,7 @@ An example of a coroutine function:: await some_coroutine() +.. index:: statement: async for .. _`async for`: The :keyword:`async for` statement @@ -742,6 +746,7 @@ It is a :exc:`SyntaxError` to use ``async for`` statement outside of an :keyword:`async def` function. +.. index:: statement: async with .. _`async with`: The :keyword:`async with` statement diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 508b4b519cdd..2ca1194c5ee8 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -624,7 +624,7 @@ Callable types a :dfn:`coroutine function`. Such a function, when called, returns a :term:`coroutine` object. It may contain :keyword:`await` expressions, as well as :keyword:`async with` and :keyword:`async for` statements. See - also :ref:`coroutines` section. + also the :ref:`coroutine-objects` section. Built-in functions .. index:: @@ -2264,26 +2264,25 @@ special methods (the special method *must* be set on the class object itself in order to be consistently invoked by the interpreter). -.. _coroutines: +.. index:: + single: coroutine Coroutines ========== -.. index:: - single: coroutine - Awaitable Objects ----------------- -An *awaitable* object can be one of the following: - -* A :term:`coroutine` object returned from a :term:`coroutine function`. +An :term:`awaitable` object generally implements an :meth:`__await__` method. +:term:`Coroutine` objects returned from :keyword:`async def` functions +are awaitable. -* A :term:`generator` decorated with :func:`types.coroutine` - (or :func:`asyncio.coroutine`) decorator. +.. note:: -* An object that implements an ``__await__`` method. + The :term:`generator iterator` objects returned from generators + decorated with :func:`types.coroutine` or :func:`asyncio.coroutine` + are also awaitable, but they do not implement :meth:`__await__`. .. method:: object.__await__(self) @@ -2296,6 +2295,58 @@ An *awaitable* object can be one of the following: .. seealso:: :pep:`492` for additional information about awaitable objects. +.. _coroutine-objects: + +Coroutine Objects +----------------- + +:term:`Coroutine` objects are :term:`awaitable` objects. +A coroutine's execution can be controlled by calling :meth:`__await__` and +iterating over the result. When the coroutine has finished executing and +returns, the iterator raises :exc:`StopIteration`, and the exception's +:attr:`~StopIteration.value` attribute holds the return value. If the +coroutine raises an exception, it is propagated by the iterator. Coroutines +should not directly raise unhandled :exc:`StopIteration` exceptions. + +Coroutines also have the methods listed below, which are analogous to +those of generators (see :ref:`generator-methods`). However, unlike +generators, coroutines do not directly support iteration. + +.. method:: coroutine.send(value) + + Starts or resumes execution of the coroutine. If *value* is ``None``, + this is equivalent to advancing the iterator returned by + :meth:`__await__`. If *value* is not ``None``, this method delegates + to the :meth:`~generator.send` method of the iterator that caused + the coroutine to suspend. The result (return value, + :exc:`StopIteration`, or other exception) is the same as when + iterating over the :meth:`__await__` return value, described above. + +.. method:: coroutine.throw(type[, value[, traceback]]) + + Raises the specified exception in the coroutine. This method delegates + to the :meth:`~generator.throw` method of the iterator that caused + the coroutine to suspend, if it has such a method. Otherwise, + the exception is raised at the suspension point. The result + (return value, :exc:`StopIteration`, or other exception) is the same as + when iterating over the :meth:`__await__` return value, described + above. If the exception is not caught in the coroutine, it propagates + back to the caller. + +.. method:: coroutine.close() + + Causes the coroutine to clean itself up and exit. If the coroutine + is suspended, this method first delegates to the :meth:`~generator.close` + method of the iterator that caused the coroutine to suspend, if it + has such a method. Then it raises :exc:`GeneratorExit` at the + suspension point, causing the coroutine to immediately clean itself up. + Finally, the coroutine is marked as having finished executing, even if + it was never started. + + Coroutine objects are automatically closed using the above process when + they are about to be destroyed. + + Asynchronous Iterators ---------------------- diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 9d3fdf26fc05..d3face7f6a7b 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -390,6 +390,7 @@ on the right hand side of an assignment statement. to sub-generators easy. .. index:: object: generator +.. _generator-methods: Generator-iterator methods ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Objects/genobject.c b/Objects/genobject.c index 40340b487424..3311c4e0e757 100644 --- a/Objects/genobject.c +++ b/Objects/genobject.c @@ -793,11 +793,11 @@ static PyMemberDef coro_memberlist[] = { PyDoc_STRVAR(coro_send_doc, "send(arg) -> send 'arg' into coroutine,\n\ -return next yielded value or raise StopIteration."); +return next iterated value or raise StopIteration."); PyDoc_STRVAR(coro_throw_doc, "throw(typ[,val[,tb]]) -> raise exception in coroutine,\n\ -return next yielded value or raise StopIteration."); +return next iterated value or raise StopIteration."); PyDoc_STRVAR(coro_close_doc, "close() -> raise GeneratorExit inside coroutine."); @@ -908,9 +908,9 @@ coro_wrapper_traverse(PyCoroWrapper *cw, visitproc visit, void *arg) } static PyMethodDef coro_wrapper_methods[] = { - {"send",(PyCFunction)coro_wrapper_send, METH_O, send_doc}, - {"throw",(PyCFunction)coro_wrapper_throw, METH_VARARGS, throw_doc}, - {"close",(PyCFunction)coro_wrapper_close, METH_NOARGS, close_doc}, + {"send",(PyCFunction)coro_wrapper_send, METH_O, coro_send_doc}, + {"throw",(PyCFunction)coro_wrapper_throw, METH_VARARGS, coro_throw_doc}, + {"close",(PyCFunction)coro_wrapper_close, METH_NOARGS, coro_close_doc}, {NULL, NULL} /* Sentinel */ }; -- 2.47.3