PrefixCommons Python API

Common errors

• ModuleNotFoundError: No module named 'prefixcommons.curie_util'

  cause Attempting to import core utility functions directly from the top-level `prefixcommons` package instead of their specific submodule `curie_util`.
  fix Change your import statement from `from prefixcommons import expand_uri` (or similar) to `from prefixcommons.curie_util import expand_uri, contract_uri`.

• KeyError: 'UNKNOWN_PREFIX'

  cause The CURIE prefix (e.g., 'MYAPP' in 'MYAPP:123') is not found in the currently active prefix map when attempting to expand or contract a URI.
  fix Ensure that the `prefix_map` supplied to `expand_uri` or `contract_uri` (or the default map being used) contains the required prefix. You can load specific contexts using `prefixcommons.curie_util.read_biocontext()` or pass a custom dictionary: `expand_uri('MYAPP:123', prefix_map={'MYAPP': 'http://example.com/myapp/'})`.

Warnings

• gotcha The default prefix map, loaded internally from `resources/prefixcommons.jsonld`, may not be exhaustive for all domains or may become stale over time. For robust applications, relying solely on this default map for critical or very specific prefixes is not recommended.
  Fix: Consider explicitly loading domain-specific context maps using functions like `prefixcommons.curie_util.read_biocontext()` or provide your own custom `prefix_map` dictionary to functions like `expand_uri` and `contract_uri`.
• gotcha PrefixCommons has an infrequent release cadence, often tied to specific project needs. While stable, this means that updates to its default prefix maps for very new or niche identifiers might not be as frequent as external data sources.
  Fix: For applications requiring the absolute latest or highly specialized prefix definitions, it is advisable to rely on custom-maintained prefix maps or external services rather than solely on the library's built-in defaults. Monitor the GitHub repository for updates.

Install

• pip install prefixcommons Install latest version

Imports

• expand_uri
  wrong:

  from prefixcommons import expand_uri

  correct:

  from prefixcommons.curie_util import expand_uri

  Core utility functions like expand_uri and contract_uri reside in the `curie_util` submodule, not directly under the top-level package.
• contract_uri
  wrong:

  from prefixcommons import contract_uri

  correct:

  from prefixcommons.curie_util import contract_uri

  Core utility functions like expand_uri and contract_uri reside in the `curie_util` submodule, not directly under the top-level package.
• read_biocontext

  from prefixcommons.curie_util import read_biocontext

  Helper function to load a common set of biomedical prefixes.

Quickstart

This quickstart demonstrates how to expand and contract CURIEs using the default prefix map provided by the library, as well as how to supply a custom prefix map or load a pre-defined biomedical context map for more specific use cases.

from prefixcommons.curie_util import expand_uri, contract_uri, read_biocontext

# Using the default prefix map
expanded_go = expand_uri('GO:0008150')
print(f"Expanded GO: {expanded_go}")

contracted_go = contract_uri('http://purl.obolibrary.org/obo/GO_0008150')
print(f"Contracted GO: {contracted_go}\n")

# Using a custom prefix map
custom_map = {'EXAMPLE': 'http://example.org/myterms/'}
expanded_custom = expand_uri('EXAMPLE:001', prefix_map=custom_map)
print(f"Expanded custom: {expanded_custom}")

# Loading a biomedical context map
bio_context = read_biocontext()
expanded_ncbi = expand_uri('NCBIGENE:12345', prefix_map=bio_context)
print(f"Expanded NCBIGENE from bio_context: {expanded_ncbi}")