API reference

Build the httpx client, attach the cache transport, and wire up resource accessors.

Enter the context manager, opening the underlying HTTP connection.

Exit the context manager, closing the underlying HTTP connection.

Fetch a single publication by reference code via /searchPublication.

Initialise the token manager with optional settings, path, and storage overrides.

Start PKCE browser flow; blocks until redirect received or manual code entered.

Parameters:

Revoke tokens server-side (best-effort) then delete local storage.

Return the stored offline refresh token for transfer to another host.

Refuses online sessions, which would die with the SSO session. With move=True the local copy is deleted (without server-side revocation, so the exported token stays valid).

Keycloak rotates refresh tokens, so once the other host refreshes, any copy kept here may be rejected on its next refresh.

move=True is not transactional: the local copy is deleted before the caller delivers the returned token. If that delivery or the remote import fails, the session stays valid server-side but can no longer be revoked from this host (:meth:logout only revokes tokens still stored). A later login(offline=True) creates a separate session; it neither recovers nor revokes the orphaned one, which lapses only after the server's offline-session idle timeout.

Store a session from an offline refresh token exported elsewhere.

The token is redeemed immediately, so a bad or expired token fails here rather than on the first unattended run. A rejected token leaves any session already stored on this host untouched.

Return a valid access token, refreshing and exchanging as needed.

If settings.exchange_audience is set, the PKCE access token is exchanged for an audience-scoped token via RFC 8693. The exchanged token is cached in memory to avoid a round-trip on every API call.

Return the PKCE base access token (refreshing if needed).

Never performs a token exchange regardless of exchange_audience. Raises :exc:~stare.exceptions.AuthenticationError if not logged in.

Return the stored PKCE id token, or None if absent or not logged in.

Return the raw RFC 8693 exchanged access token.

Returns None if exchange_audience is not configured. Performs the exchange if the cached token is absent or nearly expired. Raises :exc:~stare.exceptions.AuthenticationError if not logged in.

Return True if a non-expired token is stored.

Return token metadata and decoded JWT claims, or None if not stored.

The JWT payload is decoded without signature verification — suitable only for display purposes, not security decisions.

Return whether the stored session is offline, or None if not stored.

Decoded from the refresh token without signature verification — suitable only for display purposes, not security decisions.

Decode and return info for the RFC 8693 exchanged token.

Returns None if exchange_audience is not configured. Performs the exchange if the cached token is absent or nearly expired. Raises :exc:~stare.exceptions.AuthenticationError if not logged in.

Return stored tokens, or None if absent.

Persist tokens to storage.

Delete stored tokens; no-op if absent.

Return True if tokens are currently stored.

Store the path where the token JSON file will be read and written.

Return stored tokens, or None if the file does not exist.

Write tokens to the JSON file, creating parent directories as needed.

Written atomically to a 0o600 temp file in the same directory, then renamed onto the target, so the file is never briefly world-readable or observable mid-write.

Delete the token file; no-op if it does not exist.

Return True if the token file exists.

Return stored tokens from the keyring, or None if absent.

Persist tokens as a JSON blob in the OS-native credential store.

Delete the keyring entry; no-op if it does not exist.

Return True if a token entry exists in the keyring.

One-time migration from plaintext file to keyring. Idempotent.

Return the effective cache directory, defaulting to the platform user-cache dir.

Store HTTP status code, title, and detail then delegate to Exception.

Store the raw API payload alongside the error message.

Serialize to DSL string.

Raises ValueError for values that cannot be represented in the grammar's STRING token (/"[^"\n\r\t\f\v]*"/): - embedded double-quotes are unsupported (escaped-quote support not yet implemented) - non-space whitespace (tabs, newlines, etc.) is excluded by the grammar

Wraps the value in double quotes when it is empty, contains spaces, parentheses, or square brackets, or is a DSL keyword/operator token (which would otherwise be reparsed as syntax); emits bare otherwise. Fields are always emitted bare after normalization.

Serialize to DSL string, parenthesizing Or operands.

Serialize to DSL string.

Return the operator value, not the enum repr.

Initialise with camelCase field names and an optional boolean subset.

Load the field catalogue for mode from the bundled TOML data file.

Convert each dot-separated segment from snake_case to camelCase.

Return sorted list of valid camelCase field names.

Raise DSLValidationError if the (normalized) field is not in the catalogue.

Raise DSLValidationError if an already-normalized field is not in the catalogue.

Raise DSLValidationError if operator is not valid for normalized field.

Boolean fields only accept = and !=; all other fields accept any operator.

Render as a Rich clickable hyperlink when a URL is present.

Return a Rich Panel summarising the analysis for terminal display.

Return a Rich Panel summarising the paper for terminal display.

Return a Rich Panel summarising the CONF note for terminal display.

Return a Rich Panel summarising the PUB note for terminal display.

Return a Rich Panel summarising the plot for terminal display.