+
    }i%                        ^ RI Ht ^ RIHtHtHt ^ RIHt ^ RIHtH	t	H
t
Ht ^ RIHt ^ RIHt ^ RIHtHt ]'       d   ^ RIHt ^ R	IHt ]! ]4      t]! R
4       ! R R4      4       tR# )    )annotations)datetime	timedeltatimezone)	getLogger)TYPE_CHECKINGClassVarLiteraloverload)crypto_random_object_id)
docs_group)CookieParamSessionCookies)	CookieJarSessionModelzSession managementc                     ] tR t^t$ Rt. RDOtR]R&    RRR]! ^2R7      RRR	R
RRRRR^ R^2RRRRRR/R R llt]	R R l4       t
R R ltR R 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4       t]R( R) l4       t]R* R+ l4       t]R, R- l4       t]R. R/ l4       t]R0 R1 l4       t]R2 R3 l4       t]R4 R5 l4       tR6R7/R8 R9 lltR: R; ltR< R= ltR> R? ltR@R/RA RB lltRCtR# )ESessiona  Represent a single user session, managing cookies, error states, and usage limits.

A `Session` simulates a specific user with attributes like cookies, IP (via proxy), and potentially
a unique browser fingerprint. It maintains its internal state, which can include custom user data
(e.g., authorization tokens or headers) and tracks its usability through metrics such as error score,
usage count, and expiration.
r	   _DEFAULT_BLOCKED_STATUS_CODESidNmax_age)minutes	user_datamax_error_scoreg      @error_score_decrementg      ?
created_atusage_countmax_usage_counterror_scoreg        cookiesblocked_status_codesc               H    V ^8  d   QhRRRRRRRRR	RR
RRRRRRRRRRRRR/# )   r   z
str | Noner   r   r   zdict | Noner   floatr   r   zdatetime | Noner   intr   r   r    zFSessionCookies | CookieJar | dict[str, str] | list[CookieParam] | Noner!   zlist | NonereturnNone )formats   "k/Users/ahmad/.openclaw/workspace/my-crawler/.venv/lib/python3.14/site-packages/crawlee/sessions/_session.py__annotate__Session.__annotate__"   s     (e (e (e 	(e
 (e (e  %(e $(e (e (e (e X(e *(e 
(e    c                  T;'       g    \        ^
R7      V n        W n        T;'       g    / V n        W@n        WPn        T;'       g%    \        P                  ! \        P                  4      V n
        Wpn        Wn        Wn        \        V
4      ;'       g    \        4       V n        \!        T;'       g    V P"                  4      V n        R# )aY  Initialize a new instance.

Args:
    id: Unique identifier for the session, autogenerated if not provided.
    max_age: Time duration after which the session expires.
    user_data: Custom user data associated with the session.
    max_error_score: Threshold score beyond which the session is considered blocked.
    error_score_decrement: Value by which the error score is decremented on successful operations.
    created_at: Timestamp when the session was created, defaults to current UTC time if not provided.
    usage_count: Number of times the session has been used.
    max_usage_count: Maximum allowable uses of the session before it is considered expired.
    error_score: Current error score of the session.
    cookies: Cookies associated with the session.
    blocked_status_codes: HTTP status codes that indicate a session should be blocked.
)lengthN)r   _id_max_age
_user_data_max_error_score_error_score_decrementr   nowr   utc_created_at_usage_count_max_usage_count_error_scorer   _cookiessetr   _blocked_status_codes)selfr   r   r   r   r   r   r   r   r   r    r!   s   &$$$$$$$$$$$r*   __init__Session.__init__"   s    < ;;0;#//r /&;#%CChll)C' /'&w/CC>3C%()=)c)cAcAc%d"r-   c                    V ^8  d   QhRRRR/# )r#   modelr   r&   r   r(   )r)   s   "r*   r+   r,   M   s     M M| M Mr-   c                f    \        VP                  4      pV ! R/ VP                  R0R7      BRV/B # )z0Initialize a new instance from a `SessionModel`.r    )excluder(   )r   r    
model_dump)clsrB   r    s   && r*   
from_modelSession.from_modelL   s5     !/LU%%yk%:LGLLr-   c                   V ^8  d   QhRR/# r#   r&   strr(   )r)   s   "r*   r+   r,   R   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r>   s   &r*   __repr__Session.__repr__R   s.    4>>**+1T^^E^-J,K1MMr-   c                    V ^8  d   QhRRRR/# )r#   otherobjectr&   boolr(   )r)   s   "r*   r+   r,   V   s     M MF Mt Mr-   c                    \        V\        4      '       g   \        # V P                  RR7      VP                  RR7      8H  # )z"Compare two sessions for equality.TrO   )
isinstancer   NotImplementedrT   )r>   rY   s   &&r*   __eq__Session.__eq__V   s6    %))!!~~d~+ut/LLLr-   c                   V ^8  d   QhRR/# )r#   r&   r%   r(   )r)   s   "r*   r+   r,   \   s     + +# +r-   c                   V P                  RR7      p\        \        \        \        3,          ,          ! 4       p\        VP                  4       4       F  w  r4VR8X  d)   VP                  V\        V P                  4      34       K4  \        V\        \        34      '       d|   \        V\        4      '       d(   VP                  V\        \        V4      4      34       K  VP                  V\        \        \        VP                  4       4      4      4      34       K  VP                  V\        V4      34       K  	  \        \        V4      4      # )z'Return hash based on the session state.TrO   r    )rT   listtuplerK   r%   sorteditemsappendhashr;   r]   dict)r>   statehashable_itemskeyvalues   &    r*   __hash__Session.__hash__\   s    t,eCHo.0 !/JCi%%sD,?&@AED$<00eT**"))3U5\0B*CD"))3U6%++-;P5Q0R*ST%%sDK&89 0 E.)**r-   c                   V ^8  d   QhRR/# rJ   r(   )r)   s   "r*   r+   r,   s   s      C r-   c                    V P                   # )zGet the session ID.)r0   rU   s   &r*   r   
Session.idr   s     xxr-   c                   V ^8  d   QhRR/# )r#   r&   ri   r(   )r)   s   "r*   r+   r,   x   s      4 r-   c                    V P                   # )zGet the user data.)r2   rU   s   &r*   r   Session.user_dataw   s     r-   c                   V ^8  d   QhRR/# )r#   r&   r   r(   )r)   s   "r*   r+   r,   }   s       r-   c                    V P                   # )zGet the cookies.)r;   rU   s   &r*   r    Session.cookies|   s     }}r-   c                   V ^8  d   QhRR/# r#   r&   r$   r(   )r)   s   "r*   r+   r,           ! !U !r-   c                    V P                   # )zGet the current error score.)r:   rU   s   &r*   r   Session.error_score           r-   c                   V ^8  d   QhRR/# rz   r(   )r)   s   "r*   r+   r,      r{   r-   c                    V P                   # )zGet the current usage count.)r8   rU   s   &r*   r   Session.usage_count   r~   r-   c                   V ^8  d   QhRR/# )r#   r&   r   r(   )r)   s   "r*   r+   r,      s     0 0H 0r-   c                <    V P                   V P                  ,           # )z+Get the expiration datetime of the session.)r7   r1   rU   s   &r*   
expires_atSession.expires_at   s     $--//r-   c                   V ^8  d   QhRR/# r#   r&   r[   r(   )r)   s   "r*   r+   r,      s     : :D :r-   c                4    V P                   V P                  8  # )zBIndicate whether the session is blocked based on the error score..)r:   r3   rU   s   &r*   
is_blockedSession.is_blocked          D$9$999r-   c                   V ^8  d   QhRR/# r   r(   )r)   s   "r*   r+   r,      s     = =D =r-   c                d    \         P                  ! \        P                  4      V P                  8  # )zBIndicate whether the session is expired based on the current time.)r   r5   r   r6   r   rU   s   &r*   
is_expiredSession.is_expired   s      ||HLL)T__<<r-   c                   V ^8  d   QhRR/# r   r(   )r)   s   "r*   r+   r,      s     : :D :r-   c                4    V P                   V P                  8  # )zAIndicate whether the session has reached its maximum usage limit.)r8   r9   rU   s   &r*   is_max_usage_count_reached"Session.is_max_usage_count_reached   r   r-   c                   V ^8  d   QhRR/# r   r(   )r)   s   "r*   r+   r,      s     [ [4 [r-   c                t    V P                   ;'       g!    V P                  ;'       g    V P                  '       * # )z5Determine if the session is usable for next requests.)r   r   r   rU   s   &r*   	is_usableSession.is_usable   s+     OOYYtYY$:Y:YZZr-   c                    V ^8  d   QhRRRR/# )r#   rP   zLiteral[True]r&   ri   r(   )r)   s   "r*   r+   r,      s    ??M?d?r-   c               	    R # Nr(   r>   rP   s   &$r*   rT   Session.get_state   s    <?r-   c                    V ^8  d   QhRRRR/# )r#   rP   zLiteral[False]r&   r   r(   )r)   s   "r*   r+   r,      s    HHNH|Hr-   c               	    R # r   r(   r   s   &$r*   rT   r      s    EHr-   rP   Fc                    V ^8  d   QhRRRR/# )r#   rP   r[   r&   zSessionModel | dictr(   )r)   s   "r*   r+   r,      s      D 5H r-   c               r   ^RI Hp V! V P                  V P                  V P                  V P
                  V P                  V P                  V P                  V P                  V P                  V P                  P                  4       \        V P                  4      R7      pV'       d   VP                  4       # V# )zORetrieve the current state of the session either as a model or as a dictionary.r   )r   r   r   r   r   r   r   r   r   r    r!   )_modelsr   r0   r1   r2   r3   r4   r7   r8   r9   r:   r;   get_cookies_as_dictsrc   r=   rE   )r>   rP   r   rB   s   &$  r*   rT   r      s    )xxMMoo 11"&"="='')) 11))MM668!%d&@&@!A
 ##%%r-   c                   V ^8  d   QhRR/# r#   r&   r'   r(   )r)   s   "r*   r+   r,      s     	 	4 	r-   c                    V ;P                   ^,          un         V P                  ^ 8  d-   \        ^ V P                  V P                  ,
          4      V n        V P                  '       g   V P                  4        R# R# )zLMark the session as good. Should be called after a successful session usage.N)r8   r:   maxr4   r   retirerU   s   &r*   	mark_goodSession.mark_good   sZ    Qq  #At'8'84;V;V'V WD ~~~KKM r-   c                   V ^8  d   QhRR/# r   r(   )r)   s   "r*   r+   r,      s      $ r-   c                    V ;P                   ^,          un         V ;P                  ^,          un        V P                  '       g   V P                  4        R# R# )z<Mark the session as bad after an unsuccessful session usage.N)r:   r8   r   r   rU   s   &r*   mark_badSession.mark_bad   s=    QQ ~~~KKM r-   c                   V ^8  d   QhRR/# r   r(   )r)   s   "r*   r+   r,      s     	 	 	r-   c                ~    V ;P                   V P                  ,          un         V ;P                  ^,          un        R# )a  Retire the session by setting the error score to the maximum value.

This method should be used if the session usage was unsuccessful and you are sure that it is because of
the session configuration and not any external matters. For example when server returns 403 status code.
If the session does not work due to some external factors as server error such as 5XX you probably want
to use `mark_bad` method.
N)r:   r3   r8   rU   s   &r*   r   Session.retire   s,     	T222Qr-   ignore_http_error_status_codesc               $    V ^8  d   QhRRRRRR/# )r#   status_coder%   r   zset[int] | Noner&   r[   r(   )r)   s   "r*   r+   r,      s/     g g g )8	g
 
gr-   c               P    YP                   T;'       g    \        4       ,
          9   # )ab  Evaluate whether a session should be retired based on the received HTTP status code.

Args:
    status_code: The HTTP status code received from a server response.
    ignore_http_error_status_codes: Optional status codes to allow suppression of
    codes from `blocked_status_codes`.

Returns:
    True if the session should be retired, False otherwise.
)r=   r<   )r>   r   r   s   &$$r*   is_blocked_status_codeSession.is_blocked_status_code   s%      99=[=d=d_b_deffr-   )r=   r;   r7   r:   r4   r0   r1   r3   r9   r8   r2   )i  i  i  ) rS   
__module____qualname____firstlineno____doc__r   __annotations__r   r?   classmethodrG   rV   r_   rn   propertyr   r   r    r   r   r   r   r   r   r   r   rT   r   r   r   r   __static_attributes__r(   r-   r*   r   r      s    />!8=B(e (e 'r2	(e
 "&(e "%(e (+(e '+(e (e  "(e !(e [_(e -1(eT M M
NM+,       ! ! ! ! 0 0 : : = = : : [ [ ? ?H H5 *		g ;?	g gr-   r   N)
__future__r   r   r   r   loggingr   typingr   r	   r
   r   crawlee._utils.cryptor   crawlee._utils.docsr   crawlee.sessions._cookiesr   r   http.cookiejarr   crawlee.sessions._modelsr   rS   loggerr   r(   r-   r*   <module>r      sZ    # 2 2  = = 9 * A(5	8	  !Yg Yg "Ygr-   