pywry.auth.flow¶

OAuth2 authentication flow orchestrator.

AuthFlowManager¶

pywry.auth.flow.AuthFlowManager ¶

AuthFlowManager(provider: OAuthProvider, token_store: TokenStore | None = None, session_manager: SessionManager | None = None, use_pkce: bool = True, auth_timeout: float = 120.0)

Orchestrates OAuth2 authentication flows.

Supports two modes:

Native mode: Opens a dedicated auth window pointing at the provider's authorize URL, captures the redirect on an ephemeral localhost HTTP server, and exchanges the code for tokens.
Deploy mode: Returns the /auth/login URL for the frontend to navigate to. The server-side routes handle the actual flow.

PARAMETER	DESCRIPTION
`provider`	The configured OAuth2 provider. TYPE: `OAuthProvider`
`token_store`	Store for persisting tokens after successful auth. TYPE: `TokenStore` DEFAULT: `None`
`session_manager`	Session manager for token lifecycle. TYPE: `SessionManager` DEFAULT: `None`
`use_pkce`	Whether to use PKCE (default `True`). TYPE: `bool` DEFAULT: `True`
`auth_timeout`	Seconds to wait for the auth callback (default `120`). TYPE: `float` DEFAULT: `120.0`

Initialize the auth flow manager.

Attributes¶

flow_state `property` ¶

flow_state: AuthFlowState

Current state of the auth flow.

Functions¶

run_native ¶

run_native(show_window: Any | None = None, close_window: Any | None = None, window_config: dict[str, Any] | None = None) -> AuthFlowResult

Run the OAuth2 flow in native window mode.

This method blocks until authentication completes, times out, or is cancelled.

PARAMETER	DESCRIPTION
`show_window`	Function to open the auth window. Signature: `show_window(url: str, config: dict) -> str` (returns label). If None, the URL is logged for manual navigation. TYPE: `callable` DEFAULT: `None`
`close_window`	Function to close the auth window. Signature: `close_window(label: str) -> None`. TYPE: `callable` DEFAULT: `None`
`window_config`	Additional window configuration (title, width, height). TYPE: `dict` DEFAULT: `None`

RETURNS	DESCRIPTION
`AuthFlowResult`	The result of the authentication flow.

RAISES	DESCRIPTION
`AuthFlowTimeout`	If the callback is not received within the timeout.
`AuthFlowCancelled`	If the user closes the auth window or aborts.
`AuthenticationError`	If the provider returns an error.

run_deploy ¶

run_deploy(base_url: str = '') -> str

Get the login URL for deploy mode.

In deploy mode, the actual OAuth2 flow is handled server-side by the routes in deploy_routes.py. This method simply returns the URL that the frontend should navigate to.

PARAMETER	DESCRIPTION
`base_url`	The base URL of the deploy server (e.g. `http://localhost:8080`). TYPE: `str` DEFAULT: `''`

RETURNS	DESCRIPTION
`str`	The `/auth/login` URL.

authenticate ¶

authenticate(app: Any, show_window: Any | None = None, close_window: Any | None = None, window_config: dict[str, Any] | None = None) -> AuthFlowResult

Unified authentication entry point.

Detects the app mode and runs the appropriate flow.

PARAMETER	DESCRIPTION
`app`	The PyWry application instance. TYPE: `PyWry`
`show_window`	Window opener for native mode. TYPE: `callable` DEFAULT: `None`
`close_window`	Window closer for native mode. TYPE: `callable` DEFAULT: `None`
`window_config`	Window configuration for native mode. TYPE: `dict` DEFAULT: `None`

RETURNS	DESCRIPTION
`AuthFlowResult`	The authentication result.

cancel ¶

cancel() -> None

Cancel the current authentication flow.

Sets the cancellation event which unblocks _wait_for_callback_with_cancellation.

AuthFlowResult¶

pywry.auth.flow.AuthFlowResult `dataclass` ¶

AuthFlowResult(success: bool, tokens: OAuthTokenSet | None = None, error: str | None = None, user_info: dict[str, Any] | None = None)

Result of an OAuth2 authentication flow.

ATTRIBUTE	DESCRIPTION
`success`	Whether authentication completed successfully. TYPE: `bool`
`tokens`	The token set if authentication succeeded. TYPE: `OAuthTokenSet or None`
`error`	Error message if authentication failed. TYPE: `str or None`
`user_info`	User profile information from the provider. TYPE: `dict[str, Any] or None`

AuthFlowState¶

pywry.auth.flow.AuthFlowState ¶

Bases: str, Enum

State of an OAuth2 authentication flow.