API reference
Client
Top-level client for the ATLAS Glance/Fence API.
__init__(*, settings: StareSettings | None = None, token_manager: TokenManager | None = None, token: str | None = None) -> None
Build the httpx client, attach the cache transport, and wire up resource accessors.
Resource accessors
Accessor for /analyses/ and /searchAnalysis endpoints.
get(ref_code: str, *, verbose: bool = False) -> Analysis
Fetch a single analysis by reference code via /searchAnalysis.
search(*, query: str | Expression | None = None, offset: int = 0, limit: int = 50, sort_by: str | None = None, sort_desc: bool = False, validate_query: bool = True, verbose: bool = False) -> AnalysisSearchResult
Search analyses via GET /searchAnalysis.
Accessor for /papers/ and /searchPaper endpoints.
get(ref_code: str, *, verbose: bool = False) -> Paper
Fetch a single paper by reference code via /searchPaper.
search(*, query: str | Expression | None = None, offset: int = 0, limit: int = 50, sort_by: str | None = None, sort_desc: bool = False, validate_query: bool = True, verbose: bool = False) -> PaperSearchResult
Search papers via GET /searchPaper.
Accessor for /confnotes/ endpoint.
get(ref_code: str, *, verbose: bool = False) -> ConfNote
Fetch a single CONF note by temporary reference code via /searchConfnote.
search(*, query: str | Expression | None = None, offset: int = 0, limit: int = 50, sort_by: str | None = None, sort_desc: bool = False, validate_query: bool = True, verbose: bool = False) -> ConfNoteSearchResult
Search conf notes via GET /searchConfnote.
Accessor for /searchPubnote endpoint.
get(ref_code: str, *, verbose: bool = False) -> PubNote
Fetch a single PUB note by temporary reference code via /searchPubnote.
search(*, query: str | Expression | None = None, offset: int = 0, limit: int = 50, sort_by: str | None = None, sort_desc: bool = False, validate_query: bool = True, verbose: bool = False) -> PubNoteSearchResult
Search pub notes via GET /searchPubnote.
Accessor for the /searchPublication endpoint.
get(ref_code: str, *, verbose: bool = False) -> PublicationSummary
Fetch a single publication by reference code via /searchPublication.
search(*, query: str | Expression | None = None, offset: int = 0, limit: int = 50, sort_by: str | None = None, sort_desc: bool = False, validate_query: bool = True, verbose: bool = False) -> PublicationSearchResult
Search across all publication types via GET /searchPublication.
Accessor for /searchLeadgroup endpoint.
search(*, query: str | Expression | None = None, offset: int = 0, limit: int = 50, sort_by: str | None = None, sort_desc: bool = False, validate_query: bool = True, verbose: bool = False) -> LeadgroupSearchResult
Search leading groups via GET /searchLeadgroup.
Accessor for /searchSubgroup endpoint.
search(*, query: str | Expression | None = None, offset: int = 0, limit: int = 50, sort_by: str | None = None, sort_desc: bool = False, validate_query: bool = True, verbose: bool = False) -> SubgroupSearchResult
Search subgroups via GET /searchSubgroup.
Accessor for /searchTrigger endpoint.
search(*, query: str | Expression | None = None, offset: int = 0, limit: int = 50, sort_by: str | None = None, sort_desc: bool = False, validate_query: bool = True, verbose: bool = False) -> TriggerSearchResult
Search triggers via GET /searchTrigger.
Authentication
Manages OAuth2 tokens: PKCE login flow, storage, and refresh.
__init__(settings: StareSettings | None = None, token_path: Path | None = None, storage: TokenStorage | None = None) -> None
Initialise the token manager with optional settings, path, and storage overrides.
login(*, on_url_ready: Callable[[str], None] | None = None, get_manual_code: Callable[[], str | None] | None = None) -> None
Start PKCE browser flow; blocks until redirect received or manual code entered.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
on_url_ready
|
Callable[[str], None] | None
|
Called with the authorization URL before the browser is opened — use this to display the URL to the user. |
None
|
get_manual_code
|
Callable[[], str | None] | None
|
Called in a background thread to obtain a fallback authorization code (e.g. via user input) when the browser redirect cannot reach the local callback server. |
None
|
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 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.
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.
Bases: ABC
Abstract base class for token storage backends.
Bases: TokenStorage
Stores tokens as a JSON file on disk.
property
Return the path to the advisory lock file for this storage backend.
Store the path where the token JSON file will be read and written.
Write tokens to the JSON file, creating parent directories as needed.
Bases: TokenStorage
Stores tokens as a JSON blob in the OS-native credential store.
Uses macOS Keychain, Linux Secret Service, or Windows Credential Locker
depending on the platform. The entire :class:_StoredToken is persisted
as a single JSON string to avoid partial-write races.
property
Return the path to the advisory lock file for this storage backend.
Persist tokens as a JSON blob in the OS-native credential store.
Settings
Exceptions
Bases: Exception
Base exception for all stare errors.
Bases: StareError
Authentication failed or no credentials available.
Bases: AuthenticationError
Stored token is expired; re-run stare login.
Bases: StareError
An error response from the Glance API.
Bases: StareError
Raised when an API response cannot be parsed into the expected model.
Attributes:
| Name | Type | Description |
|---|---|---|
raw_data |
The raw object that failed validation (typically the parsed JSON dict/list), attached so callers can display it alongside the error message. |
DSL
The query DSL is available for programmatic use. See Query DSL for the syntax reference.
Parse a DSL query string and return a validated AST.
Raises DSLSyntaxError on grammar violations and DSLValidationError on unknown fields. Normalizes field names to camelCase.
Bases: BaseModel
A single field OP value predicate.
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 or contains spaces, parentheses, or square brackets; emits bare otherwise. Fields are always emitted bare after normalization.
Catalogue of valid DSL field names for a given query mode.
Initialise with camelCase field names and an optional boolean subset.
classmethod
for_mode(mode: Mode) -> FieldRegistry
Load the field catalogue for mode from the bundled TOML data file.
Convert each dot-separated segment from snake_case to camelCase.
Raise DSLValidationError if the (normalized) field is not in the catalogue.
Raise DSLValidationError if an already-normalized field is not in the catalogue.
validate_operator(normalized: str, operator: Operator) -> None
Raise DSLValidationError if operator is not valid for normalized field.
Boolean fields only accept = and !=; all other fields accept any operator.
Bases: Exception
Base class for all DSL errors.
Bases: DSLError
Raised when the input cannot be parsed by the grammar.
Bases: DSLError
Raised when a field name or operator fails semantic validation.
Enums
All enums are also available in a lenient form via the Lenient* type aliases
(e.g. LenientAnalysisStatus). Lenient aliases accept unknown strings
gracefully — logging a warning and storing the raw value rather than raising a
validation error.
Bases: StrEnum
Auto-generated enum.
Bases: StrEnum
Auto-generated enum.
Bases: StrEnum
Auto-generated enum.
Bases: StrEnum
Auto-generated enum.
Bases: StrEnum
Auto-generated enum.
Bases: StrEnum
Auto-generated enum.
Bases: StrEnum
Auto-generated enum.
Bases: StrEnum
Auto-generated enum.
Bases: StrEnum
Observed collision type identifiers.
Bases: StrEnum
Observed repository type values.
Bases: StrEnum
Observed publication type values (cross-references between record types).
Bases: StrEnum
Phase0 meeting role tags (used internally after flattening the 4 meeting lists).
URLs
URL builders for the ATLAS Glance web UI. Used internally to generate clickable hyperlinks in CLI output; also available for library callers.
Return the Glance web UI URL for an analysis.
Return the Glance web UI URL for a paper.
Return the Glance web UI URL for a CONF note.
Return the Glance web UI URL for a PUB note.
Models
Shared
Bases: _Base
A recorded meeting (EOI, editorial board request, pre-approval, approval, etc.).
The API sends a flat linkLabel / link pair; we fold them into a
single nested Link object on ingestion.
Analysis
Papers and notes
Publications
Bases: _Base
A summary record returned by GET /searchPublication.
Leading groups, subgroups, and triggers
Bases: _Base
A leading physics group returned by GET /searchLeadgroup.
Bases: _Base
A physics subgroup returned by GET /searchSubgroup.
Bases: _Base
A trigger entry returned by GET /searchTrigger.