.Stat Connector

Overview

The StatConnector retrieves structural metadata (dataflows, data structures, codelists, concept schemes and more) and data (as Pandas datasets) from SDMX .Stat Suite services such as the OECD dotStatSuite.

This connector is experimental and subject to change without prior notice. It is not covered by semantic versioning guarantees. Use it with caution in production environments or critical processes.

API Reference

class pysdmx.api.stat.StatConnector(api_endpoint=StatEndpoints.OECD, pem=None, timeout=20.0, token=None)

Read connector for .Stat Suite SDMX-REST v2 services.

Inherits RegistryClient, so its get_* methods return the same model objects – but it reads .Stat’s SDMX-ML 2.1 and parses it with read_sdmx() (the FMR client’s JSON deserializers do not apply). Structure types or endpoints .Stat does not serve raise Invalid.

Adds the SDMX data-discovery-and-retrieval profile (BasicConnector) that the FMR client does not offer – dataflows(), dataflow() and data() – with the same signatures as the generic SdmxConnector. Reads are anonymous unless a bearer token is supplied.

Obtain the agency, id and version of a dataflow from the OECD Data Explorer (https://data-explorer.oecd.org) via its “Developer API” button.

Warning: This class is experimental and subject to change without prior notice. It is not covered by semantic versioning guarantees, and modifications to this class will not result in a major version increment. Use it with caution in production environments or critical processes.

data(dataflow, filters=None)

Get data for a dataflow (SDMX data-discovery profile).

Implements the data method of the SDMX “data discovery and retrieval” profile (BasicConnector), yielding the observations as dictionaries.

Parameters:
  • dataflow (Union[str, MaintainableIdentification]) – The dataflow to query – a short or full URN, or any object implementing MaintainableIdentification (e.g. a Dataflow or DataflowRef).

  • filters (Union[BooleanFilter, DateTimeFilter, MultiFilter, NumberFilter, TextFilter, str, None]) – The query filters, if any – a SQL-like string ("FREQ='A' AND REF_AREA='UY'"), a Python expression, or a pysdmx.api.dc.query filter.

Yields:

One dict per observation (the SDMX-CSV rows).

dataflow(dataflow, filters=None)

Get a dataflow and its structure (SDMX data-discovery profile).

Implements the dataflow method of the SDMX “data discovery and retrieval” profile (BasicConnector), returning the dataflow together with its data structure.

Parameters:
  • dataflow (Union[str, MaintainableIdentification]) – The dataflow – a short or full URN, the agency:id(version) shorthand, or any object implementing MaintainableIdentification (e.g. a Dataflow or DataflowRef).

  • filters (Union[BooleanFilter, DateTimeFilter, MultiFilter, NumberFilter, TextFilter, str, None]) – Not supported on .Stat. .Stat does not serve the SDMX-JSON availability the profile relies on (it returns HTTP 500, while SDMX-ML returns a raw content constraint), so passing filters raises Invalid; use data() to query filtered data.

Return type:

Dataflow

Returns:

The dataflow with its data structure.

dataflows(search_term=None)

List available dataflows (SDMX data-discovery profile).

Implements the dataflows method of the SDMX “data discovery and retrieval” profile (BasicConnector). The dataflows are retrieved as complete stubs (detail=allcompletestubs), as prescribed by the profile’s Structure Catalogue step.

Parameters:

search_term (Optional[str]) – If set, only dataflows whose id, name or description contains the term (case-insensitive) are returned.

Return type:

tuple[Dataflow, ...]

Returns:

The matching dataflows, sorted by agency, id and version.

get_agencies(agency)

Get the sub-agencies for the supplied agency.

Return type:

Sequence[Agency]

get_categories(agency, id, version='~')

Get the category scheme matching the parameters.

Return type:

CategoryScheme

get_categorisation(agency, id, version='~')

Get the categorisation matching the parameters.

Return type:

Categorisation

get_code_map(agency, id, version='~')

Get the representation map matching the parameters.

Return type:

Union[MultiRepresentationMap, RepresentationMap]

get_codes(agency, id, version='~')

Get the codelist matching the parameters.

Return type:

Codelist

get_concepts(agency, id, version='~')

Get the concept scheme matching the parameters.

Return type:

ConceptScheme

get_data_structures(agency='*', id='*', version='~')

Get the data structure(s) matching the parameters.

Return type:

Sequence[DataStructureDefinition]

get_dataflow_details(agency, id, version='~', detail=DataflowDetails.ALL)

Not served by .Stat.

Return type:

DataflowInfo

get_dataflows(agency='*', id='*', version='~')

Get the dataflow(s) matching the parameters.

Return type:

Sequence[Dataflow]

get_hierarchy(agency, id, version='~')

Get the hierarchy matching the parameters.

Return type:

Hierarchy

get_mapping(agency, id, version='~')

Get the structure map matching the parameters.

Return type:

StructureMap

get_metadata_providers(agency, with_flows=False)

Get the metadata providers for the supplied agency.

Return type:

Sequence[DataProvider]

get_metadata_provision_agreement(agency, id, version='~')

Get the metadata provision agreement matching the parameters.

Return type:

MetadataProvisionAgreement

get_metadata_structures(agency='*', id='*', version='~')

Get the metadata structure(s) matching the parameters.

Return type:

Sequence[MetadataStructure]

get_metadataflows(agency='*', id='*', version='~')

Get the metadataflow(s) matching the parameters.

Return type:

Sequence[Metadataflow]

get_providers(agency, with_flows=False)

Get the data providers for the supplied agency.

Return type:

Sequence[DataProvider]

get_provision_agreement(agency, id, version='~')

Get the provision agreement matching the parameters.

Return type:

ProvisionAgreement

get_report(provider, id, version='~')

Not served by .Stat.

Return type:

MetadataReport

get_reports(artefact_type, agency, id, version='~')

Not served by .Stat.

Return type:

Sequence[MetadataReport]

get_schema(context, agency, id, version)

Not served by .Stat (no SDMX-REST /schema endpoint).

Return type:

Schema

get_vtl_transformation_scheme(agency, id, version='~')

Get the VTL transformation scheme matching the parameters.

Return type:

TransformationScheme

class pysdmx.api.stat.AsyncStatConnector(api_endpoint=StatEndpoints.OECD, pem=None, timeout=20.0, token=None)

Asynchronous read connector for .Stat Suite SDMX-REST v2 services.

The async counterpart of StatConnector: inherits AsyncRegistryClient, reads .Stat’s SDMX-ML 2.1 and parses it with read_sdmx(), and raises Invalid for endpoints .Stat does not serve. Adds the async data-discovery-and-retrieval profile: dataflows(), dataflow() and data(). Reads are anonymous unless a bearer token is supplied.

Warning: This class is experimental and subject to change without prior notice. It is not covered by semantic versioning guarantees, and modifications to this class will not result in a major version increment. Use it with caution in production environments or critical processes.

async data(dataflow, filters=None)

Get data for a dataflow (SDMX data-discovery profile).

Async counterpart of StatConnector.data(), yielding the observations as dictionaries.

Parameters:
Yields:

One dict per observation (the SDMX-CSV rows).

async dataflow(dataflow, filters=None)

Get a dataflow and its structure (SDMX data-discovery profile).

Async counterpart of StatConnector.dataflow().

Parameters:
Return type:

Dataflow

Returns:

The dataflow with its data structure.

async dataflows(search_term=None)

List available dataflows (SDMX data-discovery profile).

Async counterpart of StatConnector.dataflows().

Parameters:

search_term (Optional[str]) – If set, only dataflows whose id, name or description contains the term (case-insensitive) are returned.

Return type:

tuple[Dataflow, ...]

Returns:

The matching dataflows, sorted by agency, id and version.

async get_agencies(agency)

Get the sub-agencies for the supplied agency.

Return type:

Sequence[Agency]

async get_categories(agency, id, version='~')

Get the category scheme matching the parameters.

Return type:

CategoryScheme

async get_categorisation(agency, id, version='~')

Get the categorisation matching the parameters.

Return type:

Categorisation

async get_code_map(agency, id, version='~')

Get the representation map matching the parameters.

Return type:

Union[MultiRepresentationMap, RepresentationMap]

async get_codes(agency, id, version='~')

Get the codelist matching the parameters.

Return type:

Codelist

async get_concepts(agency, id, version='~')

Get the concept scheme matching the parameters.

Return type:

ConceptScheme

async get_data_structures(agency='*', id='*', version='~')

Get the data structure(s) matching the parameters.

Return type:

Sequence[DataStructureDefinition]

async get_dataflow_details(agency, id, version='~', detail=DataflowDetails.ALL)

Not served by .Stat.

Return type:

DataflowInfo

async get_dataflows(agency='*', id='*', version='~')

Get the dataflow(s) matching the parameters.

Return type:

Sequence[Dataflow]

async get_hierarchy(agency, id, version='~')

Get the hierarchy matching the parameters.

Return type:

Hierarchy

async get_mapping(agency, id, version='~')

Get the structure map matching the parameters.

Return type:

StructureMap

async get_metadata_providers(agency, with_flows=False)

Get the metadata providers for the supplied agency.

Return type:

Sequence[DataProvider]

async get_metadata_provision_agreement(agency, id, version='~')

Get the metadata provision agreement matching the parameters.

Return type:

MetadataProvisionAgreement

async get_metadata_structures(agency='*', id='*', version='~')

Get the metadata structure(s) matching the parameters.

Return type:

Sequence[MetadataStructure]

async get_metadataflows(agency='*', id='*', version='~')

Get the metadataflow(s) matching the parameters.

Return type:

Sequence[Metadataflow]

async get_providers(agency, with_flows=False)

Get the data providers for the supplied agency.

Return type:

Sequence[DataProvider]

async get_provision_agreement(agency, id, version='~')

Get the provision agreement matching the parameters.

Return type:

ProvisionAgreement

async get_report(provider, id, version='~')

Not served by .Stat.

Return type:

MetadataReport

async get_reports(artefact_type, agency, id, version='~')

Not served by .Stat.

Return type:

Sequence[MetadataReport]

async get_schema(context, agency, id, version)

Not served by .Stat (no SDMX-REST /schema endpoint).

Return type:

Schema

async get_vtl_transformation_scheme(agency, id, version='~')

Get the VTL transformation scheme matching the parameters.

Return type:

TransformationScheme

class pysdmx.api.stat.StatUploader(nsi_endpoint, transfer_endpoint, dataspace=None, token=None, pem=None, timeout=60.0)

Submit structures and data to a .Stat Suite service.

.Stat Suite splits submission across two services. Structural metadata goes to the NSI web service (POST {nsi}/rest/structure, SDMX-ML 2.1). Data goes to the Transfer service as a multipart/form-data upload (POST {transfer}/import/sdmxFile, file field file) scoped to a data space; it is asynchronous and returns a transaction id polled via POST {transfer}/status/request. Both services require an OAuth2 / Keycloak bearer token. Payloads are built with pysdmx’s pysdmx.io.write_sdmx().

The SDMX action (Append/Replace/Merge/Delete) is carried inside the submitted file (the SDMX-CSV 2.0 ACTION column, or the SDMX-ML dataset action), not as a request parameter. A dataflow’s structure must exist before its data is loaded, so use submit() (structure first, then data) for a new dataflow.

This class is standalone (it does not inherit pysdmx.api.dc.rest.SdmxConnector): submission needs authenticated POST requests, whereas the connector’s RestService only performs GET requests.

It is the .Stat counterpart of the FMR’s RegistryMaintenanceClient but is not interchangeable with it. That client targets the FMR and takes the SDMX StructureAction as a request parameter, returning None (raising on failure); this one carries the action inside the file, submits data asynchronously through the Transfer service, and returns result objects. Roughly, submit_structure() corresponds to put_structures.

Warning: This class is experimental and subject to change without prior notice. It is not covered by semantic versioning guarantees, and modifications to this class will not result in a major version increment. Use it with caution in production environments or critical processes.

cleanup_dsd(dsd, dataspace=None, cleanup_msd_only=False)

Clear a DSD’s data-side objects on the Transfer service.

Deleting a data structure through the NSI leaves the Transfer service’s per-DSD data-side objects in place, so re-creating the DSD with changed component types then fails on import (non-backward-compatible change). This wraps the Transfer DELETE {transfer}/cleanup/dsd method that drops them; run it as the final teardown step, after the NSI deletions.

Parameters:
  • dsd (Union[str, DataStructureDefinition]) – The data structure to clean up, as a short URN (e.g. "DataStructure=MD:DSD(1.0)") or a DataStructureDefinition.

  • dataspace (Optional[str]) – The target data space; defaults to the one set on the connector.

  • cleanup_msd_only (bool) – Clean up only the metadata-structure side.

Return type:

SubmissionResult

Returns:

The Transfer SubmissionResult acknowledgement.

Raises:
  • errors.Unauthorized – If the token is missing or rejected.

  • errors.Invalid – If dsd is not a valid reference, no data space is set, or the service returns a client error.

  • errors.InternalError – If the service returns a server error.

  • errors.Unavailable – If the service cannot be reached.

delete_data(dataset, dataspace=None)

Delete data by submitting it with the SDMX Delete action.

The dataset’s observations are uploaded to the Transfer service as SDMX-CSV 2.0 with ACTION=D per row, which deletes the matching observations. Asynchronous, like submit_data().

Parameters:
  • dataset (Union[Dataset, Sequence[Dataset]]) – A Schema-backed dataset (or a sequence of them) whose observations (keys) should be deleted.

  • dataspace (Optional[str]) – The target data space; defaults to the one set on the connector.

Return type:

SubmissionResult

Returns:

A SubmissionResult with the acknowledgement success, the service message, and the request_id (the async transaction id) to poll with submission_status().

Raises:
  • errors.Unauthorized – If the token is missing or rejected.

  • errors.Invalid – If no data space is set, or the service returns a client error.

  • errors.InternalError – If the service returns a server error.

  • errors.Unavailable – If the service cannot be reached.

delete_structure(artefacts)

Delete structural artefact(s) from the NSI web service.

Each artefact is deleted with DELETE {nsi}/rest/{type}/{agency}/{id}/{version} (the type segment is the lower-cased SDMX type). Accepts a maintainable artefact, a short-URN string (e.g. "DataConstraint=MD:CR_A_DF(1.0)"), or a sequence of either; a sequence is deleted in order, so pass dependents first.

.Stat dependencies: a data import auto-creates an actual content constraint CR_A_<dataflow>. To remove a dataflow, first delete_data(), then delete that constraint, then the dataflow, its DSD and concept scheme (a wrong order yields a 409/Invalid).

Parameters:

artefacts (Union[MaintainableArtefact, str, Sequence[Union[MaintainableArtefact, str]]]) – The artefact(s) or short URN(s) to delete.

Deletion is fail-fast: on the first error the exception is raised and an indeterminate prefix of the sequence may already have been deleted (re-run with the remaining artefacts). The NSI signals a delete failure with an HTTP status (mapped above) rather than an in-body error, but callers may still inspect the returned bodies.

Return type:

list[StructureSubmissionResult]

Returns:

The parsed StructureSubmissionResult for each artefact, in order.

Raises:
  • errors.Unauthorized – If the token is missing or rejected.

  • errors.Invalid – If the service returns a client error (e.g. a 409 because a dependent artefact still references it).

  • errors.NotFound – If the service reports a missing artefact. (Many .Stat NSIs treat DELETE as idempotent and return success for an already-absent artefact instead.)

  • errors.InternalError – If the service returns a server error.

  • errors.Unavailable – If the service cannot be reached.

put_structures(artefacts, structure_format=Format.STRUCTURE_SDMX_JSON_2_0_0)

Submit structures (the .Stat counterpart of put_structures).

Provided under the same method name and primary artefacts parameter as put_structures(), so a caller can target either client; it delegates to submit_structure(). The signatures differ where .Stat and the FMR genuinely diverge: .Stat returns a StructureSubmissionResult (not None), builds the SDMX message header itself (no header argument), and handles removal via a separate delete_structure() (no action argument); it adds structure_format for per-deployment format selection.

Parameters:
  • artefacts (Union[MaintainableArtefact, Sequence[Any]]) – A maintainable artefact (e.g. a Codelist or Dataflow) or a sequence of maintainable artefacts.

  • structure_format (Format) – The SDMX structure format to serialize to (see submit_structure()).

Return type:

StructureSubmissionResult

Returns:

The StructureSubmissionResult from the submission.

Raises:
  • errors.Invalid – If an artefact cannot be serialized in structure_format, or the service rejects the submission.

  • errors.Unauthorized – If the token is missing or rejected.

  • errors.InternalError – If the service returns a server error.

  • errors.Unavailable – If the service cannot be reached.

submission_status(request_id, dataspace=None, *, wait=False, interval=3.0, attempts=20)

Poll the status of an asynchronous data submission.

Issues POST {transfer}/status/request with the dataspace and id form fields.

Parameters:
  • request_id (str) – The transaction id returned by submit_data() or submit().

  • dataspace (Optional[str]) – The data space the request was submitted to; defaults to the one set on the connector.

  • wait (bool) – When True, poll until the execution_status is terminal (Completed/Failed/TimedOut/Canceled) or attempts is reached.

  • interval (float) – Seconds between polls when wait is True.

  • attempts (int) – Maximum number of polls when wait is True.

Return type:

SubmissionResult

Returns:

The parsed SubmissionResult (its execution_status and outcome tell you whether the async job succeeded).

Raises:
  • errors.Unauthorized – If the token is missing or rejected.

  • errors.Invalid – If no data space is set, or the service returns a client error.

  • errors.InternalError – If the service returns a server error.

  • errors.Unavailable – If the service cannot be reached.

submit(structures, dataset, dataspace=None, structure_format=Format.STRUCTURE_SDMX_JSON_2_0_0)

Submit the structure(s) first, then the data.

.Stat Suite requires a dataflow’s structure to exist before its data can be loaded, so the structure is submitted synchronously and only then is the (asynchronous) data submission started.

Parameters:
  • structures (Union[MaintainableArtefact, Sequence[Any]]) – The structural metadata to submit first.

  • dataset (Union[Dataset, Sequence[Dataset]]) – The data to submit once the structure is in place.

  • dataspace (Optional[str]) – The target data space for the data; defaults to the one set on the connector.

  • structure_format (Format) – The SDMX structure format for the structure step; passed to submit_structure() (defaults to SDMX-JSON 2.0 – see it for the format trade-offs).

Return type:

SubmissionResult

Returns:

The data submission’s SubmissionResult (with the request_id to poll with submission_status()).

Raises:
  • errors.Unauthorized – If the token is missing or rejected.

  • errors.Invalid – If the structure submission was not successful (the data is then not submitted), if no data space is set, or the service returns a client error.

  • errors.InternalError – If the service returns a server error.

  • errors.Unavailable – If the service cannot be reached.

submit_data(dataset, dataspace=None, data_format=Format.DATA_SDMX_CSV_2_0_0)

Submit data to the Transfer service.

The dataset is serialized with write_sdmx() and uploaded as a multipart/form-data request (file field file, plus the required dataspace field) to {transfer}/import/sdmxFile. The dataset must be Schema-backed (e.g. produced by pysdmx.io.get_datasets); a dataset whose structure is a bare URN cannot be written. Its schema must reference a dataflow (context="dataflow"), not a data structure: .Stat rejects a datastructure-bound dataset and the failure surfaces only at status-poll time (submit_data uploads it without complaint). The per-row/per-dataset action is taken from the file (the SDMX-CSV 2.0 ACTION column, or the SDMX-ML dataset action).

Submission is asynchronous: the returned SubmissionResult carries the transaction id (request_id) to pass to submission_status().

Parameters:
  • dataset (Union[Dataset, Sequence[Dataset]]) – A Schema-backed dataset, or a sequence of them.

  • dataspace (Optional[str]) – The target data space; defaults to the one set on the connector.

  • data_format (Format) – The SDMX data format to serialize to – an SDMX-CSV (DATA_SDMX_CSV_1_0_0 / 2_0_0 / 2_1_0) or SDMX-ML 2.1/3.0/3.1 data writer. Defaults to SDMX-CSV 2.0; the Transfer service auto-detects the format.

Return type:

SubmissionResult

Returns:

A SubmissionResult with the acknowledgement success, the service message, and the request_id (the async transaction id) to poll with submission_status().

Raises:
  • errors.Unauthorized – If the token is missing or rejected.

  • errors.Invalid – If no data space is set, or the service returns a client error.

  • errors.InternalError – If the service returns a server error.

  • errors.Unavailable – If the service cannot be reached.

submit_structure(structures, structure_format=Format.STRUCTURE_SDMX_JSON_2_0_0)

Submit structural metadata to the NSI web service.

The artefact(s) are serialized with write_sdmx() and posted to {nsi}/rest/structure. The Content-Type is taken from structure_format.

Parameters:
  • structures (Union[MaintainableArtefact, Sequence[Any]]) – A maintainable artefact (e.g. a Codelist or Dataflow) or a sequence of maintainable artefacts.

  • structure_format (Format) – The SDMX structure format to serialize to. Defaults to SDMX-JSON 2.0 – the only format whose writer covers every SDMX artefact type (the SDMX-ML writers do not support the metadata artefacts and have narrower type coverage). Override with an SDMX-ML format (STRUCTURE_SDMX_ML_2_1 / 3_0 / 3_1) or STRUCTURE_SDMX_JSON_2_1_0 for a deployment that requires it; write_sdmx() raises Invalid for a type that the chosen format cannot serialize.

Return type:

StructureSubmissionResult

Returns:

A StructureSubmissionResult parsed from the NSI SubmitStructureResponse body. A per-artefact failure, or a body reporting no artefact at all, surfaces as success=False (with the service messages), not as an exception: the service can report a failure inside the body even on an HTTP 200 response. The NSI may instead reject a submission with an HTTP error (e.g. 422 carrying an SDMX error document), which is raised as Invalid (see below) rather than returned – so check both.

Raises:
  • errors.Invalid – If an artefact type cannot be serialized in structure_format, or the service rejects the submission with an HTTP client error (e.g. 422).

  • errors.Unauthorized – If the token is missing or rejected.

  • errors.InternalError – If the service returns a server error.

  • errors.Unavailable – If the service cannot be reached.

class pysdmx.api.stat.StatEndpoints(*values)

Known .Stat Suite deployments, as SDMX-REST v2 base URLs.

Each value is the deployment’s SDMX-REST v2 API base – not its Data Explorer web UI – ready to pass to StatConnector. The first group is anonymously readable. The second group points at a real endpoint that needs one extra step (an API key, a valid TLS certificate, or the service’s backend to be up), noted per entry; passing it as-is will not work until that condition is met.

All base URLs were confirmed live against each deployment’s structure/dataflow endpoint; the second group needs its noted prerequisite before it returns data.

Authentication

Token-acquisition flows for the .Stat Suite APIs. Each class takes the realm (authority) URL, runs its OAuth2 flow, and exposes get_token().

class pysdmx.api.stat.authentication.KeycloakDeviceAuthentication(authority_url, client_id='app', proxy=None)

Interactive device-code flow (RFC 8628) with PKCE.

Prints a verification URL plus a short code, then polls the token endpoint until the user finishes signing in from any browser. No redirect URI is involved, so it works with federated logins (e.g. GitHub) and public clients out of the box.

get_token()

Return a valid access token, or None if acquisition failed.

Re-runs the flow when the cached token is missing or expired; for the interactive device flow that means a new browser sign-in.

Return type:

Optional[str]

is_authenticated()

Ask the provider whether the current access token is active.

Sends the token to the OIDC userinfo endpoint under the authority URL, and only an HTTP 200 counts. False when the flow never produced a token, the provider rejects it (expired, revoked, missing openid scope), or the endpoint cannot be reached.

Return type:

bool

property refresh_token: str | None

Refresh token from the last flow (None if none was issued).

class pysdmx.api.stat.authentication.ClientCredentialsAuthentication(authority_url, client_id, client_secret, proxy=None)

Non-interactive client-credentials flow (machine-to-machine).

The application authenticates as itself – no user involved. Requires a confidential client: its id, its secret, and a service account holding the permissions the API calls will need.

get_token()

Return a valid access token, or None if acquisition failed.

Re-runs the flow when the cached token is missing or expired; for the interactive device flow that means a new browser sign-in.

Return type:

Optional[str]

is_authenticated()

Ask the provider whether the current access token is active.

Sends the token to the OIDC userinfo endpoint under the authority URL, and only an HTTP 200 counts. False when the flow never produced a token, the provider rejects it (expired, revoked, missing openid scope), or the endpoint cannot be reached.

Return type:

bool

property refresh_token: str | None

Refresh token from the last flow (None if none was issued).

class pysdmx.api.stat.authentication.KeycloakAuthentication(authority_url, user, password, client_id='app', client_secret='', proxy=None)

Non-interactive resource-owner password grant.

Sends a username and password directly to the token endpoint. The user needs a local Keycloak password (federated accounts, e.g. GitHub, have none) and the client must allow direct access grants. This is a legacy grant – prefer the device or client-credentials flow when possible.

get_token()

Return a valid access token, or None if acquisition failed.

Re-runs the flow when the cached token is missing or expired; for the interactive device flow that means a new browser sign-in.

Return type:

Optional[str]

is_authenticated()

Ask the provider whether the current access token is active.

Sends the token to the OIDC userinfo endpoint under the authority URL, and only an HTTP 200 counts. False when the flow never produced a token, the provider rejects it (expired, revoked, missing openid scope), or the endpoint cannot be reached.

Return type:

bool

property refresh_token: str | None

Refresh token from the last flow (None if none was issued).