pymetadata 0.7.0__tar.gz → 0.8.0__tar.gz

{pymetadata-0.7.0 → pymetadata-0.8.0}/.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.7.0"
+current_version = "0.8.0"
 commit = true
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]

{pymetadata-0.7.0 → pymetadata-0.8.0}/CITATION.cff

@@ -8,7 +8,7 @@ authors:
     given-names: "Matthias"
     orcid: "https://orcid.org/0000-0003-1725-179X"
     affiliation: "Humboldt-University Berlin, Faculty of Life Science, Institute for Biology, Biology, Berlin; University Lübeck; University Hospital Schleswig-Holstein, Campus Lübeck, First Department of Medicine, Germany"
-version: "0.7.0"
+version: "0.8.0"
 date-released: "2026-09-23"
 doi: "10.5281/zenodo.5308801"
 license: MIT

{pymetadata-0.7.0 → pymetadata-0.8.0}/CLAUDE.md

@@ -73,7 +73,10 @@ identifiers.org URL (classic or compact), a bioregistry.io URL, a `urn:miriam:*`
 a `collection/term` shorthand, or an arbitrary URL, and normalizes it into
 `collection` + `term`. Validation checks the term against the identifiers.org
 registry pattern (`webservices/registry.py`). `RDFAnnotationData` enriches an
-annotation with label/description/synonyms/xrefs by querying OLS.
+annotation with label/description/synonyms/xrefs by querying OLS, and with the
+providers of the collection: `url` is the url of the primary provider (the official
+non deprecated one, see `primary_resource`), `providers` lists the others, and
+`collection_name`, `collection_homepage` and `pattern_match` describe the collection.
 
 **Ontologies are generated code.** `ontologies/sbo.py`, `kisao.py`, `pbpko.py`
 are machine-generated (large; do not hand-edit). Each is a class of
@@ -103,9 +106,11 @@ cheap (the `pymetadata.metadata` package was removed in 0.6.0).
 
 **Web services + caching.** The `webservices/` package holds everything which
 hits a remote API: `ols.py` (EBI OLS4), `registry.py` (identifiers.org),
-`chebi.py` and `unichem.py`, all going through the shared, retrying session of
+`chebi.py` (also the svg structure of a compound), `uniprot.py` and `unichem.py`, all going through the shared, retrying session of
 `webservices/webservice.py`, whose `get_json` turns an unreachable service, an
-error response and a non-JSON body into one `WebserviceError`. They share the
+error response and a non-JSON body into one `WebserviceError`; a 404 raises its
+subclass `WebserviceNotFoundError`, which callers treat as an unknown entry and
+never answer from an outdated cache. `get_bytes` does the same for svg images. They share the
 JSON cache helpers in `cache.py`, gated by the module-level globals
 `pymetadata.CACHE_USE` (default `True`) and `pymetadata.CACHE_PATH`
 (`~/.cache/pymetadata`). These are read at call time, so consumers override them by
@@ -115,7 +120,7 @@ an ontology release) or `CACHE_DURATION_REGISTRY` (24 h, for the identifiers.org
 registry). When a refresh fails, `read_json_cache_fallback` returns the outdated
 content with a warning instead of failing, so queries answered before keep
 working offline; `tests/test_offline.py` covers this per service. The corresponding tests
-(`test_ols.py`, `test_registry.py`, `test_chebi.py`, `test_unichem.py`) require
+(`test_ols.py`, `test_registry.py`, `test_chebi.py`, `test_unichem.py`, `test_uniprot.py`) require
 network access.
 
 `console.py` (rich console, for scripts and `__main__` blocks) and `log.py`

{pymetadata-0.7.0 → pymetadata-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pymetadata
-Version: 0.7.0
+Version: 0.8.0
 Summary: pymetadata are python utilities for working with metadata.
 Project-URL: Homepage, https://matthiaskoenig.github.io/pymetadata
 Project-URL: Documentation, https://matthiaskoenig.github.io/pymetadata

{pymetadata-0.7.0 → pymetadata-0.8.0}/docs/annotations.md

@@ -90,11 +90,15 @@ from pymetadata.core.miriam import BQB
 
 annotation = RDFAnnotation(qualifier=BQB.IS, resource="chebi/CHEBI:33699")
 data = RDFAnnotationData(annotation)
-print(data.url)  # url of the first provider
+print(data.url)  # url of the primary provider, the official one of the registry
+print(data.providers)  # the non deprecated providers, the primary one first
+print(data.collection_name)  # name of the collection
+print(data.collection_homepage)  # homepage of the primary provider
+print(data.pattern_match)  # whether the term matches the pattern of the collection
 print(data.xrefs)  # one entry per identifiers.org provider
 ```
 
-`query_ols()` then asks the [Ontology Lookup Service](https://www.ebi.ac.uk/ols4) for the term itself and fills in label, description and synonyms. Note that it also replaces `xrefs` with the cross references reported by OLS, which can be empty for a given term:
+`query_ols()` then asks the [Ontology Lookup Service](https://www.ebi.ac.uk/ols4) for the term itself and fills in label, description and synonyms, and the ontology, the IRI and the page of the term in OLS (`ontology`, `iri`, `ols_url`). A collection which is not on OLS gives no information and no message, a term which OLS does not know gives a warning. Note that it also replaces `xrefs` with the cross references reported by OLS, which can be empty for a given term:
 
 ```python
 data.query_ols()
@@ -104,6 +108,8 @@ print(data.description)  # An RNA molecule that transfers the coding information
 print(data.synonyms)  # mRNA, ...
 ```
 
+Protein information of UniProt and the structure of a ChEBI compound are queried with `UniprotQuery.query("P69905")` and `ChebiQuery.structure("CHEBI:15377")`, see the [API reference](api/webservices.uniprot.md).
+
 Both steps require network access. Responses are cached on disk by default, so repeated terms are not queried again; see [Cache](installation.md#cache).
 
 ## Ontology terms { #ontology-terms }

{pymetadata-0.7.0 → pymetadata-0.8.0}/docs/api/index.md

@@ -30,10 +30,11 @@ The services queried for the information which does not ship with the package. T
 
 | module | description |
 | --- | --- |
-| [webservices.chebi](webservices.chebi.md) | Substance information from ChEBI |
+| [webservices.chebi](webservices.chebi.md) | Substance information and structure from ChEBI |
 | [webservices.ols](webservices.ols.md) | Lookup of ontology terms in the Ontology Lookup Service |
 | [webservices.registry](webservices.registry.md) | The identifiers.org registry |
 | [webservices.unichem](webservices.unichem.md) | Substance cross references from UniChem |
+| [webservices.uniprot](webservices.uniprot.md) | Protein information from UniProt |
 | [webservices.webservice](webservices.webservice.md) | The shared HTTP session |
 
 ## pymetadata.ontologies

pymetadata-0.8.0/docs/api/webservices.uniprot.md

@@ -0,0 +1,3 @@
+# webservices.uniprot
+
+::: pymetadata.webservices.uniprot

pymetadata-0.8.0/release-notes/0.8.0.md

@@ -0,0 +1,19 @@
+# Release notes for pymetadata 0.8.0
+![pymetadata](./docs/images/favicon/pymetadata-100x100-300dpi.png)
+
+## New
+
+- `UniprotQuery.query` reads the protein information of a UniProt accession (name, organism, genes, length, function), including isoform accessions such as `P69905-2`. Responses are cached, an outdated cache is used when UniProt cannot be reached.
+- `ChebiQuery.structure` returns the structure of a ChEBI compound as svg, cached and written atomically.
+- `RDFAnnotationData` carries the `ontology`, `iri` and `ols_url` of the term in OLS, and reports the `providers` of a collection with the primary one first, the `collection_name` and `collection_homepage`, and `pattern_match`, whether the term matches the pattern of its collection.
+- `OLSQuery` reports the `ontology`, the `iri` and the page of the term in OLS (`ols_url`).
+- `WebserviceNotFoundError`, a subclass of `WebserviceError` for a 404 answer, and `get_bytes` for binary downloads.
+
+## Changes
+
+- A collection which is not on OLS gives no information and no warning or error.
+- A term which OLS does not know is a warning and no longer an error; an outdated cache entry is not used for it.
+- The `url` of an annotation is the url of the official non deprecated provider of the registry, e.g., UniProt links UniProt instead of NCBI Protein.
+- A corrupt cache file of the ChEBI and UniProt queries is queried again.
+
+Your pymetadata team

{pymetadata-0.7.0 → pymetadata-0.8.0}/src/pymetadata/__init__.py

@@ -7,7 +7,7 @@ from pathlib import Path
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 
 __author__ = "Matthias Koenig"
-__version__ = "0.7.0"
+__version__ = "0.8.0"
 
 
 program_name: str = "pymetadata"

{pymetadata-0.7.0 → pymetadata-0.8.0}/src/pymetadata/core/annotation.py

@@ -21,6 +21,7 @@ print(annotation.validate())
 import logging
 import re
 import urllib.parse
+from dataclasses import asdict, dataclass
 from enum import Enum
 from functools import lru_cache
 from pprint import pprint
@@ -29,7 +30,7 @@ from typing import Any, ClassVar, Final
 from pymetadata.core.miriam import BQB, BQM
 from pymetadata.core.xref import CrossReference, is_url
 from pymetadata.webservices.ols import ONTOLOGIES, OLSQuery
-from pymetadata.webservices.registry import Namespace, get_registry
+from pymetadata.webservices.registry import Namespace, Resource, get_registry
 
 _OLS_QUERY: OLSQuery | None = None
 
@@ -482,6 +483,46 @@ class RDFAnnotation:
         return valid_qualifier and valid_term
 
 
+@dataclass
+class Provider:
+    """A provider which resolves the term of an annotation.
+
+    Attributes:
+        name: name of the provider, e.g., `UniProt`
+        url: url of the term at the provider
+        official: whether the registry names it the official provider
+    """
+
+    name: str
+    url: str
+    official: bool
+
+
+def primary_resource(resources: list[Resource]) -> Resource | None:
+    """Get the provider a term links to: the official non deprecated one.
+
+    Falls back to the first non deprecated provider, and to the first provider
+    when all are deprecated.
+    """
+    active = [resource for resource in resources if not resource.deprecated]
+    for resource in active:
+        if resource.official:
+            return resource
+    if active:
+        return active[0]
+    return resources[0] if resources else None
+
+
+def pattern_matches(pattern: str | None, term: str | None) -> bool | None:
+    """Check a term against the pattern of its collection, None if it cannot be checked."""
+    if not pattern or not term:
+        return None
+    try:
+        return re.match(pattern, term) is not None
+    except re.error:
+        return None
+
+
 class RDFAnnotationData(RDFAnnotation):
     """An annotation with the information behind the identifier resolved.
 
@@ -492,8 +533,16 @@ class RDFAnnotationData(RDFAnnotation):
     cross references reported by OLS.
 
     Attributes:
-        url: url of the first provider of the collection
+        url: url of the primary provider of the collection
+        providers: non deprecated providers, the primary one first
+        collection_name: name of the collection, e.g., `UniProt Knowledgebase`
+        collection_homepage: homepage of the primary provider
+        pattern_match: whether the term matches the pattern of the collection,
+            None if it cannot be checked
         label: name of the term
+        ontology: ontology id of the term in OLS, e.g., `go`
+        iri: IRI of the term
+        ols_url: page of the term in OLS
         description: definition of the term
         synonyms: synonyms of the term
         xrefs: cross references of the term
@@ -519,8 +568,15 @@ class RDFAnnotationData(RDFAnnotation):
         self.term: str | None = annotation.term
         self.provider = annotation.provider
         self.url: str | None = None
+        self.providers: list[Provider] = []
+        self.collection_name: str | None = None
+        self.collection_homepage: str | None = None
+        self.pattern_match: bool | None = None
         self.description: str | None = None
         self.label: str | None = None
+        self.ontology: str | None = None
+        self.iri: str | None = None
+        self.ols_url: str | None = None
         self.synonyms: list[Any] = []
         self.xrefs: list[Any] = []
         self.warnings: list[Any] = []
@@ -539,6 +595,7 @@ class RDFAnnotationData(RDFAnnotation):
             if not namespace.resources:
                 namespace.resources = []
 
+            urls: dict[int, str] = {}
             for ns_resource in namespace.resources:
                 # create url
                 url = ns_resource.urlPattern
@@ -563,9 +620,7 @@ class RDFAnnotationData(RDFAnnotation):
                 url = url.replace("{$Id}", term)
                 url = url.replace("{$id}", term)
 
-                if not self.url:
-                    # set url to first resource url
-                    self.url = url
+                urls[id(ns_resource)] = url
 
                 # print(url)
                 _xref = CrossReference(
@@ -575,6 +630,36 @@ class RDFAnnotationData(RDFAnnotation):
                 if valid:
                     self.xrefs.append(_xref)
 
+            primary = primary_resource(namespace.resources)
+            self.collection_name = namespace.name
+            candidates = [self.term]
+            if (
+                namespace_embedded
+                and namespace.prefix
+                and self.term
+                and not self.term.lower().startswith(f"{namespace.prefix.lower()}:")
+            ):
+                # the pattern contains the prefix, the term is written without it
+                candidates = [
+                    f"{namespace.prefix.upper()}:{self.term}",
+                    f"{namespace.prefix}:{self.term}",
+                ]
+            results = [pattern_matches(namespace.pattern, c) for c in candidates]
+            self.pattern_match = (
+                True if any(results) else (False if False in results else None)
+            )
+            if primary is not None:
+                self.collection_homepage = primary.resourceHomeUrl
+                self.url = urls.get(id(primary))
+            active = [
+                r for r in namespace.resources if not r.deprecated and id(r) in urls
+            ]
+            active.sort(key=lambda r: r is not primary)
+            self.providers = [
+                Provider(name=r.name, url=urls[id(r)], official=bool(r.official))
+                for r in active
+            ]
+
         # query OLS information
         self.query_ols()
 
@@ -591,8 +676,15 @@ class RDFAnnotationData(RDFAnnotation):
             "collection": self.collection,
             "term": self.term,
             "label": self.label,
+            "ontology": self.ontology,
+            "iri": self.iri,
+            "ols_url": self.ols_url,
             "description": self.description,
             "url": self.url,
+            "providers": [asdict(p) for p in self.providers],
+            "collection_name": self.collection_name,
+            "collection_homepage": self.collection_homepage,
+            "pattern_match": self.pattern_match,
             "synonyms": self.synonyms,
             "xrefs": self.xrefs,
             "errors": self.errors,
@@ -618,6 +710,9 @@ class RDFAnnotationData(RDFAnnotation):
         if self.description is None:
             self.description = info["description"]
 
+        self.ontology = info.get("ontology")
+        self.iri = info.get("iri")
+        self.ols_url = info.get("ols_url")
         self.synonyms = info["synonyms"]
         self.xrefs = info["xrefs"]
         self.warnings.extend(info["warnings"])

{pymetadata-0.7.0 → pymetadata-0.8.0}/src/pymetadata/webservices/chebi.py

@@ -16,6 +16,7 @@ See <https://www.ebi.ac.uk/chebi/>.
 import contextlib
 import logging
 import re
+import tempfile
 from pathlib import Path
 from typing import Any
 
@@ -23,12 +24,18 @@ import pymetadata
 from pymetadata.cache import (
     CACHE_DURATION_ONTOLOGY,
     DataclassJSONEncoder,
+    cache_age,
     cache_file,
     read_json_cache,
     read_json_cache_fallback,
     write_json_cache,
 )
-from pymetadata.webservices.webservice import WebserviceError, get_json
+from pymetadata.webservices.webservice import (
+    WebserviceError,
+    WebserviceNotFoundError,
+    get_bytes,
+    get_json,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -38,6 +45,25 @@ CHEBI_PATTERN = re.compile(r"^(?:CHEBI:)?(\d+)$", flags=re.IGNORECASE)
 #: endpoint of the ChEBI compounds, queried with the `chebi_ids` parameter
 CHEBI_URL = "https://www.ebi.ac.uk/chebi/backend/api/public/compounds/"
 
+#: endpoint of the structure (svg image) of a compound, formatted with its number
+CHEBI_STRUCTURE_URL = (
+    "https://www.ebi.ac.uk/chebi/backend/api/public/compound/{}/structure/"
+)
+
+
+def _write_bytes_atomic(path: Path, content: bytes) -> None:
+    """Write a file atomically, so a reader never sees a partial file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as fp:
+            temporary_path = Path(fp.name)
+            fp.write(content)
+        temporary_path.replace(path)
+    finally:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+
 
 class ChebiQuery:
     """Queries against the ChEBI web service.
@@ -95,8 +121,8 @@ class ChebiQuery:
         chebi_path = cache_file(Path(cache_path) / "chebi", chebi)
         data: dict[str, Any] = {}
         if cache:
-            with contextlib.suppress(OSError):
-                # cache does not exist or is outdated
+            with contextlib.suppress(OSError, ValueError):
+                # cache does not exist, is outdated or corrupt
                 data = read_json_cache(
                     cache_path=chebi_path, max_age=CACHE_DURATION_ONTOLOGY
                 )
@@ -144,6 +170,55 @@ class ChebiQuery:
 
         return data
 
+    @staticmethod
+    def structure(
+        chebi: str, cache: bool | None = None, cache_path: Path | None = None
+    ) -> bytes | None:
+        """Get the structure of a ChEBI compound as an svg image.
+
+        Args:
+            chebi: ChEBI term, e.g., `CHEBI:33699`
+            cache: cache the image, defaults to `pymetadata.CACHE_USE`
+            cache_path: directory for cached responses, defaults to
+                `pymetadata.CACHE_PATH`
+
+        Returns:
+            The svg image, None if the id is invalid, the compound has no
+            structure, or ChEBI cannot be reached and nothing is cached.
+        """
+        match = CHEBI_PATTERN.match(chebi.strip()) if chebi else None
+        if not match:
+            logger.error("Invalid ChEBI id: '%s'", chebi)
+            return None
+        number = match.group(1)
+        if cache is None:
+            cache = pymetadata.CACHE_USE
+        if cache_path is None:
+            cache_path = pymetadata.CACHE_PATH
+        path = Path(cache_path) / "chebi" / f"CHEBI%3A{number}.svg"
+        age = cache_age(path) if cache else None
+        if age is not None and age <= CACHE_DURATION_ONTOLOGY:
+            return path.read_bytes()
+        try:
+            svg = get_bytes(CHEBI_STRUCTURE_URL.format(number))
+        except WebserviceNotFoundError:
+            return None
+        except WebserviceError as err:
+            if age is not None:
+                logger.warning(
+                    "Using outdated structure of 'CHEBI:%s': %s", number, err
+                )
+                return path.read_bytes()
+            logger.error(
+                "ChEBI structure could not be retrieved for 'CHEBI:%s': %s",
+                number,
+                err,
+            )
+            return None
+        if cache:
+            _write_bytes_atomic(path, svg)
+        return svg
+
 
 if __name__ == "__main__":
     from pymetadata.console import console

{pymetadata-0.7.0 → pymetadata-0.8.0}/src/pymetadata/webservices/ols.py

@@ -35,7 +35,11 @@ from pymetadata.cache import (
     write_json_cache,
 )
 from pymetadata.webservices.registry import get_registry
-from pymetadata.webservices.webservice import WebserviceError, get_json
+from pymetadata.webservices.webservice import (
+    WebserviceError,
+    WebserviceNotFoundError,
+    get_json,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -96,6 +100,24 @@ ONTOLOGIES = [
 ]
 
 
+OLS_TERM_PAGE = "https://www.ebi.ac.uk/ols4/ontologies/{}/classes?iri={}"
+
+
+def ols_term_url(ontology: str | None, iri: str | None) -> str | None:
+    """Get the page of a term in the Ontology Lookup Service.
+
+    Args:
+        ontology: ontology id of OLS, e.g., `go`
+        iri: IRI of the term
+
+    Returns:
+        The url of the page, or None without an ontology or an IRI.
+    """
+    if not ontology or not iri:
+        return None
+    return OLS_TERM_PAGE.format(ontology, urllib.parse.quote(iri, safe=""))
+
+
 class OLSQuery:
     """Queries against the Ontology Lookup Service.
 
@@ -174,7 +196,8 @@ class OLSQuery:
 
         Returns:
             The OLS response, with `errors` and `warnings` describing problems
-            with the query.
+            with the query. A term OLS does not know is a warning, an ontology
+            which is not on OLS returns no information and no message.
         """
         if not ontology:
             return {"errors": [], "warnings": ["No collection."]}
@@ -191,10 +214,7 @@ class OLSQuery:
             if not namespace or not any(
                 resource.providerCode == "ols" for resource in namespace.resources or []
             ):
-                return {
-                    "errors": [],
-                    "warnings": [f"'{ontology}' is not on OLS."],
-                }
+                return {"errors": [], "warnings": []}
 
         iri = self.get_iri(ontology=ontology, term=term)
 
@@ -216,6 +236,8 @@ class OLSQuery:
             logger.info("Query: %s", url)
             try:
                 data = get_json(url)
+            except WebserviceNotFoundError:
+                return {"errors": [], "warnings": [f"Term '{term}' is not on OLS."]}
             except WebserviceError as err:
                 # prefer outdated information over none, e.g., when offline
                 if self.cache:
@@ -246,7 +268,8 @@ class OLSQuery:
             term: OLS response from `query_ols`
 
         Returns:
-            Dictionary with `label`, `description`, `synonyms` and `xrefs`.
+            Dictionary with `label`, `description`, `synonyms`, `xrefs`,
+            `ontology`, `iri` and `ols_url`.
         """
         data = {
             "errors": term["errors"],
@@ -268,10 +291,15 @@ class OLSQuery:
         synonyms = term.get("obo_synonym", [])
         xrefs = term.get("obo_xref", [])
 
+        ontology = term.get("ontology_name")
+        iri = term.get("iri")
         return {
             **data,
             "label": label,
             "description": description,
             "synonyms": synonyms,
             "xrefs": xrefs,
+            "ontology": ontology,
+            "iri": iri,
+            "ols_url": ols_term_url(ontology, iri),
         }

pymetadata-0.8.0/src/pymetadata/webservices/uniprot.py

@@ -0,0 +1,140 @@
+"""Protein information from UniProt.
+
+```python
+from pymetadata.webservices.uniprot import UniprotQuery
+
+info = UniprotQuery.query("P69905")
+```
+
+See <https://www.uniprot.org/>.
+"""
+
+import contextlib
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+import pymetadata
+from pymetadata.cache import (
+    CACHE_DURATION_ONTOLOGY,
+    cache_file,
+    read_json_cache,
+    read_json_cache_fallback,
+    write_json_cache,
+)
+from pymetadata.webservices.webservice import (
+    WebserviceError,
+    WebserviceNotFoundError,
+    get_json,
+)
+
+logger = logging.getLogger(__name__)
+
+UNIPROT_URL = "https://rest.uniprot.org/uniprotkb/{}.json"
+
+# the accession format of UniProt, with an optional isoform
+UNIPROT_PATTERN = re.compile(
+    r"^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2})(?:-\d+)?$"
+)
+
+
+def _entry_info(entry: dict[str, Any]) -> dict[str, Any]:
+    """Reduce an entry of UniProt to the information shown for an annotation."""
+    description = entry.get("proteinDescription") or {}
+    names = description.get("recommendedName") or next(
+        iter(description.get("submissionNames") or []), {}
+    )
+    function = next(
+        (
+            comment["texts"][0].get("value")
+            for comment in entry.get("comments") or []
+            if comment.get("commentType") == "FUNCTION" and comment.get("texts")
+        ),
+        None,
+    )
+    return {
+        "accession": entry.get("primaryAccession"),
+        "entry": entry.get("uniProtkbId"),
+        "name": (names.get("fullName") or {}).get("value"),
+        "organism": (entry.get("organism") or {}).get("scientificName"),
+        "genes": [
+            gene["geneName"]["value"]
+            for gene in entry.get("genes") or []
+            if "geneName" in gene
+        ],
+        "length": (entry.get("sequence") or {}).get("length"),
+        "function": function,
+    }
+
+
+class UniprotQuery:
+    """Queries against the UniProt web service.
+
+    Responses are cached on disk for `CACHE_DURATION_ONTOLOGY` hours, see
+    `pymetadata.CACHE_USE`. If UniProt cannot be reached, cached content is used
+    however old it is.
+    """
+
+    @staticmethod
+    def query(
+        accession: str, cache: bool | None = None, cache_path: Path | None = None
+    ) -> dict[str, Any]:
+        """Query the information of a protein.
+
+        Args:
+            accession: accession of UniProt, e.g., `P69905`
+            cache: cache the response, defaults to `pymetadata.CACHE_USE`
+            cache_path: directory for cached responses, defaults to
+                `pymetadata.CACHE_PATH`
+
+        Returns:
+            The protein information, empty if the accession is invalid, unknown
+            or inactive, or if UniProt cannot be reached and nothing is cached.
+        """
+        accession = accession.strip().upper() if accession else ""
+        if not UNIPROT_PATTERN.match(accession):
+            logger.error("Invalid UniProt accession: '%s'", accession)
+            return {}
+        if cache is None:
+            cache = pymetadata.CACHE_USE
+        if cache_path is None:
+            cache_path = pymetadata.CACHE_PATH
+
+        path = cache_file(Path(cache_path) / "uniprot", accession)
+        if cache:
+            with contextlib.suppress(OSError, ValueError):
+                # cache does not exist, is outdated or corrupt
+                data = read_json_cache(cache_path=path, max_age=CACHE_DURATION_ONTOLOGY)
+                if data:
+                    return data
+
+        try:
+            entry = get_json(UNIPROT_URL.format(accession))
+        except WebserviceNotFoundError:
+            logger.error("UniProt accession is unknown: '%s'", accession)
+            return {}
+        except WebserviceError as err:
+            # prefer outdated information over none, e.g., when offline
+            if cache:
+                fallback = read_json_cache_fallback(path, reason=str(err))
+                if fallback is not None:
+                    return fallback
+            logger.error(
+                "UniProt information could not be retrieved for '%s': %s",
+                accession,
+                err,
+            )
+            return {}
+
+        if not isinstance(entry, dict):
+            logger.error("Unexpected response of UniProt for '%s'", accession)
+            return {}
+        if entry.get("entryType") == "Inactive":
+            logger.error("UniProt entry is inactive: '%s'", accession)
+            return {}
+
+        data = _entry_info(entry)
+        if cache:
+            write_json_cache(data=data, cache_path=path)
+        return data