cache¶

Caching of web service responses.

Queries to identifiers.org, OLS, ChEBI and UniChem are cached on disk so that repeated lookups of the same term do not hit the network again. Caching is on by default and controlled by pymetadata.CACHE_USE and pymetadata.CACHE_PATH, which are read at query time.

A cached response is refreshed once it is older than the cache duration of its service, see CACHE_DURATION_ONTOLOGY and CACHE_DURATION_REGISTRY. If the refresh fails, because the service is unreachable or answers with an error, the outdated content is used instead of failing the query and a warning is logged, see read_json_cache_fallback. Working offline therefore keeps working with whatever was cached before.

DataclassJSONEncoder ¶

Bases: JSONEncoder

JSON encoder which serializes dataclasses via their __dict__.

default ¶

default(o)

Serialize an object which json cannot serialize itself.

cache_age ¶

cache_age(cache_path)

Get the age of a cache file in hours.

Parameters:

Name	Type	Description	Default
`cache_path`	`Path`	path of the cache file	required

Returns:

Type	Description
`float \| None`	The age in hours, or None if the file does not exist.

read_json_cache ¶

read_json_cache(cache_path, max_age=None)

Read a JSON cache file.

Parameters:

Name	Type	Description	Default
`cache_path`	`Path`	path of the cache file	required
`max_age`	`float \| None`	maximum age of the content in hours; older content is treated as if it were not cached. Any age is accepted if None	`None`

Returns:

Type	Description
`dict`	The cached content.

Raises:

Type	Description
`IOError`	if the cache file does not exist or is older than `max_age`

read_json_cache_fallback ¶

read_json_cache_fallback(cache_path, reason)

Read a cache file of any age, after the query which should refresh it failed.

The library prefers outdated content over no content, so that an unreachable service does not fail a query which was answered before. The age of the content is not checked and a warning names the reason, so that the fallback is visible in the log.

Parameters:

Name	Type	Description	Default
`cache_path`	`Path`	path of the cache file	required
`reason`	`str`	why the content could not be refreshed, e.g., the error of the failed query	required

Returns:

Type	Description
`dict \| None`	The cached content, or None if nothing is cached.

write_json_cache ¶

write_json_cache(data, cache_path, json_encoder=None)

Write a JSON cache file.

Missing parent directories are created.

Parameters:

Name	Type	Description	Default
`data`	`dict`	data to serialize	required
`cache_path`	`Path`	path of the cache file	required
`json_encoder`	`type[JSONEncoder] \| None`	encoder for objects json cannot serialize, e.g. `DataclassJSONEncoder` for dataclasses	`None`