webservices.webservice¶

HTTP access to the web services.

The queried services (identifiers.org, OLS, ChEBI, UniChem) answer with a transient error every now and then, e.g., a HTML error page with status 500 instead of the expected JSON. get_session provides a shared requests.Session which retries these responses with an exponential backoff and applies a default timeout, so that a single hiccup of a service does not fail the query.

from pymetadata.webservices.webservice import get_json

data = get_json("https://www.ebi.ac.uk/unichem/rest/inchikey/...")

get_json raises a WebserviceError for everything which keeps a query from answering, i.e., an unreachable service, an error response and a response which is not JSON. A service which is down for longer than the retries answers with an HTML error page, so the status code has to be checked before the response is parsed; get_json does that and the callers fall back to their cache, see pymetadata.cache.

WebserviceError ¶

Bases: OSError

Raised when a web service query cannot be answered.

Covers the unreachable service, the error response and the response which is not JSON, i.e., everything a caller handles the same way: fall back to the cached content, see pymetadata.cache.read_json_cache_fallback.

WebserviceNotFoundError ¶

Bases: WebserviceError

Raised when a web service answers that the queried entry does not exist (404).

A caller tells a missing entry apart from a service which cannot answer: the entry is reported as unknown, and no cached content is used.

get_session ¶

get_session()

Get the shared session for the web service queries.

The session retries the transient responses in RETRY_STATUS_CODES and times out after TIMEOUT seconds.

Returns:

Type	Description
`Session`	The shared session, created on first use.

get_json ¶

get_json(url, params=None)

Query a url and return the parsed JSON response.

Parameters:

Name	Type	Description	Default
`url`	`str`	url to query	required
`params`	`dict[str, str] \| None`	query parameters, encoded and appended to the url	`None`

Returns:

Type	Description
`Any`	The parsed JSON response.

Raises:

Type	Description
`WebserviceNotFoundError`	if the service answers 404
`WebserviceError`	if the service cannot be reached, answers with a status other than 200, or does not answer with JSON

get_bytes ¶

get_bytes(url, params=None)

Query a url for an svg image and return its content.

Parameters:

Name	Type	Description	Default
`url`	`str`	url to query	required
`params`	`dict[str, str] \| None`	query parameters, encoded and appended to the url	`None`

Returns:

Type	Description
`bytes`	The content of the response.

Raises:

Type	Description
`WebserviceNotFoundError`	if the service answers 404
`WebserviceError`	if the service cannot be reached, answers with another status than 200, or does not answer with an svg image