\jx*UdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZmZddlmZddlmZddlmZmZddlmZdd lmZdd lmZdd lmZdd l m!Z!erdd l"m#Z#m$Z$edZ%dZ&dZ'e(eddZ)e jTdk7xrejVejXvZ-eZ.de/d<e j`a1da2da3edGddZ4eGddZ5edGddZ6eGddZ7Gd d!e8Z9Gd"d#e9$Z:Gd%d&e jvZd5d*Z?dd' d6d+Z@dd'd7d,ZAdd'd7d-ZBd8d.ZCd9d/ZDd:d0ZEd:d1ZFd:d2ZGd#gZHy);zZCross-process and cross-host reader/writer lock built on :class:`SoftFileLock` primitives.) annotationsN)contextmanagersuppress) dataclass)Path) TYPE_CHECKINGLiteral)WeakValueDictionary)AcquireReturnProxy)Timeout) SoftFileLock)ensure_directory_exists)Callable Generator)readwritez.breaki O_NOFOLLOWwin32,WeakValueDictionary[Path, SoftReadWriteLock]_all_instancesFT)frozenc,eZdZUded<ded<ded<y)_PathsstrstaterreadersN__name__ __module__ __qualname____annotations__A/root/env/lib/python3.12/site-packages/filelock/_soft_rw/_sync.pyrr-s J J Lr#rc,eZdZUded<ded<ded<y)_Locksthreading.Lockinternal transactionr rNrr"r#r$r&r&4s r#r&c,eZdZUded<ded<ded<y) _MarkerInfortokenintpidhostnameNrr"r#r$r+r+;s J HMr#r+cbeZdZUdZded<ded<ded<ded <d ed <ded <d ed<ded<y)_HoldzYEverything that exists only while a lock is held; ``None`` when the instance has no lock.r-level_Modemode int | Nonewrite_thread_idr marker_namebool is_readerr,_HeartbeatThreadheartbeat_threadthreading.Eventheartbeat_stopN)rrr __doc__r!r"r#r$r1r1Bs1c J KO J&&##r#r1cfeZdZUded<ded< d dddddd  d fd ZxZS) _SoftRWMetar _instancesr'_instances_lockT>@N?blocking is_singletonheartbeat_intervalstale_threshold poll_intervalc |st ||||||||St|j}|j5|j j |} | &t ||||||||} | |j |<nK| j|k7s| j|k7r-d| jd| jd|d|} t| | cdddS#1swYyxYw)NrEz$Singleton lock created with timeout=z , blocking=z, cannot be changed to timeout=) super__call__rresolverBrAgettimeoutrF ValueError) cls lock_filerPrFrGrHrIrJ normalizedinstancemsg __class__s r$rMz_SoftRWMeta.__call__Ts7#!)#5 /+$ )_,,.   ~~))*5H 7+%!-'9$3"/,.6z*!!W,0A0AX0M:8;K;K:LKX`XiXiWjk55..`` — one file per reader. Each marker stores a random token (``secrets.token_hex(16)``), the holder's pid, and the holder's hostname. A daemon heartbeat thread refreshes ``mtime`` on every held marker. A marker whose mtime has not advanced in ``stale_threshold`` seconds may be evicted by any process on any host, giving correct behavior when a compute node crashes with a lock held. Writer acquire is two-phase and writer-preferring: phase 1 claims ``.write`` (blocking any new reader), phase 2 waits for existing readers to drain. Writer starvation is impossible. Reentrancy, upgrade/downgrade rules, thread pinning, and singleton caching by resolved path match :class:`~filelock.ReadWriteLock`. Forking while holding a lock invalidates the inherited instance in the child so the child cannot double-own the lock with its parent; ``release()`` on a fork-invalidated instance is a no-op, and the child must re-acquire if it needs a lock. Trust boundary: protects against same-UID non-cooperating processes (one host or cross-host) and same-host different-UID users via ``0o600`` / ``0o700`` permissions. Does not protect against root compromise, NTP tampering on same-UID cross-host nodes, or multi-tenant mounts where hostile co-tenants share the UID. :param lock_file: path to the lock file; sidecar state/write/readers live next to it :param timeout: maximum wait time in seconds; ``-1`` means block indefinitely :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately on contention :param is_singleton: if ``True``, reuse existing instances for the same resolved path :param heartbeat_interval: seconds between heartbeat refreshes; default 30 s :param stale_threshold: seconds of ``mtime`` inactivity before a marker is stale; defaults to ``3 * heartbeat_interval``, matching etcd's ``LeaseKeepAlive`` convention :param poll_interval: seconds between acquire retries under contention; default 0.25 s .. versionadded:: 3.27.0 rrATrCNrDrEc2|dkrd|}t|||dz}||krd|d|d}t||dkrd|}t|tj||_||_||_||_||_||_t|jd|jd |jd  |_ t|jttjtjt|jj d |_d|_d|_d|_d|_t,5|t.t1|jj3<t5dddy#1swYyxYw)Nrz)heartbeat_interval must be positive, got z0stale_threshold must exceed heartbeat_interval (z <= )z$poll_interval must be positive, got z.statez.writez.readers)rrrrYrPr(r)rF)rQosfspathrSrPrFrHrIrJr_pathsrr& threadingLockr r_locks_readers_dir_fd_hold_fork_invalidated_closed_all_instances_lockrrrN_register_hooks) selfrSrPrFrGrHrIrJrVs r$__init__zSoftReadWriteLock.__init__s  "=>P=QRCS/ !  "014O 0 0D_DUUYZlYmmnoCS/ ! A 8HCS/ ! ii 2% & );&5$1^^$F+^^$F+~~&h/  /^^%!(t{{00"=  ,0#' ',"  =AN4/779 :     s 5F  FrFc#K|j|| d|jy#|jwxYww)a Context manager that acquires and releases a shared read lock. Falls back to instance defaults for *timeout* and *blocking* when ``None``. :param timeout: maximum wait time in seconds, or ``None`` to use the instance default :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately; ``None`` uses the instance default :raises RuntimeError: if a write lock is already held on this instance :raises Timeout: if the lock cannot be acquired within *timeout* seconds ruN) acquire_readreleasersrPrFs r$ read_lockzSoftReadWriteLock.read_locks5 'H5   LLNDLLNA,A>Ac#K|j|| d|jy#|jwxYww)a@ Context manager that acquires and releases an exclusive write lock. Falls back to instance defaults for *timeout* and *blocking* when ``None``. :param timeout: maximum wait time in seconds, or ``None`` to use the instance default :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately; ``None`` uses the instance default :raises RuntimeError: if a read lock is already held, or a write lock is held by a different thread :raises Timeout: if the lock cannot be acquired within *timeout* seconds ruN) acquire_writerxrys r$ write_lockzSoftReadWriteLock.write_locks5 7X6   LLNDLLNr{c*|jd||S)uf Acquire a shared read lock. If this instance already holds a read lock, the lock level is incremented (reentrant). Attempting to acquire a read lock while holding a write lock raises :class:`RuntimeError` (downgrade not allowed). On the 0→1 transition a daemon heartbeat thread is started that refreshes the reader marker's ``mtime`` every ``heartbeat_interval`` seconds so peers on other hosts do not evict the marker as stale. :param timeout: maximum wait time in seconds, or ``None`` to use the instance default; ``-1`` means block indefinitely :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately when the lock is unavailable; ``None`` uses the instance default :returns: a proxy that can be used as a context manager to release the lock :raises RuntimeError: if a write lock is already held on this instance, if this instance was invalidated by :func:`os.fork`, or if :meth:`close` was called :raises Timeout: if the lock cannot be acquired within *timeout* seconds rru_acquirerys r$rwzSoftReadWriteLock.acquire_read s*}}VWx}@@r#c*|jd||S)a Acquire an exclusive write lock. If this instance already holds a write lock from the same thread, the lock level is incremented (reentrant). Attempting to acquire a write lock while holding a read lock raises :class:`RuntimeError` (upgrade not allowed). Write locks are pinned to the acquiring thread: a different thread trying to re-enter also raises :class:`RuntimeError`. Writer acquisition runs in two phases. Phase 1 atomically claims ``.write`` via ``O_CREAT | O_EXCL``, which immediately blocks any new reader on any host. Phase 2 waits for existing readers to drain. Writer starvation is impossible: new readers see ``.write`` during phase 2 and wait behind the pending writer. :param timeout: maximum wait time in seconds, or ``None`` to use the instance default; ``-1`` means block indefinitely :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately when the lock is unavailable; ``None`` uses the instance default :returns: a proxy that can be used as a context manager to release the lock :raises RuntimeError: if a read lock is already held, if a write lock is held by a different thread, if this instance was invalidated by :func:`os.fork`, or if :meth:`close` was called :raises Timeout: if the lock cannot be acquired within *timeout* seconds rrurrys r$r}zSoftReadWriteLock.acquire_write$s2}}Wg}AAr#cd|jd|jj5|jr dddyd|_|j>t t 5tj|jdddd|_dddy#1swYxYw#1swYyxYw)u Release any held lock and release internal filesystem resources. Idempotent. After calling this method the instance can no longer acquire locks — subsequent acquires raise :class:`RuntimeError`. A fork-invalidated instance is closed without raising. TforceN) rxrlr(rprmrOSErrorrgcloserss r$rzSoftReadWriteLock.close?s 4  [[ ! ! ,|| , , DL##/g&3HHT1123'+$ , , 33  , ,s)B&"B&" BB&B# B&&B/Frc|jj5|jrd|_ dddy|j}|3|r dddyd|jdt |d}t ||rd|_n|xjdzc_|jdkDr dddyd|_dddjj|jj|jdz|jr"t|j|j yt|jy#1swYxYw) a8 Release one level of the current lock. When the lock level reaches zero the heartbeat thread is stopped and the held marker file is unlinked. On a fork-invalidated instance (that is, the child of a :func:`os.fork` call made while the parent held a lock) this method is a no-op so inherited ``with`` blocks can unwind cleanly in the child. :param force: if ``True``, release the lock completely regardless of the current lock level :raises RuntimeError: if no lock is currently held and *force* is ``False`` NzCannot release a lock on (lock id: z) that is not heldrg?redir_fd)rlr(rornrSid RuntimeErrorr2r=setr;joinrHr9_unlinkr7rm)rsrholdrVs r$rxzSoftReadWriteLock.releasePs([[ ! ! %%!     ::D|  2$..1ARPTXJVhi"3''  a zzA~!  "DJ# , ! ""4+B+BS+H"I >> D$$T-A-A B D$$ %7  sEEAE.EE c||||S)a Return the singleton :class:`SoftReadWriteLock` for *lock_file*. :param lock_file: path to the lock file; sidecar state/write/readers live next to it :param timeout: maximum wait time in seconds; ``-1`` means block indefinitely :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately when the lock is unavailable :returns: the singleton lock instance :raises ValueError: if an instance already exists for this path with different *timeout* or *blocking* values rur")rRrSrPrFs r$get_lockzSoftReadWriteLock.get_lockzs(9g99r#c | |jn|}| |jn|}|jj5|jrd|j d}t ||jrd|j d}t ||j|j|cdddS dddtj}|s'|jjjd}nS|dk(r'|jjjd}n'|jjjd|}|st|j d |jj5|j>|j|cddd|jjjS ddd|dk(rdn||z} t!j"d } |d k(r|j%| | | \} } n|j'| | | \} } t)j*} t-|j.|j0| d t3|d }|jj5t5d||d k(rt)j6nd| | | || |_ddd|j9t;||jjjS#1swYFxYw#1swY@xYw#1swYcxYw#|jjjwxYw)NzSoftReadWriteLock on z4 was invalidated by fork(); construct a new instancez has been closedFrurYT)rFrPrdeadlinerFzfilelock-heartbeat-x)refreshinterval stop_eventnamer)r2r4r6r7r9r,r;r=lock)rPrFrlr(rorSrrprn_validate_reentranttime perf_counterr)acquirer rxsecrets token_hex_acquire_writer_slot_acquire_reader_slotrjEventr:_refresh_markerrHrr1 get_identstartr )rsr4rPrFeffective_timeouteffective_blockingrVracquiredrr,r7r9r heartbeats r$rzSoftReadWriteLock._acquires-4ODLL.6.>T]]H [[ ! ! 6%%-dnn-==qr"3''||-dnn-==MN"3''zz%//5 6 6& 6!!#!{{..666FH " ${{..666EH{{..66N_6`H$..)t 3' .%% :::)33D9 : :L KK # # + + -K* : 1B6tEDU LB7L72L )#L1K;>LL LL&L=c |j}|J|j|k7rB|dk(rdnd}|dk(rdnd}d|d|jdt|d|d |d }t ||dk(rYt j x}|jk7r6d |jdt|d |d |j}t ||xjdz c_t|S)Nrr downgradeupgradezCannot acquire z lock on rz): already holding a z lock (z not allowed)zCannot acquire write lock on z) from thread z while it is held by thread rr) rnr4rSrrrjrr6r2r )rsr4ropposite directionrVcurs r$rz%SoftReadWriteLock._validate_reentrantszz 99 "&&.wfH'+v~ 9I!$y0@ BtH:V%%-Jgi[ O s# # 7?y':':'< <AUAUU//?{2d8*U"e#?@T@T?UW s# # a !t,,r#cjdfd }dfd }j||| j|||jj dfS#t$r!tjj wxYw)Ncjj5tjjj t j tjjr dddy tjj dddy#t$r YdddywxYw#1swYyxYw)NrInowFT) rlr_break_stale_markerrirrIr _file_exists_atomic_create_markerFileExistsError)rsr,sr$try_claim_writerz@SoftReadWriteLock._acquire_writer_slot..try_claim_writers"" !#DKK$5$5tG[G[aeajajalm 1 12  ! !!)$++*;*;UC  !'!  ! ! !  !s*AC B++ B?4C>B??CC cJjj5tt5t j j dddjtjj cdddS#1swYFxYw#1swYyxYwN) rlrrr_touchrir_break_stale_readersr _any_readersrsr$readers_drained_touchingzHSoftReadWriteLock._acquire_writer_slot..readers_drained_touchings~"" /g&.4;;,,-.))$))+6,,..  / /.. / /s"B B ;B B BB"rFr]r8)_open_readers_dir _wait_forr rrir)rsr,rrFrrs`` r$rz&SoftReadWriteLock._acquire_writer_slots    / '(XN  NN3hQYN Z {{  %''   DKK%% &  s A!!*B cTjtjjdt j j ttjjz dfd }j|||dfSdfS)N.cfjj5tjjj t j tjjr dddytn t dddy#1swYyxYw)NrFrT) rlrrrirrIrrr)rfull_reader_path reader_namersr,sr$try_claim_readerz@SoftReadWriteLock._acquire_reader_slot..try_claim_readers"" #DKK$5$5tG[G[aeajajalm 1 12   %)+uVL)*:EB   sAB'B''B0rTr) ruuiduuid4hexrggetpidrmrrrirr)rsr,rrFrrrrs`` @@@r$rz&SoftReadWriteLock._acquire_reader_slots  ))*!BIIK=9 %%tDKK$7$78;FG   '(XN%1 $NN7G$NNr#c |rytj}|st|j|||k\rt|j|j}|t |t ||z d}tj|)Ng)rrr rSrJminmaxsleep)rs predicaterrFr sleep_fors r$rzSoftReadWriteLock._wait_for,s{##%Cdnn--#xdnn--**I# 3x#~s+CD JJy !r#ct|jj}tt5|j ddddt j|jj}tj|jstj|js$|jjd}t||j`trYt jt!t ddzt"z}t j$|jj||_ yyy#1swYxYw)Ni)r4zB exists but is not a directory or is a symlink; refusing to use it O_DIRECTORYr)rrirrrmkdirrglstatstatS_ISLNKst_modeS_ISDIRrrm_SUPPORTS_DIR_FDO_RDONLYgetattr _O_NOFOLLOWopen)rs readers_pathstrVflagss r$rz#SoftReadWriteLock._open_readers_dir@sDKK//0 o & +   E  * +XXdkk)) * << #4<< +C[[(())klCs# #    ',<KK'"mQ"??+ME#%774;;+>+>#FD -= ' + +s EE c0|jD]}yy)NTF)_iter_reader_entries)rs_s r$rzSoftReadWriteLock._any_readersNs **, A r#c#K|jWtj|j5}|D](}t|jr|jdf* dddyt |j j}tj|5}|D]4}t|jrt||jz df6 dddy#1swYyxYw#1swYyxYww)a# Yield ``(name, dirfd_relative)`` pairs for every live reader marker. ``dirfd_relative`` is ``True`` when *name* should be passed to ``dir_fd=``-aware syscalls; ``False`` when *name* is a full path because dirfd-relative I/O is unavailable on this platform. NTF) rmrgscandir_is_housekeeping_namerrrirr)rsitentryrs r$rz&SoftReadWriteLock._iter_reader_entriesSs    +D001 /R/E0<#jj$../ / DKK//0 ZZ % @ @,UZZ8lUZZ78%?? @ @ @  /  @ @s@,C6C C=C6C*6C* C6C'#C6*C3/C6cg} |jD]&\}}|j||r |jndf( |D]\}}t ||j || y#t$rYywxYw)N)rIrr)rappendrmrrrI)rsrnamesrdirfd_relativefds r$rz&SoftReadWriteLock._break_stale_readersfs.0 (,(A(A(C W$n dND$8$8PTUV W `HD" d6J6JPS\^ _ `   s9A"" A.-A.c|jj5|j}| dddy|j}|j}|j r |j nd}dddt}|y|\}}| tj|jsy t||y#1swYPxYw#t$rYywxYw)NFrT) rlr(rnr7r,r9rm _read_markerhmaccompare_digestrFileNotFoundError)rsrr7r,r read_resultinfo_mtimes r$rz!SoftReadWriteLock._refresh_markerps [[ ! ! F::D| F F**KJJE-1^^T))F  F#;v>  " f r rAr!rjrkrBrtrrzr~rwr}rrx classmethodrrrrrrrrrrrrr"r#r$r^r^s$,\@S?TJ<T$inn&O 0 !$((,#0)00  0  0"0&00 0dQU&RV&ATXA.BUYB6,"(-(&T:  :)::  :  ::*D.D.D.  D.  D.L-(&(&( &(  &(  &(POO O  O  O4"%" "  "  "( G @&`. &r#r^) metaclassc<eZdZ dfd ZddZxZS)r:cRt||d||_||_||_y)NT)rdaemon)rLrt_refresh _interval _stop_event)rsrrrrrWs r$rtz_HeartbeatThread.__init__s- d40 !%r#c|jj|jsR|js|jj y|jj|jsQyyr)r waitr r rrs r$runz_HeartbeatThread.runsR""''7==?  $$&""''7r#) rrrr[rr<rrr]rr)rrr rtrr_r`s@r$r:r:s= &# & &$ &  &  &r#r:rctjtjztjztz}t r|tj ||d|}ntj ||d} |dtjdtjdjd}tj||tj|y#tj|wxYw)Nir ascii) rgO_CREATO_EXCLO_WRONLYrrrrsocket gethostnameencoderr)rr,rrrcontents r$rrs JJ "R[[ 0; >EF. WWT5% 7 WWT5% (G2biik]"V-?-?-A,B"ELLWU W   s 4ACC5ctjtz} tr|tj|||ntj||} tj |}tj|tdz} tj|t||jfS#t $rYywxYw#t $rYtj|ywxYw#tj|wxYw)Nrr) rgrrrrrfstatr_MAX_MARKER_SIZEr_parse_marker_bytesst_mtime)rrrrrdatas r$rrs KK+ %E4DI[RWWT5 0acahahimotau "B772/!34D  t $bkk 11        s56B02B?0 B<;B<? C C#C  C##C:c|rt|tkDry |jd}t j d|tj }|yt|dd}|dkDryt|d||dS#t$rYywxYw) Nru \A # start of string (?P [0-9a-f]{32} ) \n # 128-bit hex token (?P [1-9][0-9]{0,9} ) \n # decimal pid: no leading zero, ≤ 10 digits (?P [\x21-\x7e]{1,253}) # printable non-whitespace ASCII (RFC 1123 hostname limit) \n* # tolerate sloppy writers that append extra newlines \Z # end of string r. ir,r/)r,r.r/) lenrdecodeUnicodeDecodeErrorrematchVERBOSEr-r+)rtextr%r.s r$rrs 3t9//{{7# HH    E } eElB C Y U7^uZ?P QQ' sA99 BBc(t||}|y|\}}||z |kry|t||y|tdtjdt j d} tr|tj||||nt|j|t||}|y|\} } | t||ytj|j| jsy| |kDryt||y#t$rYywxYw)NrFTrr) src_dir_fd dst_dir_fd)rr _BREAK_SUFFIXrgrrrrrenamerrrrr,) rrIrrr info_before mtime_before break_name read_after info_after mtime_afters r$rrs"tF3K +K \_,V$6-"))+a8I8I"8M7NOJ  2 IIdJ6f M J  j )j8J(J  6*   {00*2B2B C\! Jv&  s% ? +@A!@ r#)rrr,rrr5r]r)rrrr5r]z'tuple[_MarkerInfo | None, float] | None)rbytesr]z_MarkerInfo | None) rrrIr[rr[rr5r]r8)rrrr5r]r)r;rr]r8)rrr]r8r)Ir> __future__rrJrrgr$rrrsysrjrr contextlibrr dataclassesrpathlibrtypingrr weakrefr filelock._apir filelock._errorr filelock._softr filelock._utilrcollections.abcrrr3r+rrrplatformrsupports_dir_fdrrr!rkrqrIrLrr&r+r1typer@r^Threadr:rrrrrrrrrBrErr__all__r"r#r$r`s`"   /!)',#'23   b,* <<7*Lrww":L:L/L?R?T<T$inn& $     $   $ $  $.$.bQ&+Q&hy''(JN 592&RF * **  *  *  *Z04 /3$9.)   r#