.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 itsget_*methods return the same model objects – but it reads .Stat’s SDMX-ML 2.1 and parses it withread_sdmx()(the FMR client’s JSON deserializers do not apply). Structure types or endpoints .Stat does not serve raiseInvalid.Adds the SDMX data-discovery-and-retrieval profile (
BasicConnector) that the FMR client does not offer –dataflows(),dataflow()anddata()– with the same signatures as the genericSdmxConnector. Reads are anonymous unless a bearertokenis supplied.Obtain the
agency,idandversionof 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
datamethod 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 implementingMaintainableIdentification(e.g. aDatafloworDataflowRef).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 apysdmx.api.dc.queryfilter.
- 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
dataflowmethod 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, theagency:id(version)shorthand, or any object implementingMaintainableIdentification(e.g. aDatafloworDataflowRef).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 raisesInvalid; usedata()to query filtered data.
- Return type:
- Returns:
The dataflow with its data structure.
- dataflows(search_term=None)
List available dataflows (SDMX data-discovery profile).
Implements the
dataflowsmethod 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_categories(agency, id, version='~')
Get the category scheme matching the parameters.
- Return type:
- 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:
- get_concepts(agency, id, version='~')
Get the concept scheme matching the parameters.
- Return type:
- 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:
- 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:
- get_mapping(agency, id, version='~')
Get the structure map matching the parameters.
- Return type:
- 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:
- 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
/schemaendpoint).- Return type:
- get_vtl_transformation_scheme(agency, id, version='~')
Get the VTL transformation scheme matching the parameters.
- Return type:
- 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: inheritsAsyncRegistryClient, reads .Stat’s SDMX-ML 2.1 and parses it withread_sdmx(), and raisesInvalidfor endpoints .Stat does not serve. Adds the async data-discovery-and-retrieval profile:dataflows(),dataflow()anddata(). Reads are anonymous unless a bearertokenis 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:
dataflow (
Union[str,MaintainableIdentification]) – The dataflow to query – a short or full URN, or any object implementingMaintainableIdentification.filters (
Union[BooleanFilter,DateTimeFilter,MultiFilter,NumberFilter,TextFilter,str,None]) – The query filters, if any (seeStatConnector.data()).
- 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:
dataflow (
Union[str,MaintainableIdentification]) – The dataflow – a short/full URN, theagency:id(version)shorthand, or aMaintainableIdentification.filters (
Union[BooleanFilter,DateTimeFilter,MultiFilter,NumberFilter,TextFilter,str,None]) – Not supported on .Stat (raisesInvalid); usedata().
- Return type:
- 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:
- 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:
- async get_codes(agency, id, version='~')
Get the codelist matching the parameters.
- Return type:
- async get_concepts(agency, id, version='~')
Get the concept scheme matching the parameters.
- Return type:
- 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:
- 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:
- async get_mapping(agency, id, version='~')
Get the structure map matching the parameters.
- Return type:
- 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:
- 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
/schemaendpoint).- Return type:
- async get_vtl_transformation_scheme(agency, id, version='~')
Get the VTL transformation scheme matching the parameters.
- Return type:
- 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 amultipart/form-dataupload (POST {transfer}/import/sdmxFile, file fieldfile) scoped to a data space; it is asynchronous and returns a transaction id polled viaPOST {transfer}/status/request. Both services require an OAuth2 / Keycloak bearer token. Payloads are built with pysdmx’spysdmx.io.write_sdmx().The SDMX action (Append/Replace/Merge/Delete) is carried inside the submitted file (the SDMX-CSV 2.0
ACTIONcolumn, or the SDMX-ML dataset action), not as a request parameter. A dataflow’s structure must exist before its data is loaded, so usesubmit()(structure first, then data) for a new dataflow.This class is standalone (it does not inherit
pysdmx.api.dc.rest.SdmxConnector): submission needs authenticatedPOSTrequests, whereas the connector’sRestServiceonly performsGETrequests.It is the .Stat counterpart of the FMR’s
RegistryMaintenanceClientbut is not interchangeable with it. That client targets the FMR and takes the SDMXStructureActionas a request parameter, returningNone(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 toput_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/dsdmethod 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 aDataStructureDefinition.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
SubmissionResultacknowledgement.- Raises:
errors.Unauthorized – If the token is missing or rejected.
errors.Invalid – If
dsdis 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=Dper row, which deletes the matching observations. Asynchronous, likesubmit_data().- Parameters:
- Return type:
SubmissionResult- Returns:
A
SubmissionResultwith the acknowledgementsuccess, the servicemessage, and therequest_id(the async transaction id) to poll withsubmission_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, firstdelete_data(), then delete that constraint, then the dataflow, its DSD and concept scheme (a wrong order yields a409/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
StructureSubmissionResultfor 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
409because 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
artefactsparameter asput_structures(), so a caller can target either client; it delegates tosubmit_structure(). The signatures differ where .Stat and the FMR genuinely diverge: .Stat returns aStructureSubmissionResult(notNone), builds the SDMX message header itself (noheaderargument), and handles removal via a separatedelete_structure()(noactionargument); it addsstructure_formatfor per-deployment format selection.- Parameters:
artefacts (
Union[MaintainableArtefact,Sequence[Any]]) – A maintainable artefact (e.g. aCodelistorDataflow) or a sequence of maintainable artefacts.structure_format (
Format) – The SDMX structure format to serialize to (seesubmit_structure()).
- Return type:
StructureSubmissionResult- Returns:
The
StructureSubmissionResultfrom 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/requestwith thedataspaceandidform fields.- Parameters:
request_id (
str) – The transaction id returned bysubmit_data()orsubmit().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 theexecution_statusis terminal (Completed/Failed/TimedOut/Canceled) orattemptsis reached.interval (
float) – Seconds between polls whenwaitis True.attempts (
int) – Maximum number of polls whenwaitis True.
- Return type:
SubmissionResult- Returns:
The parsed
SubmissionResult(itsexecution_statusandoutcometell 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 tosubmit_structure()(defaults to SDMX-JSON 2.0 – see it for the format trade-offs).
- Return type:
SubmissionResult- Returns:
The data submission’s
SubmissionResult(with therequest_idto poll withsubmission_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 amultipart/form-datarequest (file fieldfile, plus the requireddataspacefield) to{transfer}/import/sdmxFile. The dataset must be Schema-backed (e.g. produced bypysdmx.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_datauploads it without complaint). The per-row/per-dataset action is taken from the file (the SDMX-CSV 2.0ACTIONcolumn, or the SDMX-ML dataset action).Submission is asynchronous: the returned
SubmissionResultcarries the transaction id (request_id) to pass tosubmission_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
SubmissionResultwith the acknowledgementsuccess, the servicemessage, and therequest_id(the async transaction id) to poll withsubmission_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. TheContent-Typeis taken fromstructure_format.- Parameters:
structures (
Union[MaintainableArtefact,Sequence[Any]]) – A maintainable artefact (e.g. aCodelistorDataflow) 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) orSTRUCTURE_SDMX_JSON_2_1_0for a deployment that requires it;write_sdmx()raisesInvalidfor a type that the chosen format cannot serialize.
- Return type:
StructureSubmissionResult- Returns:
A
StructureSubmissionResultparsed from the NSISubmitStructureResponsebody. A per-artefact failure, or a body reporting no artefact at all, surfaces assuccess=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 asInvalid(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/dataflowendpoint; 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).