scholar_flux.sessions.models package

Submodules

scholar_flux.sessions.models.session module

The scholar_flux.session.models.session module defines basic models used for CachedSessionManager configuration.

This module defines the BaseSessionManager which specifies the methods to be implemented by the SessionManager and CachedSessionManager subclasses while the CachedSessionConfig uses pydantic-based configuration models to validate the creation of CachedSessionManager instances.

Classes:

BaseSessionManager:

Defines the core, abstract methods necessary to create a new session object from session manager subclasses.

CachedSessionConfig:

Defines the underlying logic necessary to validate the configuration used when creating CachedSession objects using a CachedSessionManager.

class scholar_flux.sessions.models.session.BaseSessionManager(*args: Any, **kwargs: Any)

Bases: ABC

An abstract base class used as a factory to create session objects.

This base class can be extended to validate inputs to sessions and abstract the complexity of their creation

__init__(*args: Any, **kwargs: Any) → None

Initializes BaseSessionManager subclasses given the provided arguments.

abstract configure_session(*args: Any, **kwargs: Any) → Session | CachedSession

Configure the session.

Should be overridden by subclasses.

classmethod get_cache_directory(*args: Any, **kwargs: Any) → Path | None

Defines defaults used in the creation of subclasses.

Can be optionally overridden in the creation of cached session managers

classmethod with_session(*args: Any, **kwargs: Any) → Session | CachedSession

Convenience factory method for creating and configuring a new session instance.

Note: This method is designed to first instantiate the current SessionManager class using the provided positional or keyword arguments. Subclasses can define the exact parameters and type annotations required for instantiation if needed.

Parameters:

• *args – Positional arguments to pass to the __init__ method of the current class

• **kwargs – Keyword arguments to pass to the __init__ method of the current class

Returns:

A new session created by calling configure_session on the current session manager instance.

Return type:

requests.Session | CachedSession

class scholar_flux.sessions.models.session.CachedSessionConfig(*, cache_name: str, backend: SessionCacheBackendType, cache_directory: ~pathlib._local.Path | None = None, serializer: SessionCacheSerializer | None = None, expire_after: int | float | str | ~datetime.datetime | ~datetime.timedelta | None = None, user_agent: str | None = None, kwargs: dict[str, ~typing.Any] = <factory>)

Bases: BaseModel

A helper model used to validate the inputs provided when creating a CachedSessionManager.

This config is used to validate the inputs to the session manager prior to attempting its creation.

backend: SessionCacheBackendType

cache_directory: Path | None

cache_name: str

property cache_path: str

Helper method for retrieving the path that the cache will be written to or named, depending on the backend.

Assumes that the cache_name is provided to the config is not None.

expire_after: int | float | str | datetime.datetime | datetime.timedelta | None

kwargs: dict[str, Any]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

serializer: SessionCacheSerializer | None

user_agent: str | None

classmethod validate_backend_dependency(v: str | SessionCacheBackendType) → SessionCacheBackendType

Validates the choice of backend to and raises an error if its dependency is missing.

If the backend has unmet dependencies, this validator will trigger a ValidationError.

Parameters:

v (str | Optional[Literal["dynamodb", "filesystem", "gridfs", "memory", "mongodb", "redis", "sqlite"] | requests_cache.BaseCache])) – A valid backend for requests_cache (not case sensitive)

Returns:

A BaseCache or name of a backend supported by requests-cache

Return type:

Optional[Literal[“dynamodb”, “filesystem”, “gridfs”, “memory”, “mongodb”, “redis”, “sqlite”] | requests_cache.BaseCache])

validate_backend_filepath() → Self

Helper method for validating when file storage is a necessity vs when it’s not required.

classmethod validate_cache_directory(v: Path | str | None) → Path | None

Validates the cache_directory field to flag simple cases where the value is an empty string.

classmethod validate_cache_name(v: str) → str

Validates the cache_name field to flag simple cases where the value is an empty string.

classmethod validate_expire_after(v: int | float | str | datetime | timedelta | None) → int | float | datetime | timedelta | None

Validates the expire_after field to flag simple cases where numeric values below 0 are marked as invalid.

class scholar_flux.sessions.models.session.SessionCacheBackend(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Known session cache backends compatible with requests-cache.

DYNAMODB = 'dynamodb'

FILESYSTEM = 'filesystem'

GRIDFS = 'gridfs'

MEMORY = 'memory'

MONGODB = 'mongodb'

REDIS = 'redis'

SQLITE = 'sqlite'

classmethod get(backend: str | SessionCacheBackend) → SessionCacheBackend | None

Helper method for retrieving a known, valid requests-cache backend.

Module contents

The scholar_flux.sessions.models module contains classes that form the basis for the creation and validation of sessions and the parameters used to create them.

This module also contains the underlying config that is necessary for the creation and validation of the CachedSessionManager class.

Classes:

• The BaseSessionManager serves as a template for subclassing and orchestrating the creation of sessions

• The CachedSessionConfig class is based on Pydantic and supports the validation of input parameters.

• The SessionCacheBackend enum gives a static depiction of all available backends supported by requests-cache.

Usage:

Neither classes are currently intended to be client facing. Instead, they support the creation and use of existing Session Managers behind the scenes.

For example, the BaseSessionManager is subclassed into the SessionManager to create user-facing session managers:

>>> from scholar_flux.sessions import SessionManager
### Implementations validate parameters on instantiation and/or fill in missing details with defaults
>>> session_manager = SessionManager("my_scholar_flux_session") # Enforces the creation of a user agent
### The session_manager creates a session object for direct use in APIs
>>> session = session_manager() # In this case, the manager creates a standard requests.Session

class scholar_flux.sessions.models.BaseSessionManager(*args: Any, **kwargs: Any)

Bases: ABC

An abstract base class used as a factory to create session objects.

This base class can be extended to validate inputs to sessions and abstract the complexity of their creation

__init__(*args: Any, **kwargs: Any) → None

Initializes BaseSessionManager subclasses given the provided arguments.

abstract configure_session(*args: Any, **kwargs: Any) → Session | CachedSession

Configure the session.

Should be overridden by subclasses.

classmethod get_cache_directory(*args: Any, **kwargs: Any) → Path | None

Defines defaults used in the creation of subclasses.

Can be optionally overridden in the creation of cached session managers

classmethod with_session(*args: Any, **kwargs: Any) → Session | CachedSession

Convenience factory method for creating and configuring a new session instance.

Note: This method is designed to first instantiate the current SessionManager class using the provided positional or keyword arguments. Subclasses can define the exact parameters and type annotations required for instantiation if needed.

Parameters:

• *args – Positional arguments to pass to the __init__ method of the current class

• **kwargs – Keyword arguments to pass to the __init__ method of the current class

Returns:

A new session created by calling configure_session on the current session manager instance.

Return type:

requests.Session | CachedSession

class scholar_flux.sessions.models.CachedSessionConfig(*, cache_name: str, backend: SessionCacheBackendType, cache_directory: ~pathlib._local.Path | None = None, serializer: SessionCacheSerializer | None = None, expire_after: int | float | str | ~datetime.datetime | ~datetime.timedelta | None = None, user_agent: str | None = None, kwargs: dict[str, ~typing.Any] = <factory>)

Bases: BaseModel

A helper model used to validate the inputs provided when creating a CachedSessionManager.

This config is used to validate the inputs to the session manager prior to attempting its creation.

backend: SessionCacheBackendType

cache_directory: Path | None

cache_name: str

property cache_path: str

Helper method for retrieving the path that the cache will be written to or named, depending on the backend.

Assumes that the cache_name is provided to the config is not None.

expire_after: int | float | str | datetime.datetime | datetime.timedelta | None

kwargs: dict[str, Any]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

serializer: SessionCacheSerializer | None

user_agent: str | None

classmethod validate_backend_dependency(v: str | SessionCacheBackendType) → SessionCacheBackendType

Validates the choice of backend to and raises an error if its dependency is missing.

If the backend has unmet dependencies, this validator will trigger a ValidationError.

Parameters:

v (str | Optional[Literal["dynamodb", "filesystem", "gridfs", "memory", "mongodb", "redis", "sqlite"] | requests_cache.BaseCache])) – A valid backend for requests_cache (not case sensitive)

Returns:

A BaseCache or name of a backend supported by requests-cache

Return type:

Optional[Literal[“dynamodb”, “filesystem”, “gridfs”, “memory”, “mongodb”, “redis”, “sqlite”] | requests_cache.BaseCache])

validate_backend_filepath() → Self

Helper method for validating when file storage is a necessity vs when it’s not required.

classmethod validate_cache_directory(v: Path | str | None) → Path | None

Validates the cache_directory field to flag simple cases where the value is an empty string.

classmethod validate_cache_name(v: str) → str

Validates the cache_name field to flag simple cases where the value is an empty string.

classmethod validate_expire_after(v: int | float | str | datetime | timedelta | None) → int | float | datetime | timedelta | None

Validates the expire_after field to flag simple cases where numeric values below 0 are marked as invalid.

class scholar_flux.sessions.models.SessionCacheBackend(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Known session cache backends compatible with requests-cache.

DYNAMODB = 'dynamodb'

FILESYSTEM = 'filesystem'

GRIDFS = 'gridfs'

MEMORY = 'memory'

MONGODB = 'mongodb'

REDIS = 'redis'

SQLITE = 'sqlite'

classmethod get(backend: str | SessionCacheBackend) → SessionCacheBackend | None

Helper method for retrieving a known, valid requests-cache backend.