U
|
Þ=®dõO ã @ s d Z ddlmZ ddlZddlmZ ddlmZ ddl m
|
Z
|
ddl m Z ddl mZ dd l mZ dd
|
l mZ dd l mZ dd l mZ dd l mZ ddl mZ ddl mZ ejr:ddlZejdejdejf dZ e d¡Z e d¡Z ejeje e f geje ej e f f Z!ejeje ej e f geje e f f Z"edZ#de#_ dZ$G dd dZ%e%dZ&G dd de%Z'G d d d e(Z)G d d d e Z*e) j+Z+dS ) a+ Signals and events.
|
|
A small implementation of signals, inspired by a snippet of Django signal
|
API client code seen in a blog post. Signals are first-class objects and
|
each manages its own receivers and message emission.
|
|
The :func:`signal` function provides singleton behavior for named signals.
|
|
é )Ú annotationsN)Ú defaultdict)Úcontextmanager)Úwarn)ÚWeakValueDictionary)Úannotatable_weakref)Úhashable_identity)Ú IdentityType)Úis_coroutine_function)Ú lazy_property)Ú reference)Úsymbol)Ú WeakTypesÚ
|
T_callable.)ÚboundÚTÚPÚANYzToken for "any sender".c @ s e Zd ZdZeZed dddZed dddZdGdd d
|
d d Zed fdddddddZ dHddddddZ
|
e efddddd d Z e ddd d Z efddd dd!d"Zdd#dd$dd%d&d'd(Zdd)dd*dd%d+d,d-Zddd.d/d0Zddd.d1d2Zdd3d.d4d5Zefddd dd6d7Zd8d8d d9d:d;Zd<d d=d>d?Zd<d d@dAdBZd ddCdDZd ddEdFZdS )IÚSignalzA notification emitter.©Úreturnc C s
|
t ddS )zßEmitted after each :meth:`connect`.
|
|
The signal sender is the signal instance, and the :meth:`connect`
|
arguments are passed through: *receiver*, *sender*, and *weak*.
|
|
.. versionadded:: 1.2
|
|
z"Emitted after a receiver connects.©Údoc©r ©Úself© r úCd:\z\workplace\vscode\pyvenv\venv\Lib\site-packages\blinker/base.pyÚreceiver_connected2 s
|
zSignal.receiver_connectedc C s
|
t ddS )a Emitted after :meth:`disconnect`.
|
|
The sender is the signal instance, and the :meth:`disconnect` arguments
|
are passed through: *receiver* and *sender*.
|
|
Note, this signal is emitted **only** when :meth:`disconnect` is
|
called explicitly.
|
|
The disconnect signal can not be emitted by an automatic disconnect
|
(due to a weakly referenced receiver or sender going out of scope),
|
as the receiver and/or sender instances are no longer available for
|
use at the time this signal would be emitted.
|
|
An alternative approach is available by subscribing to
|
:attr:`receiver_connected` and setting up a custom weakref cleanup
|
callback on weak receivers and senders.
|
|
.. versionadded:: 1.2
|
|
z%Emitted after a receiver disconnects.r r r r r r Úreceiver_disconnected> s z Signal.receiver_disconnectedNú
|
str | NoneÚNone)r r c C s4 |r
|
|| _ i | _d| _tt| _tt| _i | _dS )zt
|
:param doc: optional. If provided, will be assigned to the signal's
|
__doc__ attribute.
|
|
FN)Ú__doc__Ú receiversÚis_mutedr ÚsetÚ _by_receiverÚ
|
_by_senderÚ _weak_senders)r r r r r Ú__init__V s
|
|
zSignal.__init__Tr zt.AnyÚbool)ÚreceiverÚsenderÚweakr c
|
C s~ t |}|r t|| j}||_n|}|tkr2t}nt |}| j ||¡ | j| |¡ | j
|
| |¡ ~|tk r¸|| j kr¸zt|| j }||_ W n tk
|
r¦ Y nX | j ||¡ ~d| jkr | jjr z| jj| |||d W n4 tk
|
r } z| ||¡ |W 5 d}~X Y nX tjrz| tk rzztj| |||d W n4 tk
|
rx } z| ||¡ |W 5 d}~X Y nX |S )aa Connect *receiver* to signal events sent by *sender*.
|
|
:param receiver: A callable. Will be invoked by :meth:`send` with
|
`sender=` as a single positional argument and any ``kwargs`` that
|
were provided to a call to :meth:`send`.
|
|
:param sender: Any object or :obj:`ANY`, defaults to ``ANY``.
|
Restricts notifications delivered to *receiver* to only those
|
:meth:`send` emissions sent by *sender*. If ``ANY``, the receiver
|
will always be notified. A *receiver* may be connected to
|
multiple *sender* values on the same Signal through multiple calls
|
to :meth:`connect`.
|
|
:param weak: If true, the Signal will hold a weakref to *receiver*
|
and automatically disconnect when *receiver* goes out of scope or
|
is garbage collected. Defaults to True.
|
|
r )r+ r, r- N)Z receiver_argZ
|
sender_argZweak_arg)r r Ú_cleanup_receiverÚ receiver_idr ÚANY_IDr# Ú
|
setdefaultr' Úaddr& r( Ú_cleanup_senderÚ sender_idÚ TypeErrorÚ__dict__r ÚsendÚ
|
disconnect) r r+ r, r- r/ Ú receiver_refr4 Ú
|
sender_refÚer r r Úconnectj sV
|
ÿ
|
ÿ
|
zSignal.connectFz$t.Callable[[T_callable], T_callable])r, r- r c s ddd fdd }|S )aK Connect the decorated function as a receiver for *sender*.
|
|
:param sender: Any object or :obj:`ANY`. The decorated function
|
will only receive :meth:`send` emissions sent by *sender*. If
|
``ANY``, the receiver will always be notified. A function may be
|
decorated multiple times with differing *sender* values.
|
|
:param weak: If true, the Signal will hold a weakref to the
|
decorated function and automatically disconnect when *receiver*
|
goes out of scope or is garbage collected. Unlike
|
:meth:`connect`, this defaults to False.
|
|
The decorated function will be invoked by :meth:`send` with
|
`sender=` as a single positional argument and any ``kwargs`` that
|
were provided to the call to :meth:`send`.
|
|
|
.. versionadded:: 1.1
|
|
r )Úfnr c s | ¡ | S ©N)r< )r= ©r r, r- r r Ú decoratorÈ s z%Signal.connect_via.<locals>.decoratorr )r r, r- r@ r r? r Ú connect_via° s zSignal.connect_viaz
|
t.Callablez t.Generator[(None, None, None)])r+ r, r c
|
c sZ | j ||dd z
|
dV W n0 tk
|
rJ } z| |¡ |W 5 d}~X Y n X | |¡ dS )ah Execute a block with the signal temporarily connected to *receiver*.
|
|
:param receiver: a receiver callable
|
:param sender: optional, a sender to filter on
|
|
This is a context manager for use in the ``with`` statement. It can
|
be useful in unit tests. *receiver* is connected to the signal for
|
the duration of the ``with`` block, and will be disconnected
|
automatically when exiting the block:
|
|
.. code-block:: python
|
|
with on_ready.connected_to(receiver):
|
# do stuff
|
on_ready.send(123)
|
|
.. versionadded:: 1.1
|
|
F)r, r- N)r< Ú Exceptionr8 )r r+ r, r; r r r Ú connected_toÎ s
|
|
zSignal.connected_toc
|
c sJ d| _ z6z
|
dV W n& tk
|
r8 } z|W 5 d}~X Y nX W 5 d| _ X dS )z\Context manager for temporarily disabling signal.
|
Useful for test purposes.
|
TFN)r$ rB )r r; r r r Úmutedî s
|
z Signal.mutedzt.ContextManager[None]c C s t dt | ||¡S )ag An alias for :meth:`connected_to`.
|
|
:param receiver: a receiver callable
|
:param sender: optional, a sender to filter on
|
|
.. versionadded:: 0.9
|
|
.. versionchanged:: 1.1
|
Renamed to :meth:`connected_to`. ``temporarily_connected_to`` was
|
deprecated in 1.2 and will be removed in a subsequent version.
|
|
zAtemporarily_connected_to is deprecated; use connected_to instead.)r ÚDeprecationWarningrC )r r+ r, r r r Útemporarily_connected_toû s
|
þz Signal.temporarily_connected_to)Ú_async_wrapperzAsyncWrapperType | Nonez list[tuple[t.Callable, t.Any]])r, rG Úkwargsr c O sf | j r
|
g S | |¡}g }| |¡D ]>}t|rF|dkr>td||}||f|}| ||f¡ q"|S )a Emit this signal on behalf of *sender*, passing on ``kwargs``.
|
|
Returns a list of 2-tuples, pairing receivers with their return
|
value. The ordering of receiver notification is undefined.
|
|
:param sender: Any object or ``None``. If omitted, synonymous
|
with ``None``. Only accepts one positional argument.
|
:param _async_wrapper: A callable that should wrap a coroutine
|
receiver and run it when called synchronously.
|
|
:param kwargs: Data to be sent to receivers.
|
Nz#Cannot send to a coroutine function©r$ Ú_extract_senderÚ receivers_forr
|
Ú RuntimeErrorÚappend)r rG r, rH Úresultsr+ Úresultr r r r7 s
|
z Signal.send)Ú _sync_wrapperzSyncWrapperType | None)r, rP rH r c Ï sl | j r
|
g S | |¡}g }| |¡D ]D}t|sF|dkr>td||}||f|I dH }| ||f¡ q"|S )a Emit this signal on behalf of *sender*, passing on ``kwargs``.
|
|
Returns a list of 2-tuples, pairing receivers with their return
|
value. The ordering of receiver notification is undefined.
|
|
:param sender: Any object or ``None``. If omitted, synonymous
|
with ``None``. Only accepts one positional argument.
|
:param _sync_wrapper: A callable that should wrap a synchronous
|
receiver and run it when awaited.
|
|
:param kwargs: Data to be sent to receivers.
|
Nz'Cannot send to a non-coroutine functionrI )r rP r, rH rN r+ rO r r r Ú
|
send_async0 s
|
zSignal.send_async)r, r c C sn | j s.|r*t|dkr*tdt| dg S t|dkr@d }n*t|dkrbtdt| dn|d }|S )NTé z-send() accepts only one positional argument, z givenr )r# Úlenr5 ©r r, r r r rJ P s ÿ ÿzSignal._extract_senderc C s2 | j s
|
dS | jt rdS |tkr$dS t|| jkS )zôTrue if there is probably a receiver for *sender*.
|
|
Performs an optimistic check only. Does not guarantee that all
|
weakly referenced receivers are still alive. See
|
:meth:`receivers_for` for a stronger search.
|
|
FT)r# r' r0 r r rT r r r Úhas_receivers_forg s
|
zSignal.has_receivers_forz9t.Generator[t.Callable | annotatable_weakref, None, None]c c s | j rt|}|| jkr.| jt | j| B }n| jt ¡ }|D ]J}| j |¡}|dkrZq@t|tr| }|dkr| |t¡ q@|}|V q@dS )z2Iterate all live receivers listening for *sender*.N) r# r r' r0 ÚcopyÚgetÚ
|
isinstancer Ú _disconnect)r r, r4 Úidsr/ r+ Ústrongr r r rK w s
|
|
zSignal.receivers_forc C sR |t krt}nt|}t|}| ||¡ d| jkrN| jjrN| jj| ||d dS )a Disconnect *receiver* from this signal's events.
|
|
:param receiver: a previously :meth:`connected<connect>` callable
|
|
:param sender: a specific sender to disconnect from, or :obj:`ANY`
|
to disconnect from all senders. Defaults to ``ANY``.
|
|
r )r+ r, N)r r0 r rY r6 r r# r7 )r r+ r, r4 r/ r r r r8 s
|
ÿþzSignal.disconnectr )r/ r4 r c C sd |t kr@| j |d¡r0| j ¡ D ]}| |¡ q | j |d ¡ n | j| |¡ | j| |¡ d S )NF)r0 r& Úpopr' ÚvaluesÚdiscardr# )r r/ r4 Úbucketr r r rY ¥ s zSignal._disconnectr )r9 r c C s | t t|j¡t¡ dS )z'Disconnect a receiver from all senders.N)rY ÚtÚcastr r/ r0 )r r9 r r r r. ¯ s zSignal._cleanup_receiver)r: r c C sP t t|j¡}|tkst| j |d¡ | j |d¡D ]}| j |
|
|¡ q6dS )z'Disconnect all receivers from a sender.Nr ) r` ra r r4 r0 ÚAssertionErrorr( r\ r' r& r^ )r r: r4 r/ r r r r3 ³ s
|
zSignal._cleanup_senderc C s< | j | jfD ]*}t| ¡ D ]\}}|s | |d¡ q q dS )ar Prune unused sender/receiver bookkeeping. Not threadsafe.
|
|
Connecting & disconnecting leave behind a small amount of bookkeeping
|
for the receiver and sender values. Typical workloads using Blinker,
|
for example in most web apps, Flask, CLI scripts, etc., are not
|
adversely affected by this bookkeeping.
|
|
With a long-running Python process performing dynamic signal routing
|
with high volume- e.g. connecting to function closures, "senders" are
|
all unique object instances, and doing all of this over and over- you
|
may see memory usage will grow due to extraneous bookkeeping. (An empty
|
set() for each stale sender/receiver pair.)
|
|
This method will prune that bookkeeping away, with the caveat that such
|
pruning is not threadsafe. The risk is that cleanup of a fully
|
disconnected receiver/sender pair occurs while another thread is
|
connecting that same pair. If you are in the highly dynamic, unique
|
receiver/sender situation that has lead you to this method, that
|
failure mode is perhaps not a big deal for you.
|
N)r' r& ÚlistÚitemsr\ )r ÚmappingZ_idr_ r r r Ú_cleanup_bookkeeping» s zSignal._cleanup_bookkeepingc C s, | j ¡ | j ¡ | j ¡ | j ¡ dS )z4Throw away all signal state. Useful for unit tests.N)r( Úclearr# r' r& r r r r Ú _clear_stateÕ s
|
|
|
zSignal._clear_state)N)F)Ú__name__Ú
|
__module__Ú __qualname__r" r r r r r) r< rA r rC rD rF r7 rQ rJ rU rK r8 rY r. r3 rf rh r r r r r + s@ ÿG ÿ ÿ ÿý#ý
|
r a Sent by a :class:`Signal` after a receiver connects.
|
|
:argument: the Signal that was connected to
|
:keyword receiver_arg: the connected receiver
|
:keyword sender_arg: the sender to connect to
|
:keyword weak_arg: true if the connection to receiver_arg is a weak reference
|
|
.. deprecated:: 1.2
|
|
As of 1.2, individual signals have their own private
|
:attr:`~Signal.receiver_connected` and
|
:attr:`~Signal.receiver_disconnected` signals with a slightly simplified
|
call signature. This global signal is planned to be removed in 1.6.
|
|
c @ s2 e Zd ZdZd ddddddZdd d
|
d ZdS ) Ú NamedSignalz%A named generic notification emitter.NÚstrr r! ©Únamer r c C s t | |¡ || _d S r> )r r) ro )r ro r r r r r) ô s zNamedSignal.__init__r c C s$ t | ¡}|d d
d| jdS )Néÿÿÿÿz; ú>)r Ú__repr__ro )r Úbaser r r rr ú s
|
zNamedSignal.__repr__)N)ri rj rk r" r) rr r r r r rl ñ s rl c @ s$ e Zd ZdZd ddddddZdS )
|
Ú Namespacez%A mapping of signal names to signals.Nrm r rl rn c C s: z
|
| | W S t k
|
r4 | |t||¡}| Y S X dS ©zReturn the :class:`NamedSignal` *name*, creating it if required.
|
|
Repeated calls to this function will return the same signal object.
|
|
N©ÚKeyErrorr1 rl ©r ro r rO r r r Úsignal s
|
|
zNamespace.signal)N©ri rj rk r" ry r r r r rt ÿ s rt c @ s$ e Zd ZdZd ddddddZdS )
|
Ú WeakNamespacea- A weak mapping of signal names to signals.
|
|
Automatically cleans up unused Signals when the last reference goes out
|
of scope. This namespace implementation exists for a measure of legacy
|
compatibility with Blinker <= 1.2, and may be dropped in the future.
|
|
.. versionadded:: 1.3
|
|
Nrm r rl rn c C s: z
|
| | W S t k
|
r4 | |t||¡}| Y S X dS ru rv rx r r r ry s
|
|
zWeakNamespace.signal)Nrz r r r r r{ s
|
r{ ),r" Ú
|
__future__r Útypingr` Ú collectionsr Ú
|
contextlibr Úwarningsr Úweakrefr Zblinker._utilitiesr r r r
|
r r r r Ú TYPE_CHECKINGZtyping_extensionsÚteÚTypeVarÚCallableÚAnyr r Z ParamSpecr Ú AwaitableZAsyncWrapperTypeZSyncWrapperTyper r0 r r rl Údictrt r{ ry r r r r Ú<module> sF
|
|
** 5ÿ
|
