+
    }i%                       ^ RI Ht ^ RIt^ RIHt ^ RIHt ^ RIHtH	t	H
t
 ^ RIHt ^ RIHt ^ RIHt ^ R	IHt ^ R
IHt ^ RIHt ]'       d   ^ RIHt ^ RIHt ]! ]4      t]. ]3,          t]! R4       ! R R4      4       tR# )    )annotationsN)Callable)	getLogger)TYPE_CHECKINGLiteraloverload)service_locator)ensure_context)
docs_group)RecoverableState)Session)SessionPoolModel)TracebackType)EventManagerzSession managementc                     ] tR t^tRtRRRRRRRRRR	R
RRR/R R lltR R lt]R R l4       t]R R l4       t	]R R l4       t
]R R l4       tR R ltR R lt]R R l4       t]R R  l4       t]R!R	/R" R# ll4       t]R$ R% l4       t]R& R' l4       t]R( R) l4       tR* R+ ltR, R- ltR. R/ ltR0 R1 ltR2 R3 ltR4tR# )5SessionPoola`  A pool of sessions that are managed, rotated, and persisted based on usage and age.

It ensures effective session management by maintaining a pool of sessions and rotating them based on
usage count, expiration time, or custom rules. It provides methods to retrieve sessions, manage their
lifecycle, and optionally persist the state to enable recovery.
max_pool_sizei  create_session_settingsNcreate_session_functionevent_managerpersistence_enabledFpersist_state_kvs_namepersist_state_keyCRAWLEE_SESSION_POOL_STATEc               8    V ^8  d   QhRRRRRRRRR	R
RRRRRR/# )   r   intr   zdict | Noner   z CreateSessionFunctionType | Noner   zEventManager | Noner   boolr   z
str | Noner   strreturnNone )formats   "p/Users/ahmad/.openclaw/workspace/my-crawler/.venv/lib/python3.14/site-packages/crawlee/sessions/_session_pool.py__annotate__SessionPool.__annotate__$   s]     0 0 0 "-	0
 "B0 +0 "0 !+0 0 
0    c               P   V'       d   \         P                  ! V4       \        \        V/ R7      \        TTT;'       g    RR7      V n        Wn        T;'       g    / V n        W0n        WPn	        V P                  '       d   V P                  '       d   \        R4      hRV n        R# )a  Initialize a new instance.

Args:
    max_pool_size: Maximum number of sessions to maintain in the pool. You can add more sessions to the pool
        by using the `add_session` method.
    create_session_settings: Settings for creating new session instances. If None, default settings will
        be used. Do not set it if you are providing a `create_session_function`.
    create_session_function: A callable to create new session instances. If None, a default session settings
        will be used. Do not set it if you are providing `create_session_settings`.
    event_manager: The event manager to handle events like persist state.
    persistence_enabled: Flag to enable or disable state persistence of the pool.
    persist_state_kvs_name: The name of the `KeyValueStore` used for state persistence.
    persist_state_key: The key under which the session pool's state is stored in the `KeyValueStore`.
)r   sessionsr   )default_stateloggerr   r   r   zPBoth `create_session_settings` and `create_session_function` cannot be provided.FN)r	   set_event_managerr   r   r+   _state_max_pool_size_session_settings_create_session_function_persistence_enabled
ValueError_active)selfr   r   r   r   r   r   r   s   &$$$$$$$r$   __init__SessionPool.__init__$   s    2 --m<&*+  3#9/OO3O	
 ,!8!>!>B(?%$7!(((T-C-C-Copp r'   c                   V ^8  d   QhRR/# )r   r    r   r"   )r#   s   "r$   r%   r&   V   s     N N# Nr'   c                \    RV P                   P                   RV P                  RR7       R2# )zGet a string representation.< F)as_dict>)	__class____name__	get_stater4   s   &r$   __repr__SessionPool.__repr__V   s.    4>>**+1T^^E^-J,K1MMr'   c                   V ^8  d   QhRR/# r   r    r   r"   )r#   s   "r$   r%   r&   [   s     7 7s 7r'   c                T    \        V P                  P                  P                  4      # )zBGet the total number of sessions currently maintained in the pool.)lenr-   current_valuer)   r@   s   &r$   session_countSessionPool.session_countZ   s     4;;,,5566r'   c                   V ^8  d   QhRR/# rD   r"   )r#   s   "r$   r%   r&   `   s     > >c >r'   c                B    V P                   P                  P                  # )z5Get the number of sessions that are currently usable.)r-   rG   usable_session_countr@   s   &r$   rL    SessionPool.usable_session_count_   s     {{((===r'   c                   V ^8  d   QhRR/# rD   r"   )r#   s   "r$   r%   r&   e   s     ? ?s ?r'   c                B    V P                   P                  P                  # )z5Get the number of sessions that are no longer usable.)r-   rG   retired_session_countr@   s   &r$   rP   !SessionPool.retired_session_countd   s     {{((>>>r'   c                   V ^8  d   QhRR/# )r   r    r   r"   )r#   s   "r$   r%   r&   j   s       r'   c                    V P                   # )z'Indicate whether the context is active.)r3   r@   s   &r$   activeSessionPool.activei   s     ||r'   c                   V ^8  d   QhRR/# )r   r    r   r"   )r#   s   "r$   r%   r&   n   s      + r'   c                h  "   V P                   '       d$   \        RV P                  P                   R24      hRV n         V P                  P                  4       G Rj  xL
 pV P                  Vn        V P                  4        VP                  '       g   V P                  4       G Rj  xL
  V #  LQ L5i)z|Initialize the pool upon entering the context manager.

Raises:
    RuntimeError: If the context manager is already active.
The z is already active.TN)r3   RuntimeErrorr=   r>   r-   
initializer.   r   _remove_retired_sessionsr)   _fill_sessions_to_maxr4   states   & r$   
__aenter__SessionPool.__aenter__n   s      <<<dnn&=&=%>>QRSSkk,,.."11%%'~~~,,... /
 /s*   AB2B.6B2B2'B0(B20B2c               (    V ^8  d   QhRRRRRRRR/# )	r   exc_typeztype[BaseException] | None	exc_valuezBaseException | Noneexc_tracebackzTracebackType | Noner    r!   r"   )r#   s   "r$   r%   r&      s2      , ( ,	
 
r'   c                   "   V P                   '       g$   \        RV P                  P                   R24      hV P                  P                  4       G Rj  xL
  RV n         R#  L5i)zyDeinitialize the pool upon exiting the context manager.

Raises:
    RuntimeError: If the context manager is not active.
rX   z is not active.NF)r3   rY   r=   r>   r-   teardown)r4   rb   rc   rd   s   &&&&r$   	__aexit__SessionPool.__aexit__   sQ      |||dnn&=&=%>oNOOkk""$$$ 	%s   AA%A#A%c                    V ^8  d   QhRRRR/# )r   r;   zLiteral[True]r    dictr"   )r#   s   "r$   r%   r&      s    ??M?d?r'   c               	    R # Nr"   r4   r;   s   &$r$   r?   SessionPool.get_state   s    <?r'   c                    V ^8  d   QhRRRR/# )r   r;   zLiteral[False]r    r   r"   )r#   s   "r$   r%   r&      s    LLNL7GLr'   c               	    R # rl   r"   rm   s   &$r$   r?   rn      s    ILr'   r;   c                    V ^8  d   QhRRRR/# )r   r;   r   r    zSessionPoolModel | dictr"   )r#   s   "r$   r%   r&      s      D 5L r'   c                   V P                   P                  P                  RR7      pV'       d   VP                  4       # V# )zLRetrieve the current state of the pool either as a model or as a dictionary.T)deep)r-   rG   
model_copy
model_dump)r4   r;   models   &$ r$   r?   rn      s8     ))44$4?##%%r'   c                    V ^8  d   QhRRRR/# )r   sessionr   r    r!   r"   )r#   s   "r$   r%   r&      s     - -7 -t -r'   c                    V P                   P                  pVP                  VP                  9   d&   \        P                  RVP                   R24       R# WP                  VP                  &   R# )a	  Add an externally created session to the pool.

This is intended only for the cases when you want to add a session that was created outside of the pool.
Otherwise, the pool will create new sessions automatically.

Args:
    session: The session to add to the pool.
Session with ID z already exists in the pool.N)r-   rG   idr)   r+   warning)r4   rx   r^   s   && r$   add_sessionSessionPool.add_session   sQ     ))::'NN-gjj\9UVW%,wzz"r'   c                   V ^8  d   QhRR/# r   r    r   r"   )r#   s   "r$   r%   r&      s     0 07 0r'   c                   "   V P                  4       G Rj  xL
  V P                  4       pVP                  '       d   V# V P                  4        V P	                  4       G Rj  xL
 #  LP L5i)a   Retrieve a random session from the pool.

This method first ensures the session pool is at its maximum capacity. If the random session is not usable,
retired sessions are removed and a new session is created and returned.

Returns:
    The session object.
N)r\   _get_random_session	is_usabler[   _create_new_session)r4   rx   s   & r$   get_sessionSessionPool.get_session   sb      ((*****,N 	%%'--/// 	+ 0s&   A+A'%A+%A+"A)#A+)A+c                    V ^8  d   QhRRRR/# )r   
session_idr   r    zSession | Noner"   )r#   s   "r$   r%   r&      s      # . r'   c                @  "   V P                  4       G Rj  xL
  V P                  P                  P                  P	                  V4      pV'       g   \
        P                  RV R24       R# VP                  '       g   \
        P                  RV R24       R# V#  L5i)ae  Retrieve a session by ID from the pool.

This method first ensures the session pool is at its maximum capacity. It then tries to retrieve a specific
session by ID. If the session is not found or not usable, `None` is returned.

Args:
    session_id: The ID of the session to retrieve.

Returns:
    The session object if found and usable, otherwise `None`.
Nrz   z not found.z is not usable.)r\   r-   rG   r)   getr+   r|   r   )r4   r   rx   s   && r$   get_session_by_idSessionPool.get_session_by_id   s      ((***++++4488DNN-j\EF   NN-j\IJ 	+s   BB:B,B?Bc                   V ^8  d   QhRR/# r   r    r!   r"   )r#   s   "r$   r%   r&      s     " "4 "r'   c                V   "   V P                   P                  4       G Rj  xL
  R#  L5i)z0Reset the KVS where the pool state is persisted.N)r-   resetr@   s   &r$   reset_storeSessionPool.reset_store   s     kk!!!s   )')c                   V ^8  d   QhRR/# r   r"   )r#   s   "r$   r%   r&      s      7 r'   c                   "   V P                   '       d   V P                  4       pM\        R/ V P                  B pWP                  P                  P
                  VP                  &   V# 5i)z7Create a new session, add it to the pool and return it.r"   )r0   r   r/   r-   rG   r)   r{   )r4   new_sessions   & r$   r   SessionPool._create_new_session   sT     (((779K!;D$:$:;K=H!!**;>>:s   A'A)c                   V ^8  d   QhRR/# r   r"   )r#   s   "r$   r%   r&      s     - -T -r'   c                   "   \        V P                  V P                  ,
          4       F  pV P                  4       G Rj  xL
  K  	  R#  L
5i)z0Fill the pool with sessions to the maximum size.N)ranger.   rH   r   )r4   _s   & r$   r\   !SessionPool._fill_sessions_to_max   s;     t**T-?-??@A**,,, A,s   =AA
 Ac                   V ^8  d   QhRR/# r   r"   )r#   s   "r$   r%   r&      s     < <W <r'   c                    V P                   P                  pVP                  '       g   \        R4      h\        P
                  ! \        VP                  P                  4       4      4      # )z#Get a random session from the pool.z"No sessions available in the pool.)r-   rG   r)   r2   randomchoicelistvaluesr]   s   & r$   r   SessionPool._get_random_session   sG    ))~~~ABB}}T%.."7"7"9:;;r'   c                   V ^8  d   QhRR/# r   r"   )r#   s   "r$   r%   r&      s     k k$ kr'   c                    V P                   P                  pVP                  P                  4        Uu/ uF#  q"P                  '       g   K  VP
                  VbK%  	  upVn        R# u upi )z<Remove all sessions from the pool that are no longer usable.N)r-   rG   r)   r   r   r{   )r4   r^   rx   s   &  r$   r[   $SessionPool._remove_retired_sessions   sK    ))=B^^=R=R=Tj=T'XiXi-'**g-=Tjjs   A&A&)r3   r0   r.   r1   r/   r-   )r>   
__module____qualname____firstlineno____doc__r5   rA   propertyrH   rL   rP   rT   r_   rg   r   r?   r
   r}   r   r   r   r   r\   r   r[   __static_attributes__r"   r'   r$   r   r      sH   0 "0 04	0
 EI0 .20 %*0 .20 ">0dN 7 7 > > ? ?  ($ ? ?L L5   - -  0 0&  2"-
<k kr'   r   )
__future__r   r   collections.abcr   loggingr   typingr   r   r   crawleer	   crawlee._utils.contextr
   crawlee._utils.docsr    crawlee._utils.recoverable_stater   crawlee.sessionsr   crawlee.sessions._modelsr   typesr   crawlee.eventsr   r>   r+   CreateSessionFunctionTyper   r"   r'   r$   <module>r      sr    #  $  3 3 # 1 * = $ 5#+	8	$R[1   !ak ak "akr'   