AHjV% UdZddlmZddlZddlZddlZddlZddlmZm Z ddl m Z ddl m Z ddlmZddlmZmZmZmZdd lmZdd lmZdd lmZmZmZdd lmZej>e Z!erdd lm"Z"ee#e$ddddddfZ%de&d<e dgdfZ'GddZ(d/dZ)e GddZ*GddZ+GddZ,GddZ-GddZ.GddZ/Gd dZ0Gd!d"eZ1d0d#Z2 d1d$Z3Gd%d&eZ4Gd'd(e4Z5Gd)d*ejlZ7Gd+d,e5Z8Gd-d.e5Z9y)2a= Redis Keyspace Notifications support for redis-py. This module provides utilities for subscribing to and parsing Redis keyspace notifications. Keyspace notifications allow clients to receive events when keys are modified in Redis. Note: Keyspace notifications must be enabled on the Redis server via the ``notify-keyspace-events`` configuration option. This is a server-side configuration that should be done by your infrastructure/operations team. See the Redis documentation for details: https://redis.io/docs/latest/develop/pubsub/keyspace-notifications/ Standalone Redis Example: >>> from redis import Redis >>> from redis.keyspace_notifications import ( ... KeyspaceNotifications, ... KeyspaceChannel, ... EventType, ... ) >>> >>> r = Redis() >>> # Server must have notify-keyspace-events configured (e.g., "KEA") >>> ksn = KeyspaceNotifications(r) >>> >>> # Subscribe using Channel class (patterns auto-detected) >>> channel = KeyspaceChannel("user:*") >>> ksn.subscribe(channel) >>> >>> # Or use convenience methods for specific event types >>> ksn.subscribe_keyevent(EventType.SET) >>> >>> for notification in ksn.listen(): ... print(f"Key: {notification.key}, Event: {notification.event_type}") Redis Cluster Example: >>> from redis.cluster import RedisCluster >>> from redis.keyspace_notifications import ( ... ClusterKeyspaceNotifications, ... KeyspaceChannel, ... EventType, ... ) >>> >>> rc = RedisCluster(host="localhost", port=7000) >>> # Server must have notify-keyspace-events configured (e.g., "KEA") >>> ksn = ClusterKeyspaceNotifications(rc) >>> >>> # Subscribe using Channel class (patterns auto-detected) >>> channel = KeyspaceChannel("user:*") >>> ksn.subscribe(channel) >>> >>> # Or use convenience methods for specific event types >>> ksn.subscribe_keyevent(EventType.SET) >>> >>> for notification in ksn.listen(): ... print(f"Key: {notification.key}, Event: {notification.event_type}") ) annotationsN)ABCabstractmethod)Callable) dataclass)Enum) TYPE_CHECKINGAnyClassVarUnion)Redis) RedisCluster)ConnectionError RedisError TimeoutError)safe_str) TypeAliasKeyspaceChannelKeyeventChannelSubkeyspaceChannelSubkeyeventChannelSubkeyspaceitemChannelSubkeyspaceeventChannelrChannelTKeyNotificationcXeZdZdZdZdZdZdZdZdZ dZ d Z d Z d Z d Zd ZdZdZdZdZdZdZdZdZdZdZdZdZdZdZdZdZdZ dZ!d Z"d!Z#d"Z$d#Z%d$Z&d%Z'd&Z(d'Z)d(Z*d)Z+d*Z,d+Z-d,Z.d-Z/d.Z0d/Z1d0Z2d1Z3d2Z4d3Z5d4Z6d5Z7d6Z8d7Z9d8Z:d9Z;d:Zd=Z?d>Z@d?ZAd@ZBdAZCdBZDdCZEdDZFdEZGdFZHdGZIdHZJdIZKdJZLdKZMdLZNdMZOdNZPdOZQdPZRdQZSdRZTdSZUyT)U EventTypez Common Redis keyspace notification event type constants. These are provided for convenience and IDE autocomplete. You can use any string as an event type - new Redis events will work without needing library updates. setsetexsetnxsetrangeincrincrby incrbyfloatdecrdecrbyappenddelunlinkrename rename_from rename_tocopy_tomoverestoreexpireexpireatpexpire pexpireatexpiredpersistevictedlpushrpushlpoprpoplinsertlsetltrimlmoveblpopbrpopblmovesaddsremspopsmove sinterstore sunionstore sdiffstorezaddzincrbyzremzremrangebyrankzremrangebyscorezremrangebylexzpopminzpopmaxbzpopminbzpopmax zinterstore zunionstore zdiffstore zrangestorehsethsetnxhdelhincrby hincrbyfloatxaddxtrimxdelz xgroup-createzxgroup-createconsumerzxgroup-delconsumerzxgroup-destroyz xgroup-setidxsetidxclaim xautoclaim xreadgroupnew sortstoregetexgetdelsetifgtsetifltsetifeqsetifneN)V__name__ __module__ __qualname____doc__SETSETEXSETNXSETRANGEINCRINCRBY INCRBYFLOATDECRDECRBYAPPENDDELUNLINKRENAME RENAME_FROM RENAME_TOCOPY_TOMOVERESTOREEXPIREEXPIREATPEXPIRE PEXPIREATEXPIREDPERSISTEVICTEDLPUSHRPUSHLPOPRPOPLINSERTLSETLTRIMLMOVEBLPOPBRPOPBLMOVESADDSREMSPOPSMOVE SINTERSTORE SUNIONSTORE SDIFFSTOREZADDZINCRBYZREMZREMRANGEBYRANKZREMRANGEBYSCOREZREMRANGEBYLEXZPOPMINZPOPMAXBZPOPMINBZPOPMAX ZINTERSTORE ZUNIONSTORE ZDIFFSTORE ZRANGESTOREHSETHSETNXHDELHINCRBY HINCRBYFLOATXADDXTRIMXDEL XGROUP_CREATEXGROUP_CREATECONSUMERXGROUP_DELCONSUMERXGROUP_DESTROY XGROUP_SETIDXSETIDXCLAIM XAUTOCLAIM XREADGROUPNEW SORTSTOREGETEXGETDELSETIFGTSETIFLTSETIFEQSETIFNET/root/tools/cai/cai_env/lib/python3.12/site-packages/redis/keyspace_notifications.pyrros C E EH D FK D F F C F FKIG DGFHGIGGG E E D DG D E E E E F D D D EKKJ DG D'O)%NGGHHKKJK D F DG!L D E D#M3-%N!L F FJJ CI E FGGGGrrcg}d}|t|krk|jd|}t|||}|dz}|j||||z||z}|t|kr ||dk(r|dz }|t|krk|S)zParse a length-prefixed subkey list. The wire format is ``:[,:...]``. Returns: A list of subkey strings. r:,)lenindexintr')ssubkeysposcolonlengthstarts r_parse_length_prefixed_subkeysrsG C A,S!Qs5\" q01fn Q>> message = { ... 'type': 'pmessage', ... 'pattern': '__keyspace@0__:user:*', ... 'channel': '__keyspace@0__:user:123', ... 'data': 'set' ... } >>> notification = KeyNotification.from_message(message) >>> notification.key 'user:123' >>> notification.event_type 'set' Ntype)messagepmessagerr)get try_parse)clsr key_prefixmsg_typerrs r from_messagezKeyNotification.from_message+sbB ?;;v& 2 2++i({{6" ?dl}}WdJ77rcTt|}t|}|j|||S)a Try to parse a channel and data into a KeyNotification. This is a lower-level method that takes the channel and data directly, useful when working with callback-based subscription handlers. Args: channel: The channel name (e.g., "__keyspace@0__:mykey") data: The message data (event type for keyspace, key for keyevent) key_prefix: Optional prefix to filter and strip from keys Returns: A KeyNotification if valid, None otherwise. )r_parse)rrrrs rrzKeyNotification.try_parse[s**7#~zz'444rc |r t|nd}|jj|}|rW|j\}}|dk7r t |nd}|}|r |j |sy|t |d}|||||d|S|jj|}|rW|j\}}|dk7r t |nd}|}|r |j |sy|t |d}|||||d|S|jj|}|r}|j\}}|dk7r t |nd}|jd} |d| }t|| dzd} |r |j |sy|t |d}|||||d|| S|jj|}|r|j\}}|dk7r t |nd}|jd } t |d| } | dz} || | | z}| | zdz}t||d} |r |j |sy|t |d}|||||d|| S|jj|}|rw|j\}}|dk7r t |nd}|jd }|d|}||dzd}|}|r |j |sy|t |d}|||||d||g S|jj|}|r|j\}}|dk7r t |nd}|jd} |d| }|| dzd}t|} |r |j |sy|t |d}|||||d|| Sy) zInternal parsing logic.N*T)rrrrrrF|r)rrrrrrrr )rrmatchgroupsr startswithrrrrrrrr)rrrrrdb_strrrrpipe_idxr colon_idxkey_len key_start subkeys_startkey_and_subkey newline_idxsubkey event_and_keys rrzKeyNotification._parseus.8Xj)T %%++G4 ,,.KFC&,ms6{HJ~~j1#j/+,%!   %%++G4 !& FJ&,ms6{HC~~j1#j/+,%!!  ((..w7 ,,.KFC&,ms6{Hzz#HixJ4T(Q,.5IJG~~j1#j/+,%!  ((..w7 !& FJ&,ms6{H 3I$z *+G!A Iy9w#67C%/!3M4T-.5IJG~~j1#j/+,%!! ,,227; %*\\^ "FN&,ms6{H(..t4K +.C#K!O$56FJ~~j1#j/+,%!  --33G< $)LLN !FM&,ms6{H$**3/H&y1J1 /C4T:G~~j1#j/+,%!! rcNt|}|jj|S)z.Check if the key starts with the given prefix.)rrr)rprefixs rkey_starts_withzKeyNotification.key_starts_withs!&!xx""6**rr)rzdict[str, Any] | Nonerstr | bytes | NonereturnKeyNotification | None)r str | bytesrr rrr r )rrrrrrr r )rr r r)rkrlrmrnrecompiler__annotations__rrrDOTALLrrrr classmethodrrrrrrrrrs,/9bjj'/+/9bjj'/+2<*2.2<*2.6@RZZ. 627Abjj/73 HOM L IGY*.-8&-8'-8 -8-8^ *. 555' 5 552 *. aaa' a aaF+rcdeZdZUdZdZded<d ddZddZeddZ ddZ dd Z dd Z dd Z y )ra Represents a keyspace notification channel for subscribing to events on keys. Keyspace notifications publish the event type (e.g., "set", "del") as the message when a key matching the pattern is modified. This class can be used directly with subscribe()/psubscribe() as it implements __str__ to return the channel string. Attributes: key_or_pattern: The key or pattern to monitor (use '*' for wildcards) db: The database number (defaults to 0, the only database in Redis Cluster) is_pattern: Whether this channel contains wildcards Examples: >>> channel = KeyspaceChannel("user:123", db=0) >>> str(channel) '__keyspace@0__:user:123' >>> # Pattern subscription (wildcards are auto-detected) >>> channel = KeyspaceChannel("user:*", db=0) >>> str(channel) '__keyspace@0__:user:*' >>> # Use with KeyspaceNotifications >>> notifications = KeyspaceNotifications(redis_client) >>> notifications.subscribe(channel) z __keyspace@ ClassVar[str]PREFIXcJ||_||_|j|_y)z Create a keyspace notification channel. Args: key_or_pattern: The key or pattern to monitor. Use '*' for wildcards. db: The database number. Defaults to 0 (the only database in Redis Cluster). Nkey_or_patterndb_build_channel_string _channel_strrrrs r__init__zKeyspaceChannel.__init__Ds$- 668rcP|j|jd|jSN__:rrrrs rrz%KeyspaceChannel._build_channel_stringP&++twwis4+>+>*?@@rc,t|jSzCCheck if this channel contains wildcards and should use psubscribe. _is_patternrrs r is_patternzKeyspaceChannel.is_patternSs4..//rc|jSrrrs r__str__zKeyspaceChannel.__str__X   rc<d|jd|jdS)NzKeyspaceChannel(, db=)rrrs r__repr__zKeyspaceChannel.__repr__[s"!$"5"5!8dggYaHHrct|tr|j|jk(St|tr|j|k(StSr) isinstancerrrNotImplementedrothers r__eq__zKeyspaceChannel.__eq__^D e_ -$$(:(:: : eS !$$- -rc,t|jSrhashrrs r__hash__zKeyspaceChannel.__hash__eD%%&&rNrrrrrr rr rr3objectr rr rrkrlrmrnrrrrpropertyr%r(r.r4r9rrrrr$sG:*FM) 9A00!I'rcxeZdZUdZdZded<dddZddZeddZ e dddZ dd Z dd Z dd Zdd Zy )ra Represents a keyevent notification channel for subscribing to event types. Keyevent notifications publish the key name as the message when the specified event type occurs on any key. This class can be used directly with subscribe()/psubscribe() as it implements __str__ to return the channel string. Attributes: event: The event type to monitor db: The database number (defaults to 0, the only database in Redis Cluster) is_pattern: Whether this channel contains wildcards Examples: >>> channel = KeyeventChannel(EventType.SET, db=0) >>> str(channel) '__keyevent@0__:set' >>> channel = KeyeventChannel.all_events(db=0) >>> str(channel) '__keyevent@0__:*' >>> # Use with KeyspaceNotifications >>> notifications = KeyspaceNotifications(redis_client) >>> notifications.subscribe(channel) z __keyevent@rrcJ||_||_|j|_y)z Create a keyevent notification channel. Args: event: The event type to monitor (e.g., EventType.SET or "set") db: The database number. Defaults to 0 (the only database in Redis Cluster). NeventrrrrrGrs rrzKeyeventChannel.__init__s#  668rcP|j|jd|jSrrrrGrs rrz%KeyeventChannel._build_channel_string#++twwis4::,77rc,t|jSr"r$rGrs rr%zKeyeventChannel.is_patterns4::&&rc|d|S)a Create a keyevent pattern for subscribing to all event types. This is equivalent to KeyeventChannel("*"). Args: db: The database number. Defaults to 0 (the only database in Redis Cluster). Returns: A KeyeventChannel configured to receive all events. Examples: >>> channel = KeyeventChannel.all_events() >>> str(channel) '__keyevent@0__:*' rrrrrs r all_eventszKeyeventChannel.all_eventss$32rc|jSrr'rs rr(zKeyeventChannel.__str__r)rc<d|jd|jdS)NzKeyeventChannel(r+r,rGrrs rr.zKeyeventChannel.__repr__s!$**uTWWIQ??rct|tr|j|jk(St|tr|j|k(StSr)r0rrrr1r2s rr4zKeyeventChannel.__eq__r5rc,t|jSrr7rs rr9zKeyeventChannel.__hash__r:rNr;rGrrrr=r>)rrr z'KeyeventChannel'r?rArkrlrmrnrrrrrCr%rrQr(r.r4r9rrrrrisZ8*FM) 98''&!@'rcdeZdZUdZdZded<d ddZddZeddZ ddZ dd Z dd Z dd Z y )ra Represents a subkeyspace notification channel for subscribing to subkey-level events on keys (e.g., hash field changes). The channel format is ``__subkeyspace@__:``. The message payload is ``|:[,...]``. Examples: >>> channel = SubkeyspaceChannel("myhash", db=0) >>> str(channel) '__subkeyspace@0__:myhash' z__subkeyspace@rrcJ||_||_|j|_yrrrs rrzSubkeyspaceChannel.__init__s", 668rcP|j|jd|jSrrrs rrz(SubkeyspaceChannel._build_channel_stringr rc,t|jSrr#rs rr%zSubkeyspaceChannel.is_patterns4..//rc|jSrr'rs rr(zSubkeyspaceChannel.__str__r)rc<d|jd|jdS)NzSubkeyspaceChannel(r+r,r-rs rr.zSubkeyspaceChannel.__repr__s"$T%8%8$;5 KKrct|tr|j|jk(St|tr|j|k(StSr)r0rrrr1r2s rr4zSubkeyspaceChannel.__eq__E e/ 0$$(:(:: : eS !$$- -rc,t|jSrr7rs rr9zSubkeyspaceChannel.__hash__r:rNr;r<r=r>r?rArBrrrrrsG -FM,9 A00!L'rcxeZdZUdZdZded<dddZddZeddZ e dddZ dd Z dd Z dd Zdd Zy )ra Represents a subkeyevent notification channel for subscribing to specific event types with subkey-level detail. The channel format is ``__subkeyevent@__:``. The message payload is ``:|:[,...]``. Examples: >>> channel = SubkeyeventChannel("hdel", db=0) >>> str(channel) '__subkeyevent@0__:hdel' z__subkeyevent@rrcJ||_||_|j|_yrrFrHs rrzSubkeyeventChannel.__init__s!  668rcP|j|jd|jSrrJrs rrz(SubkeyeventChannel._build_channel_stringrKrc,t|jSrrMrs rr%zSubkeyeventChannel.is_patterns4::&&rc|d|S)z+Create a channel for all subkeyevent types.rrOrrPs rrQzSubkeyeventChannel.all_events s32rc|jSrr'rs rr(zSubkeyeventChannel.__str__r)rc<d|jd|jdS)NzSubkeyeventChannel(r+r,rTrs rr.zSubkeyeventChannel.__repr__s$TZZN%yBBrct|tr|j|jk(St|tr|j|k(StSr)r0rrrr1r2s rr4zSubkeyeventChannel.__eq__r`rc,t|jSrr7rs rr9zSubkeyeventChannel.__hash__r:rNr;rWr=r>)rrr rr?rArXrrrrrsZ -FM,9 8''!C'rcdeZdZUdZdZded<d ddZddZeddZ ddZ dd Z dd Z dd Z y )ra& Represents a subkeyspaceitem notification channel for subscribing to events on a specific subkey (field) of a specific key. The channel format is ``__subkeyspaceitem@__:\n``. The message payload is the event type (e.g., ``"hset"``). Note: The server only emits this notification when the key does not contain a newline character. Examples: >>> channel = SubkeyspaceitemChannel("myhash", "myfield", db=0) >>> str(channel) '__subkeyspaceitem@0__:myhash\nmyfield' z__subkeyspaceitem@rrcX||_||_||_|j|_yr)rsubkey_or_patternrrr)rrrmrs rrzSubkeyspaceitemChannel.__init__4s*,!2 668rcj|j|jd|jd|jS)Nrr)rrrrmrs rrz,SubkeyspaceitemChannel._build_channel_string:s5{{mDGG9C(;(;'V W rcZt|jxst|jSr)r$rrmrs rr%z!SubkeyspaceitemChannel.is_pattern?s#4../V;t?U?U3VVrc|jSrr'rs rr(zSubkeyspaceitemChannel.__str__Cr)rcVd|jd|jd|jdS)NzSubkeyspaceitemChannel(, r+r,)rrmrrs rr.zSubkeyspaceitemChannel.__repr__Fs4%d&9&9%r?rArBrrrrr sG"1FM09  WW! 'rcdeZdZUdZdZded<d ddZddZeddZ ddZ dd Z dd Z dd Z y )ra Represents a subkeyspaceevent notification channel for subscribing to a specific event on a specific key, receiving affected subkeys. The channel format is ``__subkeyspaceevent@__:|``. The message payload is a length-prefixed subkey list. Examples: >>> channel = SubkeyspaceeventChannel("hset", "myhash", db=0) >>> str(channel) '__subkeyspaceevent@0__:hset|myhash' z__subkeyspaceevent@rrcX||_||_||_|j|_yr)rGrrrr)rrGrrs rrz SubkeyspaceeventChannel.__init__gs) , 668rcj|j|jd|jd|jS)Nrr)rrrGrrs rrz-SubkeyspaceeventChannel._build_channel_stringms0++twwis4::,a8K8K7LMMrcZt|jxst|jSr)r$rGrrs rr%z"SubkeyspaceeventChannel.is_patternps!4::&J+d6I6I*JJrc|jSrr'rs rr(zSubkeyspaceeventChannel.__str__tr)rcVd|jd|jd|jdS)NzSubkeyspaceeventChannel(rrr+r,)rGrrrs rr.z SubkeyspaceeventChannel.__repr__ws1&tzznB""%U477)1 6 rct|tr|j|jk(St|tr|j|k(StSr)r0rrrr1r2s rr4zSubkeyspaceeventChannel.__eq__}sE e4 5$$(:(:: : eS !$$- -rc,t|jSrr7rs rr9z SubkeyspaceeventChannel.__hash__r:rNr;)rGrrrrrr=r>r?rArBrrrrrWsH 2FM19 NKK! 'rc(eZdZdZdZdZdZdZdZdZ y) ChannelTypeub Enum representing the type of a Redis keyspace notification channel. Redis provides two types of keyspace notifications and four subkey notification types: - KEYSPACE: ``__keyspace@{db}__:{key}`` — data is the event type. - KEYEVENT: ``__keyevent@{db}__:{event}`` — data is the key name. - SUBKEYSPACE: ``__subkeyspace@{db}__:{key}`` — data is event + subkeys. - SUBKEYEVENT: ``__subkeyevent@{db}__:{event}`` — data is key + subkeys. - SUBKEYSPACEITEM: ``__subkeyspaceitem@{db}__:{key}\n{subkey}`` — data is the event type. - SUBKEYSPACEEVENT: ``__subkeyspaceevent@{db}__:{event}|{key}`` — data is a subkey list. Examples: >>> get_channel_type("__keyspace@0__:mykey") ChannelType.KEYSPACE >>> get_channel_type("__subkeyspace@0__:myhash") ChannelType.SUBKEYSPACE keyspacekeyevent subkeyspace subkeyeventsubkeyspaceitemsubkeyspaceeventN) rkrlrmrnKEYSPACEKEYEVENT SUBKEYSPACE SUBKEYEVENTSUBKEYSPACEITEMSUBKEYSPACEEVENTrrrr~r~s(,HHKK'O)rr~cNt|}|jtjrtj S|jt jrtjS|jtjrtjS|jtjrtjS|jtjrtjS|jtjrtjSy)a Determine the type of a Redis keyspace notification channel. Args: channel: The channel name to check (string or bytes). Returns: ChannelType.KEYSPACE if it's a keyspace notification channel, ChannelType.KEYEVENT if it's a keyevent notification channel, None if it's not a keyspace notification channel. Examples: >>> get_channel_type("__keyspace@0__:mykey") ChannelType.KEYSPACE >>> get_channel_type("__keyevent@0__:set") ChannelType.KEYEVENT >>> get_channel_type("regular_channel") is None True >>> get_channel_type(b"__keyspace@0__:mykey") ChannelType.KEYSPACE N)rrrrr~rrrrrrrrrrr)r channel_strs rget_channel_typers,7#K4;;<***5<<=+++0778&&&0778&&&o445###o445### rcBt|dr |j}t|}d}|t|krl||}|dk(r|dz }|dvry|dk(r>|dz}|t|kr+||dk(r|dz }||d k(ry|dz }|t|kr+|dz }|t|krly ) a Check if a channel string contains glob-style pattern characters. Redis uses glob-style patterns for psubscribe: - * matches any sequence of characters - ? matches any single character - [...] matches any character in the brackets Args: channel: The channel string to check. Can be a string, bytes, or a KeyspaceChannel/KeyeventChannel object. Returns: True if the channel contains pattern characters, False otherwise. rr\)r?T[r]F)hasattrrrr)richarjs rr$r$s(w'&&wG A c'l qz 4< FA  :  3;AAc'l"1:%FA1:$Q c'l" Q' c'l ( rceZdZdZedd ddZeddZe d ddZe d ddZe d ddZ e d dd Z e d dd Z e d dd Z e d dd Z ed ZedZedZedZeeddZe d ddZy)KeyspaceNotificationsInterfacea1 Interface for keyspace notification managers. This interface provides a consistent API for both standalone (KeyspaceNotifications) and cluster (ClusterKeyspaceNotifications) implementations, allowing the same code patterns to work with both standalone and cluster Redis deployments. Nhandlercy)z,Subscribe to keyspace notification channels.Nr)rrchannelss r subscribez(KeyspaceNotificationsInterface.subscribe rcy)z0Unsubscribe from keyspace notification channels.Nr)rrs r unsubscribez*KeyspaceNotificationsInterface.unsubscribe rcy)z6Subscribe to keyspace notifications for specific keys.Nrrrrrs rsubscribe_keyspacez1KeyspaceNotificationsInterface.subscribe_keyspace rcy)z=Subscribe to keyevent notifications for specific event types.NrrrGrrs rsubscribe_keyeventz1KeyspaceNotificationsInterface.subscribe_keyevent(rrcy)z9Subscribe to subkeyspace notifications for specific keys.Nrrs rsubscribe_subkeyspacez4KeyspaceNotificationsInterface.subscribe_subkeyspace2rrcy)z@Subscribe to subkeyevent notifications for specific event types.Nrrs rsubscribe_subkeyeventz4KeyspaceNotificationsInterface.subscribe_subkeyevent<rrcy)zASubscribe to subkeyspaceitem notifications for a specific subkey.Nr)rrrmrrs rsubscribe_subkeyspaceitemz8KeyspaceNotificationsInterface.subscribe_subkeyspaceitemF rcy)zBSubscribe to subkeyspaceevent notifications for an event on a key.Nr)rrGrrrs rsubscribe_subkeyspaceeventz9KeyspaceNotificationsInterface.subscribe_subkeyspaceeventQrrcy)z7Get the next keyspace notification if one is available.Nr)rignore_subscribe_messagestimeouts r get_messagez*KeyspaceNotificationsInterface.get_message\rrcy)z"Listen for keyspace notifications.Nrrs rlistenz%KeyspaceNotificationsInterface.listenerrcy)z6Close the notification manager and clean up resources.Nrrs rclosez$KeyspaceNotificationsInterface.closejrrcyrrrs r __enter__z(KeyspaceNotificationsInterface.__enter__o rcyrrr _exc_type_exc_val_exc_tbs r__exit__z'KeyspaceNotificationsInterface.__exit__srrcy);Check if there are any active subscriptions and not closed.Nrrs r subscribedz)KeyspaceNotificationsInterface.subscribedws rcy)z7Start a background thread that polls for notifications.Nr)r poll_timeoutdaemonexception_handlers r run_in_threadz,KeyspaceNotificationsInterface.run_in_thread}s rrrrSyncHandlerT | NonerrrNrrrrrrrGrrrrrrrrmrrrrrrGrrrrrrrNrz bool | Nonerfloatr r r>rFNrrrrr\Callable[[BaseException, KeyspaceNotificationsInterface, KeyspaceWorkerThread], None] | Noner KeyspaceWorkerThread)rkrlrmrnrrrrrrrrrrrrrrrCrrrrrrrs(,  %    '+     %   '+     %   '+     %   '+     %    '+       %    '+       %   26 #.               "        rrcxeZdZdZ d ddZdd ddZe ddZddZe ddZ dd Z dd Z d dd Z d dd Z d dd Z d ddZ d ddZ d ddZdZdZ d d!dZed"dZy)#AbstractKeyspaceNotificationsa Abstract base class for keyspace notification managers. Provides shared implementation for subscribe/unsubscribe logic. Subclasses must implement: - _execute_subscribe: Execute the subscribe operation - _execute_unsubscribe: Execute the unsubscribe operation - get_message: Get the next notification - listen: Generator for notifications - close: Clean up resources Nc.||_||_d|_y)aK Initialize the base keyspace notification manager. Args: key_prefix: Optional prefix to filter and strip from keys in notifications ignore_subscribe_messages: If True, subscribe/unsubscribe confirmations are not returned by get_message/listen FN)rr_closed)rrrs rrz&AbstractKeyspaceNotifications.__init__s%)B& rrc d}|j  fd}|}i}i}|D];}t|dr t|}n t|}t |r|||<7|||<=|j |||j ||y)a Subscribe to keyspace notification channels. Automatically detects whether each channel is a pattern (contains wildcards like *, ?, [) or an exact channel name and uses the appropriate Redis subscribe command internally. Args: *channels: Channels to subscribe to. Can be strings, KeyspaceChannel, or KeyeventChannel objects. Patterns are auto-detected. handler: Optional callback function that receives KeyNotification objects. If provided, notifications are passed to the handler instead of being returned by get_message()/listen(). NcJtj|}| |yy)Nr)rr)r notificationrrs r _wrap_handlerz>AbstractKeyspaceNotifications.subscribe.._wrap_handlers2.;;  <   +L),rr)rrrrr$_execute_subscribe_track_subscribe) rrrwrapped_handlerrpatternsexact_channelsrrrs ` @rrz'AbstractKeyspaceNotifications.subscribes(,0  J *,O >Gw/!'l &w/ 7#(7%.={+ > .9 h7rcy)z Execute the subscribe operation. Args: patterns: Dict mapping pattern strings to handlers (for psubscribe) exact_channels: Dict mapping channel strings to handlers (for subscribe) Nrrrrs rrz0AbstractKeyspaceNotifications._execute_subscribe rcg}g}|D]S}t|dr t|}n t|}t|r|j |C|j |U|j |||j ||y)a Unsubscribe from keyspace notification channels. Automatically detects whether each channel is a pattern or exact channel and uses the appropriate Redis unsubscribe command. Args: *channels: Channels to unsubscribe from. rN)rrrr$r'_execute_unsubscribe_untrack_subscribe)rrrrrrs rrz)AbstractKeyspaceNotifications.unsubscribes~ 3Gw/!'l &w/ 7# ,%%k2 3 !!(N; .9rcy)z Execute the unsubscribe operation. Args: patterns: List of pattern strings to punsubscribe from exact_channels: List of channel strings to unsubscribe from Nrrs rrz2AbstractKeyspaceNotifications._execute_unsubscriberrcy)a[Track newly subscribed patterns/channels. Override in subclasses that need to maintain their own subscription registry (e.g. cluster implementations that must re-subscribe new/failed-over nodes). The default is a no-op because standalone implementations delegate tracking to the underlying PubSub object. Nrrs rrz.AbstractKeyspaceNotifications._track_subscribercy)zRemove patterns/channels from the subscription registry. Override in subclasses that maintain their own subscription registry. The default is a no-op. Nrrs rrz0AbstractKeyspaceNotifications._untrack_subscribe)rrcDt||}|j||y)a Subscribe to keyspace notifications for specific keys. Args: key_or_pattern: The key or pattern to monitor. Use '*' for wildcards. db: The database number (default 0). handler: Optional callback for notifications. Example: >>> ksn.subscribe_keyspace("user:123", db=0) >>> ksn.subscribe_keyspace("user:*", db=0) rOrN)rrrrrrrs rrz0AbstractKeyspaceNotifications.subscribe_keyspace2s $".R8 w0rcDt||}|j||y)a Subscribe to keyevent notifications for specific event types. Args: event: The event type to monitor (e.g., EventType.SET or "set") db: The database number (default 0). handler: Optional callback for notifications. Example: >>> ksn.subscribe_keyevent(EventType.SET) >>> ksn.subscribe_keyevent(EventType.EXPIRED, handler=my_handler) rOrN)rrrrGrrrs rrz0AbstractKeyspaceNotifications.subscribe_keyeventGs $"%B/ w0rcDt||}|j||y)aK Subscribe to subkeyspace notifications for specific keys. Receives events with affected subkeys (fields) for the given key. Args: key_or_pattern: The key or pattern to monitor. db: The database number (default 0). handler: Optional callback for notifications. rOrN)rrrs rrz3AbstractKeyspaceNotifications.subscribe_subkeyspace\s %^; w0rcDt||}|j||y)a] Subscribe to subkeyevent notifications for specific event types. Receives the affected key and subkeys when the given event occurs. Args: event: The event type to monitor (e.g., "hset", "hdel"). db: The database number (default 0). handler: Optional callback for notifications. rOrN)rrrs rrz3AbstractKeyspaceNotifications.subscribe_subkeyeventos %Ur2 w0rcFt|||}|j||y)a Subscribe to subkeyspaceitem notifications for a specific subkey. Receives the event type when the given subkey of the given key is modified. Args: key_or_pattern: The key or pattern to monitor. subkey_or_pattern: The subkey (field) or pattern to monitor. db: The database number (default 0). handler: Optional callback for notifications. rOrN)rr)rrrmrrrs rrz7AbstractKeyspaceNotifications.subscribe_subkeyspaceitems#&)9JrR w0rcFt|||}|j||y)a Subscribe to subkeyspaceevent notifications for an event on a key. Receives the affected subkeys when the given event occurs on the given key. Args: event: The event type to monitor. key_or_pattern: The key or pattern to monitor. db: The database number (default 0). handler: Optional callback for notifications. rOrN)rr)rrGrrrrs rrz8AbstractKeyspaceNotifications.subscribe_subkeyspaceevents"&*%BG w0rc|Srrrs rrz'AbstractKeyspaceNotifications.__enter__s rc$|jy)NF)rrs rrz&AbstractKeyspaceNotifications.__exit__s rcd|jt||||}|j|S)az Start a background thread that polls for notifications and triggers handlers. This method spawns a thread that continuously calls get_message() to process incoming notifications. When a notification arrives, any registered handler for that channel/pattern is invoked automatically. All subscriptions must have handlers registered before calling this method. Args: poll_timeout: Timeout in seconds for get_message() calls. When no message is available, the thread waits up to this long before checking again. Default 0.0 (non-blocking). WARNING: the default causes a CPU spin-loop. It is preferred to pass a positive value (e.g. 0.1 or 1.0). daemon: If True, the thread will be a daemon thread and will be terminated when the main program exits. Default False. exception_handler: Optional callback invoked when an exception occurs in the worker thread. Receives (exception, notifications, thread) as arguments. If None, exceptions are raised. Returns: KeyspaceWorkerThread: The started worker thread. Call stop() on it to stop the thread and close the notifications. Raises: RedisError: If any subscription doesn't have a handler registered. Example: >>> def my_handler(notification): ... print(f"Got: {notification.key} - {notification.event_type}") >>> >>> notifications.subscribe(KeyspaceChannel("user:*"), handler=my_handler) >>> thread = notifications.run_in_thread(poll_timeout=0.1, daemon=True) >>> # ... handlers are called automatically ... >>> thread.stop() )rr)_validate_all_handlersrr)rrrrthreads rrz+AbstractKeyspaceNotifications.run_in_threads7f ##%%  /     rcy)zRaise :class:`~redis.RedisError` if any subscription lacks a handler. Subclasses inspect their own subscription state to perform the validation. Nrrs rrz4AbstractKeyspaceNotifications._validate_all_handlersrrNT)rrrrrrdict[str, Any]rrr Nonerrrrrr rrrrrrrrr r)rkrlrmrnrrrrrrrrrrrrrrrrrrrrrrrs< *.*.&$(((,4848%48l  &  8F      :@  !  3<        &  8F     ! 3<  '+ 11 1% 10'+ 11 1% 10'+ 11 1% 1,'+ 11 1% 1.'+ 111  1 % 14'+ 111  1 % 1, "<<< < <|  rrcHeZdZdZ d dfd ZddZddZxZS)ra Background thread for processing keyspace notifications. This thread continuously polls for notifications and invokes registered handlers. It works with both KeyspaceNotifications (standalone) and ClusterKeyspaceNotifications. Example: >>> thread = notifications.run_in_thread(poll_timeout=0.1) >>> # ... handlers are called automatically ... >>> thread.stop() ct|||_||_||_||_t j|_yr) superrr notificationsrr threadingEvent_running)rr rrr __class__s rrzKeyspaceWorkerThread.__init__ s=  *(!2!) rc|jjry|jj|j}|j}|jjr/ |j d||jjr/|jy#t $r*}|j|j|||Yd}~Zd}~wwxYw)z=Main loop that polls for notifications and triggers handlers.NTrr) ris_setrr rr BaseExceptionrr)rr res rrunzKeyspaceWorkerThread.run!s ==   !  ** (( mm""$ ?)).2L*mm""$  ! ?))1&&q->> ?s)B(( C1 CCc8|jjy)z Stop the worker thread. This signals the thread to exit its run loop. The thread will close the notifications object before terminating. N)rclearrs rstopzKeyspaceWorkerThread.stop3s r)FN)r rrrrrrrr)rkrlrmrnrrr __classcell__rs@rrrsG "*5** *  *,$rrceZdZdZ d d fd Z d dZ d dZ d ddZdZe ddZ ddZ d Z xZ S)KeyspaceNotificationsa Manages keyspace notification subscriptions for standalone Redis. For standalone Redis, keyspace notifications work with a single PubSub connection. This class wraps that connection and provides: - Automatic pattern vs exact channel detection - KeyNotification parsing with optional key_prefix filtering - Convenience methods for keyspace and keyevent subscriptions - Context manager and run_in_thread support cbt|||||_|jd|_y)av Initialize the standalone keyspace notification manager. Note: Keyspace notifications must be enabled on the Redis server via the ``notify-keyspace-events`` configuration option. This is a server-side configuration that should be done by your infrastructure/operations team. Args: redis_client: A Redis client instance key_prefix: Optional prefix to filter and strip from keys in notifications ignore_subscribe_messages: If True, subscribe/unsubscribe confirmations are not returned by get_message/listen FrN)r rredispubsub_pubsub)r redis_clientrrrs rrzKeyspaceNotifications.__init__Ns3& %>?! $**U*K rc~|r|jjdi||r|jjdi|yy)z2Execute subscribe on the single pubsub connection.Nr)r! psubscriberrs rrz(KeyspaceNotifications._execute_subscribehs=  #DLL # # /h /  "DLL " " 4^ 4 rcr|r|jj||r|jj|yy)z4Execute unsubscribe on the single pubsub connection.N)r! punsubscriberrs rrz*KeyspaceNotifications._execute_unsubscribeqs7  %DLL % %x 0  $DLL $ $n 5 rc| |j}|jry|jj||}|!tj ||j Sy)ae Get the next keyspace notification if one is available. Note: If a handler was registered for the channel, pubsub will call the handler directly and this method returns None for that message. Args: ignore_subscribe_messages: If True, skip subscribe/unsubscribe messages. Defaults to the value set in __init__ (True). timeout: Time to wait for a message. Returns: A KeyNotification if a notification is available and no handler was registered for the channel, None otherwise. Nrr)rrr!rrrr)rrrrs rrz!KeyspaceNotifications.get_messagezsf( % ,(,(F(F % << ,,**&?+   "//DOO/T Trc#pK|jr&|jd}|||jr%yyw)a Listen for keyspace notifications. This is a generator that yields KeyNotification objects as they arrive. It blocks until a notification is received. Yields: KeyNotification objects for each keyspace/keyevent notification. Example: >>> for notification in ksn.listen(): ... print(f"{notification.key}: {notification.event_type}") ?rNrrrrs rrzKeyspaceNotifications.listen7oo++C+8L'""oo166cL|j xr|jjSr)rr!rrs rrz KeyspaceNotifications.subscribeds <<;DLL$;$;;rc|jjjD]\}}| td|d|jjjD]\}}| td|dy)zCRaise if any subscription in the underlying PubSub lacks a handler.N Channel '' has no handler registered Pattern ')r!ritemsrrrrrpatterns rrz,KeyspaceNotifications._validate_all_handlerss $ 5 5 ; ; = S GW 9WI5P!QRR S!% 5 5 ; ; = S GW 9WI5P!QRR Srcfd|_ |jjy#t$rYywxYw)z3Close the pubsub connection and clean up resources.TN)rr!r Exceptionrs rrzKeyspaceNotifications.closes0   LL      s $ 00r)r"r rrrrrrrrr>r)rkrlrmrnrrrrrrCrrrrrs@rrrBs *.*. LL'L$( L45&58F5 56!63<6 626%#.%% %N#&<<SrrceZdZdZ d dfd ZeddZ ddZ ddZddZ dZ ddZ dd Z dd Z dd Zdd Z d dd Z ddZdZdZddZdZdZxZS) ClusterKeyspaceNotificationsaL Manages keyspace notification subscriptions across all nodes in a Redis Cluster. In Redis Cluster, keyspace notifications are NOT broadcast between nodes. Each node only emits notifications for keys it owns. This class automatically subscribes to all primary nodes in the cluster and handles topology changes. ct|||||_i|_i|_i|_t j|_d|_ y)a{ Initialize the cluster keyspace notification manager. Note: Keyspace notifications must be enabled on all Redis cluster nodes via the ``notify-keyspace-events`` configuration option. This is a server-side configuration that should be done by your infrastructure/operations team. Args: redis_cluster: A RedisCluster instance key_prefix: Optional prefix to filter and strip from keys in notifications ignore_subscribe_messages: If True, subscribe/unsubscribe confirmations are not returned by get_message/listen rN) r rcluster_subscribed_patterns_subscribed_channels _node_pubsubsr Lock _refresh_lock _poll_index)r redis_clusterrrrs rrz%ClusterKeyspaceNotifications.__init__sS& %>?$ 57!46!.0'^^-rcf|j xr#t|jxs |jSr0)rrr>r?rs rrz'ClusterKeyspaceNotifications.subscribeds3<< D  % % B)B)B%  rcz|r|jj||r|jj|yy)zATrack newly subscribed patterns/channels in the cluster registry.N)r>updater?rs rrz-ClusterKeyspaceNotifications._track_subscribes7   % % , ,X 6   % % , ,^ < rc|D]}|jj|d |D]}|jj|d y)z3Remove patterns/channels from the cluster registry.N)r>popr?)rrrpcs rrz/ClusterKeyspaceNotifications._untrack_subscribesN 3A  % % ) )!T 2 3 3A  % % ) )!T 2 3rc|jjD]\}}| td|d|jjD]\}}| td|dy)zBRaise if any subscription in the cluster registry lacks a handler.Nr2r3r4)r?r5rr>r6s rrz3ClusterKeyspaceNotifications._validate_all_handlerss $ 9 9 ? ? A S GW 9WI5P!QRR S!% 9 9 ? ? A S GW 9WI5P!QRR Src6|jjS)z%Get all primary nodes in the cluster.)r= get_primariesrs r_get_all_primary_nodesz3ClusterKeyspaceNotifications._get_all_primary_nodes!s||))++rc|jj|d}|r |jyy#t$rYywxYw)zRemove and close a node's PubSub. Closing the ``PubSub`` disconnects its connection so it is not left in a subscribed state inside the connection pool. N)r@rIrr9)r node_namer s r _cleanup_nodez*ClusterKeyspaceNotifications._cleanup_node%sF ##'' 48      s 2 >>c|j|jvrF|jj|}|j d}||j|j<|j|jS)z+Get or create a PubSub instance for a node.Fr)namer@r=get_redis_connectionr )rnode redis_connr s r_ensure_node_pubsubz0ClusterKeyspaceNotifications._ensure_node_pubsub2sf 99D.. .::4@J &&&GF,2D  tyy )!!$)),,rc`|s|syg}|jD]}|j|jv}|j|} |rP|jr|j di|j|j r|jdi|j |r|j di||r|jdi||r&tjddj|yy#t$r:|j|j|j|jYwxYw)aExecute subscribe on all cluster nodes. Patterns and exact channels are subscribed in a single pass over nodes so that a mid-batch node failure cannot create a partially-caught-up replacement. If a node fails during this call it is removed from ``_node_pubsubs`` and will be fully re-subscribed on the next ``refresh_subscriptions`` cycle. If a newly discovered node is encountered (not yet in ``_node_pubsubs``), it is also subscribed to all *previously* tracked patterns/channels so it doesn't miss notifications for subscriptions that were established before this node joined. Nz`Failed to subscribe on cluster nodes: %s. These nodes will be retried on the next refresh cycle.rrr)rOrTr@rXr>r$r?rr9rRr'loggerwarningjoin)rrr failed_nodesrV is_new_noder s rrz/ClusterKeyspaceNotifications._execute_subscribe=s'  "$ //1 /D))4+=+==K--d3F /00)))FD,E,EF00(((E4+D+DE%F%%11!$F$$6~6 /,  NNI ,'    /""499-##DII.  /sA:C**?D-,D-cZ|r|j|d|r|j|dyy)z)Execute unsubscribe on all cluster nodes.T)use_punsubscribeFN)_unsubscribe_from_all_nodesrs rrz1ClusterKeyspaceNotifications._execute_unsubscribens5   , ,X , M   , ,^e , T rcTg}t|jjD]'\}} |r|j|n|j|)|r&tjddj|yy#t $r%|j ||j|YwxYw)aUnsubscribe from patterns/channels on all nodes. Best-effort: tries every node so that a single broken connection does not prevent the remaining nodes from being unsubscribed. Broken pubsubs are cleaned up; the tracking state is still removed by the caller, so ``refresh_subscriptions`` will *not* re-subscribe these channels on replacement nodes. zeFailed to unsubscribe on cluster nodes: %s. These nodes will be re-created on the next refresh cycle.rrN) listr@r5r&rr9rRr'rZr[r\)rrr`r]rQr s rraz8ClusterKeyspaceNotifications._unsubscribe_from_all_nodesws#% !%d&8&8&>&>&@!A / Iv /#'F''2&F&&1  /  NNL ,'    /""9-##I. /s!A99+B'&B'c|jryt|j}|dk(r|dkDrtj|y| |j }|dk(r|j |Std|t|dz }tj}||z} tj|k\ryt|jj}|sy|jt|z|_ ||j}|xjdz c_ |j||} | %t$j'| |j(} | | S#ttt f$r|j#YwxYw)a Get the next keyspace notification if one is available. This method polls all node pubsubs in round-robin fashion until a message is received or the timeout expires. If a connection error occurs, subscriptions are automatically refreshed. Args: ignore_subscribe_messages: If True, skip subscribe/unsubscribe messages. Defaults to the value set in __init__ (True). timeout: Total time to wait for a message (distributed across all nodes) Returns: A KeyNotification if a notification is available, None otherwise. Nrrg?rrr)rrr@timesleepr_poll_all_nodes_onceminmax monotonicrcvaluesrCrrrr_refresh_subscriptions_on_errorrrr) rrr total_nodesper_node_timeout start_timeend_timepubsubsr rrs rrz(ClusterKeyspaceNotifications.get_messages( <<$,,- ! { 7# % ,(,(F(F % c>,,-FG GsGc+q.A$AB^^% '~~8+4--4467G $//#g,>D T--.F    !   ,,.G,-" /;; <   +''?&$\:> 446 sE$E<;E<cTd}t|jjD]R} |j|d}|tj||j}|>|r|j|cS|r|jy#tt t f$rd}YwxYw)a3 Perform a single non-blocking poll over all node pubsubs. This is used when timeout=0 to match the expected semantics of PubSub.get_message(timeout=0) - a non-blocking check for messages. Returns: A KeyNotification if one is available, None otherwise. FrrTNr) rcr@rkrrrrrrrrl)rr had_errorr rrs rrgz1ClusterKeyspaceNotifications._poll_all_nodes_onces 4--4467 (F  ,,.G-" /;; <   +!<<>''/ (4   0 0 2-$\:> !   sBB'&B'c#pK|jr&|jd}|||jr%yyw)a Listen for keyspace notifications from all cluster nodes. This is a generator that yields KeyNotification objects as they arrive. It blocks until a notification is received. Yields: KeyNotification objects for each keyspace/keyevent notification. Example: >>> for notification in ksn.listen(): ... print(f"{notification.key}: {notification.event_type}") r)r*Nr+r,s rrz#ClusterKeyspaceNotifications.listenr-r.cd|_ |jy#t$rtj ddYywxYw)z Refresh subscriptions after a connection error. This is called automatically when a connection error occurs during get_message(). It checks if nodes changed before refreshing. rzAFailed to refresh cluster subscriptions, will retry on next errorT)exc_infoN)rCrefresh_subscriptionsr9rZr[rs rrlzr$r?rr9r'rr\) rrVcurrent_primaries removed_nodesrQexisting_nodesr  new_nodesr]s rrwz2ClusterKeyspaceNotifications.refresh_subscriptions=s$  - ,0,G,G,I!$( 4! !   2 2 7 7 9:S!&&(>M+ . ""9- . !!3!3!8!8!:;c!&&(?N, 2 ++// :$";";F"C&&y1  2-2245Drr?)rrQs rrz"ClusterKeyspaceNotifications.closexs^ d005578 *I   y ) * !!'') !!'')rr)rDrrrrrr>rrr)rQrr r)r r )rrr`rrr)rrr r )rkrlrmrnrrCrrrrrOrRrXrrrarrgrrlr|rwrrrs@rr;r;s7*.*. $#$'$$( $L  =&=8F= =3!33<3 3S,  -/&/8F/ /bU!U3<U U:26O(#.O(O( O(d))-) )V#&"9v*rr;)rrr r)rr r zChannelType | None)rz/str | bytes | KeyspaceChannel | KeyeventChannelr r):rn __future__rloggingr r reabcrrcollections.abcr dataclassesrenumrtypingr r r r redis.clientr redis.clusterrredis.exceptionsrrr redis.utilsr getLoggerrkrZrrbytesrr SyncHandlerTrrrrrrrrrr~rr$rrThreadrrr;rrrrs8t#  #$!66& !   8 $   ) *+T12 mm`* g+g+ g+^ B'B'JU'U'p*'*'Z/'/'d4'4'n.'.'b*$*>$N1 <1 1rF SF Rj $Bj Z =9++=JF9F\n*#@n*r