Skip to main content

Session

Session object represents a single user session.

Sessions are used to store information such as cookies and can be used for generating fingerprints and proxy sessions. You can imagine each session as a specific user, with its own cookies, IP (via proxy) and potentially a unique browser fingerprint. Session internal state can be enriched with custom user data for example some authorization tokens and specific headers in general.

Index

Errors

Methods

Properties

Errors

error_score

error_score: float

Get the current error score.

Methods

__eq__

  • __eq__(*, other): bool

  • Compare two sessions for equality.

    Parameters

    • optionalkeyword-onlyother: object

    Returns bool

__init__

  • __init__(*, id, max_age, user_data, max_error_score, error_score_decrement, created_at, usage_count, max_usage_count, error_score, cookies, blocked_status_codes): None

  • A default constructor.

    Parameters

    • optionalkeyword-onlyid: str | None = None

      Unique identifier for the session, autogenerated if not provided.

    • optionalkeyword-onlymax_age: timedelta = timedelta(minutes=50)

      Time duration after which the session expires.

    • optionalkeyword-onlyuser_data: dict | None = None

      Custom user data associated with the session.

    • optionalkeyword-onlymax_error_score: float = 3.0

      Threshold score beyond which the session is considered blocked.

    • optionalkeyword-onlyerror_score_decrement: float = 0.5

      Value by which the error score is decremented on successful operations.

    • optionalkeyword-onlycreated_at: datetime | None = None

      Timestamp when the session was created, defaults to current UTC time if not provided.

    • optionalkeyword-onlyusage_count: int = 0

      Number of times the session has been used.

    • optionalkeyword-onlymax_usage_count: int = 50

      Maximum allowable uses of the session before it is considered expired.

    • optionalkeyword-onlyerror_score: float = 0.0

      Current error score of the session.

    • optionalkeyword-onlycookies: dict | None = None

      Cookies associated with the session.

    • optionalkeyword-onlyblocked_status_codes: list | None = None

      HTTP status codes that indicate a session should be blocked.

    Returns None

__repr__

  • __repr__(): str

  • Get a string representation.

    Returns str

from_model

  • Create a new instance from a SessionModel.

    Parameters

    Returns Session

get_state

  • get_state(*, as_dict): dict

  • Parameters

    • optionalkeyword-onlyas_dict: Literal[true]

    Returns dict

get_state

  • Parameters

    • optionalkeyword-onlyas_dict: Literal[false]

    Returns SessionModel

get_state

  • Retrieve the current state of the session either as a model or as a dictionary.

    Parameters

    • optionalkeyword-onlyas_dict: bool = False

    Returns SessionModel | dict

is_blocked_status_code

  • is_blocked_status_code(*, status_code, additional_blocked_status_codes): bool

  • Evaluate whether a session should be retired based on the received HTTP status code.

    Parameters

    • optionalkeyword-onlystatus_code: int

      The HTTP status code received from a server response.

    • optionalkeyword-onlyadditional_blocked_status_codes: list[int] | None = None

      Optional additional status codes that should trigger session retirement.

    Returns bool

mark_bad

  • mark_bad(): None

  • Mark the session as bad after an unsuccessful session usage.

    Returns None

mark_good

  • mark_good(): None

  • Mark the session as good. Should be called after a successful session usage.

    Returns None

retire

  • retire(): None

  • 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.

    Returns None

Properties

cookies

cookies: dict

Get the cookies.

expires_at

expires_at: datetime

Get the expiration datetime of the session.

id

id: str

Get the session ID.

is_blocked

is_blocked: bool

Indicate whether the session is blocked based on the error score..

is_expired

is_expired: bool

Indicate whether the session is expired based on the current time.

is_max_usage_count_reached

is_max_usage_count_reached: bool

Indicate whether the session has reached its maximum usage limit.

is_usable

is_usable: bool

Determine if the session is usable for next requests.

usage_count

usage_count: float

Get the current usage count.

user_data

user_data: dict

Get the user data.

Page Options