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.

Parameters:

Name	Type	Description	Default
provider	OAuthProvider	The configured OAuth2 provider.	required
token_store	TokenStore	Store for persisting tokens after successful auth.	None
session_manager	SessionManager	Session manager for token lifecycle.	None
use_pkce	bool	Whether to use PKCE (default True).	True
auth_timeout	float	Seconds to wait for the auth callback (default 120).	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.

Parameters:

Name	Type	Description	Default
show_window	callable	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.	None
close_window	callable	Function to close the auth window. Signature: close_window(label: str) -> None.	None
window_config	dict	Additional window configuration (title, width, height).	None

Returns:

Type	Description
AuthFlowResult	The result of the authentication flow.

Raises:

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

Parameters:

Name	Type	Description	Default
base_url	str	The base URL of the deploy server (e.g. http://localhost:8080).	''

Returns:

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

Parameters:

Name	Type	Description	Default
app	PyWry	The PyWry application instance.	required
show_window	callable	Window opener for native mode.	None
close_window	callable	Window closer for native mode.	None
window_config	dict	Window configuration for native mode.	None

Returns:

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

Attributes:

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

---

AuthFlowState

pywry.auth.flow.AuthFlowState

Bases: str, Enum

State of an OAuth2 authentication flow.