jam.Jam

Jam ¶

Jam(
    config: Union[dict[str, Any], str] = "pyproject.toml",
    pointer: str = "jam",
)

Bases: BaseJam

Main instance.

Parameters:

Name	Type	Description	Default
`config`	`dict[str, Any] \| str`	dict or path to config file	`'pyproject.toml'`
`pointer`	`str`	Config read point	`'jam'`

Methods:

Name	Description
`clear_sessions`	Clear all sessions associated with a specific session key.
`create_session`	Create a new session.
`delete_session`	Delete a session by its ID.
`gen_jwt_token`	Creating a new token.
`get_otp_code`	Generates an OTP.
`get_otp_uri`	Generates an otpauth:// URI for Google Authenticator.
`get_session`	Retrieve session data by session ID.
`jwt_create_token`	Create JWT token.
`jwt_make_payload`	Make JWT-specific payload.
`jwt_verify_token`	Verify and decode JWT token.
`make_payload`	Payload maker tool.
`oauth2_client_credentials_flow`	Obtain access token using client credentials flow (no user interaction).
`oauth2_fetch_token`	Exchange authorization code for access token.
`oauth2_get_authorized_url`	Generate full OAuth2 authorization URL.
`oauth2_refresh_token`	Use refresh token to obtain a new access token.
`otp_code`	Generates an OTP.
`otp_uri`	Generates an otpauth:// URI for Google Authenticator.
`otp_verify_code`	Checks the OTP code, taking into account the acceptable window.
`rework_session`	Rework an existing session key to a new one.
`session_clear`	Delete all sessions by key.
`session_create`	Create new session.
`session_delete`	Delete session.
`session_get`	Get data from session.
`session_rework`	Rework session.
`session_update`	Update session data.
`update_session`	Update session data by session ID.
`verify_jwt_token`	A method for verifying a token.
`verify_otp_code`	Checks the OTP code, taking into account the acceptable window.

clear_sessions ¶

clear_sessions(session_key: str) -> None

Clear all sessions associated with a specific session key.

Parameters:

Name	Type	Description	Default
`session_key`	`str`	The session key whose sessions are to be cleared.	required

Deprecated

Use: Jam.session_clear

Raises:

Type	Description
`NotImplementedError`	If the auth type is not "session".

Returns:

Type	Description
`None`	None

create_session ¶

create_session(session_key: str, data: dict) -> str

Create a new session.

Parameters:

Name	Type	Description	Default
`session_key`	`str`	Session key	required
`data`	`dict`	Data to store in session	required

Deprecated

Use: Jam.session_create

Raises:

Type	Description
`NotImplementedError`	If the auth type is not "session"

Returns:

Name	Type	Description
`str`	`str`	The created session key

delete_session ¶

delete_session(session_id: str) -> None

Delete a session by its ID.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	The ID of the session to delete.	required

Deprecated

Use: Jam.session_delete

Raises:

Type	Description
`NotImplementedError`	If the auth type is not "session".

Returns:

Type	Description
`None`	None

gen_jwt_token ¶

gen_jwt_token(payload: dict[str, Any]) -> str

Creating a new token.

Parameters:

Name	Type	Description	Default
`payload`	`dict[str, Any]`	Payload with information	required

Deprecated

Use Jam.jwt_create_token

Raises:

Type	Description
`EmptySecretKey`	If the HMAC algorithm is selected, but the secret key is None
`EmtpyPrivateKey`	If RSA algorithm is selected, but private key None

get_otp_code ¶

get_otp_code(
    secret: Union[str, bytes], factor: Optional[int] = None
) -> str

Generates an OTP.

Parameters:

Name	Type	Description	Default
`secret`	`str \| bytes`	User secret key.	required
`factor`	`int \| None`	Unixtime for TOTP(if none, use now time) / Counter for HOTP.	`None`

Deprecated

Use: Jam.otp_code

Returns:

Name	Type	Description
`str`	`str`	OTP code (fixed-length string).

get_otp_uri ¶

get_otp_uri(
    secret: str,
    name: Optional[str] = None,
    issuer: Optional[str] = None,
    counter: Optional[int] = None,
) -> str

Generates an otpauth:// URI for Google Authenticator.

Parameters:

Name	Type	Description	Default
`secret`	`str`	User secret key.	required
`name`	`str`	Account name (e.g., email).	`None`
`issuer`	`str`	Service name (e.g., "GitHub").	`None`
`counter`	`int \| None`	Counter (for HOTP). Default is None.	`None`

Deprecated

Use: Jam.otp_uri

Returns:

Name	Type	Description
`str`	`str`	A string of the form "otpauth://..."

get_session ¶

get_session(session_id: str) -> Optional[dict]

Retrieve session data by session ID.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	The ID of the session to retrieve.	required

Raises:

Type	Description
`NotImplementedError`	If the auth type is not "session".

Deprecated

Use: Jam.session_get

Returns:

Type	Description
`Optional[dict]`	dict \| None: The session data if found, otherwise None.

jwt_create_token ¶

jwt_create_token(payload: dict[str, Any]) -> str

Create JWT token.

Parameters:

Name	Type	Description	Default
`payload`	`dict[str, Any]`	Data payload	required

Returns:

Name	Type	Description
`str`	`str`	New token

Raises:

Type	Description
`EmptySecretKey`	If the HMAC algorithm is selected, but the secret key is None
`EmtpyPrivateKey`	If RSA algorithm is selected, but private key None

jwt_make_payload ¶

jwt_make_payload(
    exp: Optional[int], data: dict[str, Any]
) -> dict[str, Any]

Make JWT-specific payload.

Parameters:

Name	Type	Description	Default
`exp`	`int \| None`	Token expire, if None -> use default	required
`data`	`dict[str, Any]`	Data to payload	required

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: Payload

jwt_verify_token ¶

jwt_verify_token(
    token: str,
    check_exp: bool = True,
    check_list: bool = True,
) -> dict[str, Any]

Verify and decode JWT token.

Parameters:

Name	Type	Description	Default
`token`	`str`	JWT token	required
`check_exp`	`bool`	Check expire	`True`
`check_list`	`bool`	Check white/black list. Docs: https://jam.makridenko.ru/jwt/lists/what/	`True`

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: Decoded payload

Raises:

Type	Description
`ValueError`	If the token is invalid.
`EmptySecretKey`	If the HMAC algorithm is selected, but the secret key is None.
`EmtpyPublicKey`	If RSA algorithm is selected, but public key None.
`NotFoundSomeInPayload`	If 'exp' not found in payload.
`TokenLifeTimeExpired`	If token has expired.
`TokenNotInWhiteList`	If the list type is white, but the token is not there
`TokenInBlackList`	If the list type is black and the token is there

make_payload ¶

make_payload(
    exp: Optional[int] = None, **data
) -> dict[str, Any]

Payload maker tool.

Parameters:

Name	Type	Description	Default
`exp`	`int \| None`	If none exp = JWTModule.exp	`None`
`**data`		Custom data	`{}`

Deprecated

Use Jam.jwt_make_payload

oauth2_client_credentials_flow ¶

oauth2_client_credentials_flow(
    provider: str,
    scope: Optional[list[str]] = None,
    **extra_params: Any
) -> dict[str, Any]

Obtain access token using client credentials flow (no user interaction).

Parameters:

Name	Type	Description	Default
`provider`	`str`	OAuth2 provider	required
`scope`	`list[str] \| None`	Auth scope	`None`
`extra_params`	`Any`	Extra auth params if needed	`{}`

Returns:

Name	Type	Description
`dict`	`dict[str, Any]`	JSON with access token

oauth2_fetch_token ¶

oauth2_fetch_token(
    provider: str,
    code: str,
    grant_type: str = "authorization_code",
    **extra_params: Any
) -> dict[str, Any]

Exchange authorization code for access token.

Parameters:

Name	Type	Description	Default
`provider`	`str`	Provider name	required
`code`	`str`	OAuth2 code	required
`grant_type`	`str`	Type of oauth2 grant	`'authorization_code'`
`extra_params`	`Any`	Extra auth params if needed	`{}`

Returns:

Name	Type	Description
`dict`	`dict[str, Any]`	OAuth2 token

oauth2_get_authorized_url ¶

oauth2_get_authorized_url(
    provider: str, scope: list[str], **extra_params: Any
) -> str

Generate full OAuth2 authorization URL.

Parameters:

Name	Type	Description	Default
`provider`	`str`	Provider name	required
`scope`	`list[str]`	Auth scope	required
`extra_params`	`Any`	Extra ath params	`{}`

Returns:

Name	Type	Description
`str`	`str`	Authorization url

oauth2_refresh_token ¶

oauth2_refresh_token(
    provider: str,
    refresh_token: str,
    grant_type: str = "refresh_token",
    **extra_params: Any
) -> dict[str, Any]

Use refresh token to obtain a new access token.

Parameters:

Name	Type	Description	Default
`provider`	`str`	Provider name	required
`refresh_token`	`str`	Refresh token	required
`grant_type`	`str`	Grant type	`'refresh_token'`
`extra_params`	`Any`	Extra auth params if needed	`{}`

Returns:

Name	Type	Description
`dict`	`dict[str, Any]`	Refresh token

otp_code ¶

otp_code(
    secret: Union[str, bytes], factor: Optional[int] = None
) -> str

Generates an OTP.

Parameters:

Name	Type	Description	Default
`secret`	`str \| bytes`	User secret key.	required
`factor`	`int \| None`	Unixtime for TOTP(if none, use now time) / Counter for HOTP.	`None`

Returns:

Name	Type	Description
`str`	`str`	OTP code (fixed-length string).

otp_uri ¶

otp_uri(
    secret: str,
    name: Optional[str] = None,
    issuer: Optional[str] = None,
    counter: Optional[int] = None,
) -> str

Generates an otpauth:// URI for Google Authenticator.

Parameters:

Name	Type	Description	Default
`secret`	`str`	User secret key.	required
`name`	`str`	Account name (e.g., email).	`None`
`issuer`	`str`	Service name (e.g., "GitHub").	`None`
`counter`	`int \| None`	Counter (for HOTP). Default is None.	`None`

Returns:

Name	Type	Description
`str`	`str`	A string of the form "otpauth://..."

otp_verify_code ¶

otp_verify_code(
    secret: Union[str, bytes],
    code: str,
    factor: Optional[int] = None,
    look_ahead: Optional[int] = 1,
) -> bool

Checks the OTP code, taking into account the acceptable window.

Parameters:

Name	Type	Description	Default
`secret`	`str \| bytes`	User secret key.	required
`code`	`str`	The code entered.	required
`factor`	`int \| None`	Unixtime for TOTP(if none, use now time) / Counter for HOTP.	`None`
`look_ahead`	`int`	Acceptable deviation in intervals (±window(totp) / ±look ahead(hotp)). Default is 1.	`1`

Returns:

Name	Type	Description
`bool`	`bool`	True if the code matches, otherwise False.

rework_session ¶

rework_session(old_session_key: str) -> str

Rework an existing session key to a new one.

Parameters:

Name	Type	Description	Default
`old_session_key`	`str`	The old session key to be reworked.	required

Deprecated

Use: Jam.session_rework

Raises:

Type	Description
`NotImplementedError`	If the auth type is not "session".

Returns:

Name	Type	Description
`str`	`str`	The new session key.

session_clear ¶

session_clear(session_key: str) -> None

Delete all sessions by key.

Parameters:

Name	Type	Description	Default
`session_key`	`str`	Key of session	required

session_create ¶

session_create(
    session_key: str, data: dict[str, Any]
) -> str

Create new session.

Parameters:

Name	Type	Description	Default
`session_key`	`str`	Key for session	required
`data`	`dict[str, Any]`	Session data	required

Returns:

Name	Type	Description
`str`	`str`	New session ID

session_delete ¶

session_delete(session_id: str) -> None

Delete session.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	Session ID	required

session_get ¶

session_get(session_id: str) -> Optional[dict[str, Any]]

Get data from session.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	Session ID	required

Returns:

Type	Description
`Optional[dict[str, Any]]`	dict[str, Any] \| None: Session data if exist

session_rework ¶

session_rework(old_session_id: str) -> str

Rework session.

Parameters:

Name	Type	Description	Default
`old_session_id`	`str`	Old session id	required

Returns:

Name	Type	Description
`str`	`str`	New session id

session_update ¶

session_update(
    session_id: str, data: dict[str, Any]
) -> None

Update session data.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	Session ID	required
`data`	`dict[str, Any]`	New data	required

update_session ¶

update_session(session_id: str, data: dict) -> None

Update session data by session ID.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	The ID of the session to update.	required
`data`	`dict`	The new data to update the session with.	required

Deprecated

Use: Jam.session_update

Raises:

Type	Description
`NotImplementedError`	If the auth type is not "session".

Returns:

Type	Description
`None`	None

verify_jwt_token ¶

verify_jwt_token(
    token: str,
    check_exp: bool = True,
    check_list: bool = True,
) -> dict[str, Any]

A method for verifying a token.

Parameters:

Name	Type	Description	Default
`token`	`str`	The token to check	required
`check_exp`	`bool`	Check for expiration?	`True`
`check_list`	`bool`	Check if there is a black/white list	`True`

Deprecated

Use Jam.jwt_verify_token

Raises:

Type	Description
`ValueError`	If the token is invalid.
`EmptySecretKey`	If the HMAC algorithm is selected, but the secret key is None.
`EmtpyPublicKey`	If RSA algorithm is selected, but public key None.
`NotFoundSomeInPayload`	If 'exp' not found in payload.
`TokenLifeTimeExpired`	If token has expired.
`TokenNotInWhiteList`	If the list type is white, but the token is not there
`TokenInBlackList`	If the list type is black and the token is there

Returns:

Type	Description
`dict[str, Any]`	Payload from token

verify_otp_code ¶

verify_otp_code(
    secret: Union[str, bytes],
    code: str,
    factor: Optional[int] = None,
    look_ahead: Optional[int] = 1,
) -> bool

Checks the OTP code, taking into account the acceptable window.

Parameters:

Name	Type	Description	Default
`secret`	`str \| bytes`	User secret key.	required
`code`	`str`	The code entered.	required
`factor`	`int \| None`	Unixtime for TOTP(if none, use now time) / Counter for HOTP.	`None`
`look_ahead`	`int`	Acceptable deviation in intervals (±window(totp) / ±look ahead(hotp)). Default is 1.	`1`

Deprecated

Use: Jam.otp_verify_code

Returns:

Name	Type	Description
`bool`	`bool`	True if the code matches, otherwise False.