CQ9@sdZddlmZddlmZddlmZmZmZm Z m Z m Z m Z e dZ de _dZGdddeZed ZGd d d eZGd d d eZGdddeZejZdS)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. )warn)WeakValueDictionary) WeakTypescontextmanager defaultdicthashable_identity lazy_property referencesymbolANYzToken for "any sender".c@seZdZdZeZeddZeddZdddZed d d Z d d dZ e eddZ eddZ ddZddZddZeddZddZddZdd Zd!d"ZdS)#SignalzA notification emitter.cCs tddS)zEmitted 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 docz"Emitted after a receiver connects.)r )selfr./usr/lib/python3/dist-packages/blinker/base.pyreceiver_connected%s zSignal.receiver_connectedcCs tddS)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 r z%Emitted after a receiver disconnects.)r )rrrrreceiver_disconnected1szSignal.receiver_disconnectedNcCsC|r||_i|_tt|_tt|_i|_dS)zt :param doc: optional. If provided, will be assigned to the signal's __doc__ attribute. N)__doc__ receiversrset _by_receiver _by_sender _weak_senders)rr rrr__init__Is   zSignal.__init__TcCst|}|r0t||j}||_n|}|tkrKt}n t|}|jj|||j|j ||j |j |~|tk r||j kryt||j }||_ Wntk rYnX|j j||~d|jkrY|jjrYy&|jj|d|d|d|Wn|j||YnXtjr|tk ry#tj|d|d|d|Wn|j||YnX|S)aaConnect *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. rreceiversenderweakZ receiver_argZ sender_argZweak_arg)rr _cleanup_receiver receiver_idr ANY_IDr setdefaultraddrr_cleanup_sender sender_id TypeError__dict__rsend disconnect)rrrrr receiver_refr# sender_refrrrconnect\sP           zSignal.connectFcsfdd}|S)aKConnect 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 csj||S)N)r*)fn)rrrrr decoratorsz%Signal.connect_via..decoratorr)rrrr,r)rrrr connect_viaszSignal.connect_viac csN|j|d|ddy dVWn|j|YnX|j|dS)aExecute 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: .. testsetup:: from __future__ import with_statement from blinker import Signal on_ready = Signal() receiver = lambda sender: None .. testcode:: with on_ready.connected_to(receiver): # do stuff on_ready.send(123) .. versionadded:: 1.1 rrFN)r*r')rrrrrr connected_tos  zSignal.connected_tocCstdt|j||S)a_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 removed in a subsequent version. zAtemporarily_connected_to is deprecated; use connected_to instead.)rDeprecationWarningr.)rrrrrrtemporarily_connected_tos zSignal.temporarily_connected_tocstdkrdn5tdkrFtdtn d|js]gSfdd|jDSdS)aEmit 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 \*\*kwargs: Data to be sent to receivers. rNz5send() accepts only one positional argument, %s givencs%g|]}||fqSrr).0r)kwargsrrr s zSignal.send..)lenr$r receivers_for)rrr3r)r3rrr&s   z Signal.sendcCsA|js dS|jtrdS|tkr.dSt||jkS)zTrue 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)rrrr r)rrrrrhas_receivers_for s   zSignal.has_receivers_forccs|jrt|}||jkr?|jt|j|B}n|jtj}xq|D]i}|jj|}|dkrqYt|tr|}|dkr|j|tqY|}|VqYWdS)z2Iterate all live receivers listening for *sender*.N) rrrrcopyget isinstancer _disconnect)rrr#ZidsrrZstrongrrrr6s"       zSignal.receivers_forcCsx|tkrt}n t|}t|}|j||d|jkrt|jjrt|jj|d|d|dS)aDisconnect *receiver* from this signal's events. :param receiver: a previously :meth:`connected` callable :param sender: a specific sender to disconnect from, or :obj:`ANY` to disconnect from all senders. Defaults to ``ANY``. rrrN)r rrr;r%rrr&)rrrr#rrrrr'3s     zSignal.disconnectcCsv|tkr^|jj|drHx$|jjD]}|j|q1W|jj|dn|j|j|dS)NF)rrpoprvaluesdiscardr)rrr#Zbucketrrrr;Is  zSignal._disconnectcCs|j|jtdS)z'Disconnect a receiver from all senders.N)r;rr)rr(rrrrRszSignal._cleanup_receivercCsf|j}|tkst|jj|dx1|jj|fD]}|j|j|qDWdS)z'Disconnect all receivers from a sender.N)r#rAssertionErrorrr<rrr>)rr)r#rrrrr"Vs  zSignal._cleanup_sendercCs8|jj|jj|jj|jjdS)z4Throw away all signal state. Useful for unit tests.N)rclearrrr)rrrr _clear_state^s   zSignal._clear_state)__name__ __module__ __qualname__rr rrrrr*r-rr.r0r&r7r6r'r;rr"rArrrrr s$  D$     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@s1eZdZdZdddZddZdS) NamedSignalz%A named generic notification emitter.NcCstj||||_dS)N)r rname)rrFr rrrr{szNamedSignal.__init__cCs*tj|}d|dd|jfS)Nz%s; %r>r1)r __repr__rF)rbaserrrrHszNamedSignal.__repr__)rBrCrDrrrHrrrrrExs rEc@s%eZdZdZdddZdS) Namespacez%A mapping of signal names to signals.Nc Cs>y ||SWn+tk r9|j|t||SYnXdS)zReturn the :class:`NamedSignal` *name*, creating it if required. Repeated calls to this function will return the same signal object. N)KeyErrorr rE)rrFr rrrsignals  zNamespace.signal)rBrCrDrrLrrrrrJs rJc@s%eZdZdZdddZdS) WeakNamespaceaA 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. Nc Cs>y ||SWn+tk r9|j|t||SYnXdS)zReturn the :class:`NamedSignal` *name*, creating it if required. Repeated calls to this function will return the same signal object. N)rKr rE)rrFr rrrrLs  zWeakNamespace.signal)rBrCrDrrLrrrrrMs rMN)rwarningsrweakrefrZblinker._utilitiesrrrrrr r r robjectr rrEdictrJrMrLrrrr s4  I