3jb%SrSSKJr SSKrSSKrSSKrSSKrSSKrSSKrSSK r SSK r SSK r SSK r SSK r SSKJrJr SSKJr SSKJr SSKJrJr SSKJr SS KJr SS KJr SS KJr SS K J!r! \(aSS K"J#r#J$r$ \Sr%Sr&Sr'\("\SS5r)\("\SS5r*\ RVS:g=(a \RX\RZ;r.\"5r/S\0S'\ Rb"5q2Sq3Sq4\"SS9"SS55r5\"SS55r6\"SS9"SS55r7\"SS 55r8"S!S"\95r:"S#S$\:S%9r;"S&S'\ Rx5r=SS(.S4S)jjr>SS(.S5S*jjr?S6S+jr@SS(.S7S,jjrASS(.S8S-jjrBSS(.S8S.jjrCS9S/jrDS:S0jrES;S1jrFS;S2jrGS;S3jrHS$/rIg)@N?blocking is_singletonheartbeat_intervalstale_threshold poll_intervalc >U(d[T U]UUUUUUUS9$[U5R5nUR UR R U5n U c"[T U]UUUUUUUS9n XR U'OMU RU:wdU RU:wa-SU RSU RSUSU3n [U 5eU sSSS5 $!,(df  g=f)NrMz$Singleton lock created with timeout=z , blocking=z, cannot be changed to timeout=) super__call__rresolverJrIgettimeoutrN ValueError) cls lock_filerXrNrOrPrQrR normalizedinstancemsg __class__s r(rU_SoftRWMeta.__call__Us7#!)#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 rrITrKNrLrMc ,US::aSU3n[U5eUcUS-nXe::aSUSUS3n[U5eUS::aSU3n[U5e[R"U5UlX lX0lXPlX`lXpl[URS3URS 3URS 3S 9Ul [UR5 [[R"5[R"5[URR S S 9S9UlSUlSUlSUlSUl[, U[.[1UR5R35'[55 SSS5 g!,(df  g=f)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)rrrrbrXr-r.rF)rYosfspathr[rXrNrPrQrRr_pathsrr* threadingLockr r_locks_readers_dir_fd_hold_fork_invalidated_closed_all_instances_lockrrrV_register_hooks) selfr[rXrNrOrPrQrRr^s r(__init__SoftReadWriteLock.__init__ss  "=>P=QRCS/ !  "014O  0D_DUUYZlYmmnoCS/ ! A 8HCS/ ! ii 2% & );&5$1^^$F+^^$F+~~&h/  /^^%!(t{{00"=  ,0#' '," =AN4/779 :  ! s 5F FrNc#~# URXS9 Sv UR5 g!UR5 f=f7f)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 rN) acquire_readreleaser}rXrNs r( read_lockSoftReadWriteLock.read_locks2 '5   LLNDLLN=(=:=c#~# URXS9 Sv UR5 g!UR5 f=f7f)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 rN) acquire_writerrs r( write_lockSoftReadWriteLock.write_locks2 76   LLNDLLNrc"URSXS9$)u 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 rr_acquirers r(rSoftReadWriteLock.acquire_reads*}}VW}@@r'c"URSXS9$)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 rrrrs r(rSoftReadWriteLock.acquire_write%s2}}Wg}AAr'cURSS9 URR UR(a SSS5 gSUlURb?[ [ 5 [R"UR5 SSS5 SUlSSS5 g!,(df  N=f!,(df  g=f)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) rrvr-rzrwrOSErrorrqcloser}s r(rSoftReadWriteLock.close@s 4  [[ ! !||" ! DL##/g&HHT112''+$" ! '& " !s)B/#B/%!BB/ B, (B// B=FrcURR UR(aSUlSSS5 gURnUc8U(a SSS5 gSURS[ U5S3n[ U5eU(aSUlOU=RS-slURS:a SSS5 gSUlSSS5 WRR5 URRURS-S9 UR(a[URUR S 9 g[UR5 g!,(df  N=f) a 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?rodir_fd)rvr-ryrxr[id RuntimeErrorr9rDsetrBjoinrPr@_unlinkr>rw)r}rholdr^s r(rSoftReadWriteLock.releaseQs[[ ! !%%!  " ! ::D|" !2$..1ARPTXJVhi"3''  a zzA~!" !"DJ#", ! ""4+B+BS+H"I >> D$$T-A-A B D$$ %7" !sEEAE?E E"cU"XUS9$)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 rr)rZr[rXrNs r(get_lockSoftReadWriteLock.get_lock{s(999r'cUc UROUnUc UROUnURR UR(aSUR S3n[ U5eUR(aSUR S3n[ U5eURbURU5sSSS5 $SSS5 [R"5nU(d$URRRSS9nONUS:Xa$URRRSS9nO$URRRSUS9nU(d[UR 5SeURXXSS9URRR!5 $!,(df  N=f!URRR!5 f=f) NzSoftReadWriteLock on z4 was invalidated by fork(); construct a new instancez has been closedFrrbT)rNrX)rXrNrvr-ryr[rrzrx_validate_reentranttime perf_counterr.acquirer _do_acquire_innerr)r}r;rXrNr^startacquireds r(rSoftReadWriteLock._acquires#*/$,,w$,$44==( [[ ! !%%-dnn-==qr"3''||-dnn-==MN"3''zz%//5" !&"!!#{{..666FH ]{{..666EH{{..66g6VH$..)t 3 .))$)R KK # # + + --" !, KK # # + + -sA6F".F3" F03&Gc URR URbURU5sSSS5 $SSS5 US:XaSOX2-n[R "S5nUS:XaUR XeUS9upxOURXeUS9upx[R"5n [URURU S[U5S3S9n URR [SUUS:Xa[R"5OSUUUU U S 9UlSSS5 U R!5 [#US 9$!,(df  GN=f!,(df  N9=f) NrbrdeadlinerNzfilelock-heartbeat-x)refreshinterval stop_eventnamer)r9r;r=r>r@r2rBrDlock)rvr-rxrsecrets token_hex_acquire_writer_slot_acquire_reader_slotrtEventrA_refresh_markerrPrr7 get_identrr ) r}r;effective_timeoutrrNrr2r>r@r heartbeats r(r#SoftReadWriteLock._do_acquire_innersD[[ ! !zz%//5" !%"-248Q!!"% 7?%)%>%>ubj%>%k "K%)%>%>ubj%>%k "K__& $((,,!&r$xl3  [[ ! !9= 3 3 5d'#!*) DJ" !t,,9" ! " !sD?-1E? E Ec URnUceURU:waDUS:XaSOSnUS:XaSOSnSUSURS[U5SUS US 3 n[ U5eUS:XaZ[ R "5=obR:wa6S URS[U5S US UR3n[ U5eU=RS- sl[US9$)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) rxr;r[rrrtrr=r9r )r}r;ropposite directionr^curs r(r%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'c^^TR5 SUU4SjjnSU4SjjnTRXBUS9 TRXRUS9 TRR S4$![a! [TRR 5 ef=f)Nc>TRR [TRRTR [ R "5S9 [TRR5(a SSS5 g[TRRT5 SSS5 g![a SSS5 gf=f!,(df  g=f)NrQnowFT) rvr_break_stale_markerrsrrQr _file_exists_atomic_create_markerFileExistsError)r}r2sr(try_claim_writer@SoftReadWriteLock._acquire_writer_slot..try_claim_writers""#DKK$5$5tG[G[aeajajalm 1 122 #"!)$++*;*;UC #'! #" ! #"s*A"C B.. C8CCC Cch>TRR [[5 [ TR R 5 SSS5 TR[R"55 TR5(+sSSS5 $!,(df  NP=f!,(df  g=fN) rvrrr_touchrsr_break_stale_readersr _any_readersrsr(readers_drained_touchingHSoftReadWriteLock._acquire_writer_slot..readers_drained_touchingsn""g&4;;,,-'))$))+6,,.. #"'&#"s#B# BAB# B B## B1rFrfr?)_open_readers_dir _wait_forr rrsr)r}r2rrNrrs`` r(r&SoftReadWriteLock._acquire_writer_slots     / 'XN  NN3QYN Z {{  %''   DKK%% &  s A+BcV^^^^^TR5 [R"5RS[R "53mTR m[[TRR5T- 5mSUUUUU4SjjnTRXBUS9 TbTS4$TS4$)N.cr>TRR [TRRTR [ R "5S9 [TRR5(a SSS5 gTb [TTTS9 O [TT5 SSS5 g!,(df  g=f)NrFrT) rvrrrsrrQrrr)rfull_reader_path reader_namer}r2sr(try_claim_reader@SoftReadWriteLock._acquire_reader_slot..try_claim_reader!s""#DKK$5$5tG[G[aeajajalm 1 122 #"%)+uVL)*:EB#""sA"B(B(( B6rTr) ruuiduuid4hexrqgetpidrwrrrsrr)r}r2rrNrrrrs`` @@@r(r&SoftReadWriteLock._acquire_reader_slots  ))*!BIIK=9 %%tDKK$7$78;FG   'XN%1 $NN7G$NNr'c8U"5(ag[R"5nU(d[UR5eUbXB:a[UR5eURnUb[ U[ X$- S55n[R"U5 M)Ng)rrr r[rRminmaxsleep)r} predicaterrNr sleep_fors r(rSoftReadWriteLock._wait_for/s{{##%Cdnn--#dnn--**I# 3x~s+CD JJy !r'c[URR5n[[5 UR SS9 SSS5 [ R"URR5n[R"UR5(d%[R"UR5(d$URRS3n[U5eURcf[(aZ[ R[![ SS5-["-n[ R$"URRU5Ul ggg!,(df  GN=f)Ni)r;zB exists but is not a directory or is a symlink; refusing to use it O_DIRECTORYr)rrsrrrmkdirrqlstatstatS_ISLNKst_modeS_ISDIRrrw_SUPPORTS_DIR_FDO_RDONLYgetattr _O_NOFOLLOWopen)r} readers_pathstr^flagss r(r#SoftReadWriteLock._open_readers_dirCsDKK//0 o &   E  *'XXdkk)) * << # #4<< +C+C[[(())klCs# #    ',<,<KK'"mQ"??+ME#%774;;+>+>#FD -= '' &s E E"c2UR5Hn g g)NTF)_iter_reader_entries)r}_s r(rSoftReadWriteLock._any_readersQs**,A-r'c#$# URb_[R"UR5nUH/n[UR5(aMURS4v M1 SSS5 g[ UR R5n[R"U5nUH:n[UR5(aM[X2R- 5S4v M< SSS5 g!,(df  g=f!,(df  g=f7f)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) rwrqscandir_is_housekeeping_namerrrsrr)r}itentryrs r(r&SoftReadWriteLock._iter_reader_entriesVs    +D001RE0<<#jj$.. 2 DKK//0 ZZ %,UZZ88lZZ78%??& % 21  % %s@.DC.C.&>D$C?C?% D. C<8D? D  Dc/nUR5H*up4URX4(a UROS45 M, UHup5[ X0R XS9 M g![a gf=f)N)rQrr)rappendrwrrrQ)r}rnamesrdirfd_relativefds r(r&SoftReadWriteLock._break_stale_readersisr.0 (,(A(A(C$ dND$8$8PTUV)DHD 6J6JPS _   s>A"" A/.A/cURR URnUc SSS5 gURnURnUR (a UR OSnSSS5 [WWS9nUcgUupgUb&[R"URW5(dg[X$S9 g!,(df  NU=f![a g[a gf=f)NFrT) rvr-rxr>r2r@rw _read_markerhmaccompare_digestrFileNotFoundErrorr)r}rr>r2r read_resultinfo_mtimes r(r!SoftReadWriteLock._refresh_markerss [[ ! !::D|" !**KJJE-1^^T))F "#;v>  "  [TU]USS9 XlX lX0lg)NT)rdaemon)rTr~_refresh _interval _stop_event)r}rrrrr_s r(r~_HeartbeatThread.__init__s' d40 !%r'cURRUR5(d]UR5(dURR 5 gURRUR5(dM\ggr)r-waitr,r+rrs r(run_HeartbeatThread.runsZ""''77==??  $$&""''77r')r,r+r-) rr%rrdrrCrrrfr"r$)r!r"r#r$r~r1r&rhris@r(rArAsB &# & &$ &  &  &r'rArc[R[R-[R-[-n[ (aUb[R "XSUS9nO[R "XS5nUS[R"5S[R"5S3RS5n[R"XE5 [R"U5 g![R"U5 f=f)Nir ascii) rqO_CREATO_EXCLO_WRONLYrrrrsocket gethostnameencoderr)rr2rrrcontents r(rrs JJ "R[[ 0; >EF. WWT% 7 WWT% (G2biik]"V-?-?-A,B"ELLWU    s 7AC$$C<c[R[-[-n[(aUb[R "XUS9O[R "X5n[R"U5n[R"U[S-5n[R"U5 [U5UR4$![ a gf=f![ a [R"U5 gf=f![R"U5 f=f)Nrr) rqrr _O_NONBLOCKrrrfstatr_MAX_MARKER_SIZEr_parse_marker_bytesst_mtime)rrrrrdatas r(rrs KK+ % 3E4D4DI[RWWT 0acahahimau "B772/!34D  t $bkk 11        s59B=4C = C  C  C0C3/C00C33D cU(a[U5[:agURS5n[R "SU[R 5nUcg[USS5nUS:ag[USX2SS9$![a gf=f) Nr5u \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 r4 ir2r5)r2r4r5) lenr@decodeUnicodeDecodeErrorrematchVERBOSEr3r0)rCtextrJr4s r(rArAs 3t9//{{7# HH    E } eElB C Y U7^Z?P QQ' sA>> B  B c[XS9nUcgUupVX&- U::agUc [XS9 gU[S[R"5S[ R "S53n[(aUb[R"XX3S9 O[U5RU5 [XsS9nUcgUupU c [XsS9 g[R"URU R5(dgX:ag[XsS9 g![a gf=f)NrFTrr) src_dir_fd dst_dir_fd)rr _BREAK_SUFFIXrqrrrrrenamerrrrr2) rrQrrr info_before mtime_before break_name read_after info_after mtime_afters r(rrst3K +K _,$6-"))+a8I8I"8M7NOJ   2 IId6 M J  j )j8J(J *   {00*2B2B C C! J&  s #C>C>> D  D c[[5 [(aUb[R"XS9 O[ U5R 5 SSS5 g!,(df  g=fNr)rrrrqunlinkrrrs r(rr!s> # $   2 IId * J    % $ $s =A A$c|[(aUb[R"USUS9 g[R"US5 grY)rrqutimer[s r(rr*s+F. tF+ tr'c[R"U5n[R"UR 5$![a gf=f)NF)rqrrrS_ISREGr)pathrs r(rr1s= XXd^ << ## s8 AAcDURS5=(d [U;$)Nr) startswithrP)rs r(r r 9s ??3  8=D#88r'c[R"5q[[R 55HnUR 5 M gr)rtrur{listrvaluesr r]s r(_reset_all_after_forkrg=s5 $..*..01++-2r'c[[R55H*n[[5 UR SS9 SSS5 M, g!,(df  M>=f)NTr)rdrrer Exceptionrrfs r(_cleanup_all_instancesrjGsB..01 i   4  (! 2 s A  A c[(d[R"[5 Sq[(d1[ [ S5(a[ R"[S9 Sqggg)NTregister_at_fork)after_in_child) _atexit_registeredatexitregisterrj_fork_registeredhasattrrqrlrgrr'r(r|r|MsL  ./!  ,> ? ? +@A!@ r')rrr2rrr<rfr")rrrr<rfz'tuple[_MarkerInfo | None, float] | None)rCbytesrfz_MarkerInfo | None) rrrQrdrrdrr<rfr?)rrrr<rfr")r`rrfr?)rrrfr?r$)JrE __future__rrorrqrIrr9rsysrtrr contextlibrr dataclassesrpathlibrtypingrr weakrefr filelock._apir filelock._errorr filelock._softr filelock._utilrcollections.abcrrr:rPr@rrr>platformrsupports_dir_fdrrr%rur{rnrqrr*r0r7typerGrgThreadrArrrArrrrr rgrjr|__all__rr'r(rs`"   /!)',#'23   b,* b,* <<7*Lrww":L:L/L?R?T<Tnn& $     $   $ $  $.$.bZ&+Z&zy''(JN 592(RF * **  *  *  *Z04 /3$9.)   r'