Class Session

src/crawlee/sessions/_session.py:24–239

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

@docs_group('Session management')
class Session:
    """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.
    """

    _DEFAULT_BLOCKED_STATUS_CODES: ClassVar = [401, 403, 429]
    """Default status codes that indicate a session is blocked."""

    def __init__(
        self,
        *,
        id: str | None = None,
        max_age: timedelta = timedelta(minutes=50),
        user_data: Mapping[str, JsonSerializable] | None = None,
        max_error_score: float = 3.0,
        error_score_decrement: float = 0.5,
        created_at: datetime | None = None,
        usage_count: int = 0,
        max_usage_count: int = 50,
        error_score: float = 0.0,
        cookies: SessionCookies | CookieJar | dict[str, str] | list[CookieParam] | None = None,
        blocked_status_codes: list | None = None,
    ) -> None:
        """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.
        """
        self._id = id or crypto_random_object_id(length=10)
        self._max_age = max_age
        self._user_data: MutableMapping[str, JsonSerializable] = dict(user_data) if user_data is not None else {}
        self._max_error_score = max_error_score
        self._error_score_decrement = error_score_decrement
        self._created_at = created_at or datetime.now(timezone.utc)
        self._usage_count = usage_count
        self._max_usage_count = max_usage_count
        self._error_score = error_score
        self._cookies = SessionCookies(cookies) or SessionCookies()
        self._blocked_status_codes = set(blocked_status_codes or self._DEFAULT_BLOCKED_STATUS_CODES)

    @classmethod
    def from_model(cls, model: SessionModel) -> Session:
        """Initialize a new instance from a `SessionModel`."""
        cookies = SessionCookies(model.cookies)