Utilities#

Configuration, token persistence, and environment detection helpers.

class py_oidc_auth_client.utils.Config(host: str, redirect_ports: List[int] = <factory>, token_env_var: str = 'OIDC_TOKEN_FILE', app_name: str = 'py-oidc-auth', login_route: str = '/auth/v2/login', token_route: str = '/auth/v2/token', device_route: str = '/auth/v2/device')#

Bases: object

Connection and routing configuration for an OIDC enabled server.

Parameters:

host (str) – Base URL of the application server (e.g. "https://myapp.example.com").
redirect_ports (list of int, optional) – Ports to try when starting a local HTTP server for the authorization code callback. The first available port is used. Defaults to [53100, 53101, 53102, 53103, 53104, 53105].
token_env_var (str) – Name of the environment variable that points to a token file.
app_name (str) – Application name used to locate the platform specific cache directory for token storage (via platformdirs).
login_route (str) – Server side route for the authorization code login endpoint.
token_route (str) – Server side route for the token exchange endpoint.
device_route (str) – Server side route for the device authorization endpoint.

Examples

from py_oidc_auth_client.utils import Config

cfg = Config(
    host="https://myapp.example.com",
    app_name="my-project",
    login_route="/auth/v2/login",
    token_route="/auth/v2/token",
    device_route="/auth/v2/device",
)

app_name: str = 'py-oidc-auth'#

device_route: str = '/auth/v2/device'#

host: str#

login_route: str = '/auth/v2/login'#

redirect_ports: List[int]#

token_env_var: str = 'OIDC_TOKEN_FILE'#

token_route: str = '/auth/v2/token'#

py_oidc_auth_client.utils.build_url(base: str, *parts: str) → str#

Join a base URL with path segments.

>>> build_url("http://localhost:7777/api/freva-nextgen", "/token/foo")
'http://localhost:7777/api/freva-nextgen/token/foo'

>>> build_url("http://localhost:7777/api/freva-nextgen/", "token", "foo")
'http://localhost:7777/api/freva-nextgen/token/foo'

py_oidc_auth_client.utils.choose_token_strategy(token: Token | None = None) → Literal['use_token', 'refresh_token', 'interactive_auth', 'fail']#

Decide the best authentication action for the current state.

Parameters:

token (Token or None) – Previously cached token, or None if unavailable.

Returns:

One of:

"use_token": The access token is still valid.
"refresh_token": The access token expired but the refresh token is valid.
"interactive_auth": No usable tokens; a browser login should be attempted.
"fail": No usable tokens and no interactive session available.

Return type:

str

py_oidc_auth_client.utils.clock(timeout: int | None = None, interactive: bool | None = None) → Iterator[None]#

Show a rich spinner while waiting for user approval.

Parameters:

timeout (int or None) – Total seconds to wait. Shown in the spinner text.
interactive (bool or None) – Force interactive mode on or off. None auto detects.

py_oidc_auth_client.utils.is_interactive_auth_possible() → bool#

Decide if a browser based login flow can be attempted.

Returns True when the session is interactive (TTY or local Jupyter) and not running inside a batch scheduler.

Returns:: True if interactive authentication is feasible.
Return type:: bool

py_oidc_auth_client.utils.is_interactive_shell() → bool#

Check whether stdin and stdout are connected to a terminal.

Returns:: True if both stdin and stdout are TTYs.
Return type:: bool

py_oidc_auth_client.utils.is_job_env() → bool#

Detect whether the process runs inside a batch scheduler.

Checks for environment variables set by Slurm, PBS, SGE, LSF, OAR, MPI, Kubernetes, JupyterHub, and FREVA batch jobs.

Returns:: True if a batch environment is detected.
Return type:: bool

py_oidc_auth_client.utils.is_jupyter_notebook() → bool#

Check if the process runs inside a Jupyter kernel.

Returns:: True if an IPython kernel is active.
Return type:: bool

py_oidc_auth_client.utils.is_token_valid(token: Token | None, token_type: Literal['access_token', 'refresh_token']) → bool#

Check whether a token is present and not expired.

Applies a safety buffer of TOKEN_EXPIRY_BUFFER seconds (default 60) so that tokens close to expiry are treated as invalid.

Parameters:

token (Token or None) – Token dictionary to inspect.
token_type ("access_token" or "refresh_token") – Which token (and corresponding expiry field) to check.

Returns:

True if the token exists and will remain valid for at least TOKEN_EXPIRY_BUFFER more seconds.

Return type:

bool

py_oidc_auth_client.utils.pprint(text: str, **args: str | int) → None#: Pritty print a text to stderr.