OLS4 client

ols_py.client

Ols4Client(base_url: str = EBI_OLS4)

Client for communicating with an OLS instance.

Parameters:

• base_url (str, default: EBI_OLS4 ) –

  Base API URL for the OLS instance, up to and including /api/

find_terms(params: schemas.requests.GetTermsParams)

Search for terms across ontologies.

Provide either iri, short_form, or obo_id

Parameters:

• params (GetTermsParams) –

  Request params. You must provide one of iri, short_form or obo_id Example requests: curl -L 'http://www.ebi.ac.uk/ols4/api/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001' -i -H 'Accept: application/json' curl -L 'http://www.ebi.ac.uk/ols4/api/terms?iri=http://www.ebi.ac.uk/efo/EFO_0000001' -i -H 'Accept: application/json' curl -L 'http://www.ebi.ac.uk/ols4/api/terms?short_form=EFO_0000001' -i -H 'Accept: application/json' curl -L 'http://www.ebi.ac.uk/ols4/api/terms?obo_id=EFO:0000001' -i -H 'Accept: application/json' curl -L 'http://www.ebi.ac.uk/ols4/api/terms?id=EFO:0000001' -i -H 'Accept: application/json'

get(path: str, params: Optional[ParamsMapping] = None) -> dict

Perform a GET request to the API. Unlike most of the client methods, this just returns the JSON data as a dict, without validation/parsing. Useful if you want to test an API endpoint, or use an endpoint that's not implemented yet.

Parameters:

• path (str) –

  API path (excluding base url)

• params (Optional[ParamsMapping], default: None ) –

  Query parameters

Returns:

• dict –

  JSON data, as a dict

Raises:

• HTTPError –

  if response is not OK

get_api_info() -> schemas.responses.ApiInfo

Get the list of endpoints supported by the API

get_individual(ontology_id: str, iri: str) -> schemas.responses.Term

Get an individual from a specific ontology.

Example request:

curl -L 'http://www.ebi.ac.uk/ols4/api/ontologies/iao/individuals/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FIAO_0000002' -i -H 'Accept: application/json'

get_ontologies(page: Optional[int] = None, size: Optional[int] = None) -> schemas.responses.OntologyList

Get the list of ontologies the OLS instance has.

Parameters:

• page (Optional[int], default: None ) –

  Page number of results (starting at 0)

• size (Optional[int], default: None ) –

  Number of results per page (API default is 20)

get_ontology(ontology_id: str) -> schemas.responses.OntologyItem

Get details for a single ontology

Parameters:

• ontology_id (str) –

  Ontology ID/name, e.g. "mondo"

get_property(ontology_id: str, iri: str) -> schemas.responses.Term

Get a property from a specific ontology.

Example request:

curl -L 'http://www.ebi.ac.uk/ols4/api/ontologies/efo/properties/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FBFO_0000050' -i -H 'Accept: application/json'

get_related_term_by_property(ontology_id: str, term_iri: str, property_iri: str)

Use the /ontologies/{ontology_id}/terms/{term_iri}/{property_iri} endpoint to find related terms.

From the OLS4 docs: In cases where a term has a direct relation to another term (single existential to a named class in OBO), for example a "part of" relation, the related terms can be accessed directly with this API.

Example request:

http://www.ebi.ac.uk/ols4/api/ontologies/uberon/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FUBERON_0000016/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FBFO_0000050

get_term(ontology_id: str, iri: str) -> schemas.responses.Term

Get a single term in a specific ontology

Parameters:

• ontology_id (str) –

  Ontology ID/name, e.g. "mondo"

• iri (str) –

  IRI for a single term

Returns:

• Term –

  Term details

get_term_ancestors(ontology_id: str, term_id: str, params: Optional[GetTermRelativesParams] = None) -> schemas.responses.MultipleTerms

Get ancestors for a term. See [get_term_parents()][ols_py.client.OlsClient.get_term_parents]

get_term_children(ontology_id: str, term_id: str, params: Optional[GetTermRelativesParams] = None) -> schemas.responses.MultipleTerms

Get children for a term. See [get_term_parents()][ols_py.client.OlsClient.get_term_parents]

get_term_descendants(ontology_id: str, term_id: str, params: Optional[GetTermRelativesParams] = None) -> schemas.responses.MultipleTerms

Get descendants for a term. See [get_term_parents()][ols_py.client.OlsClient.get_term_parents]

get_term_hierarchical_ancestors(ontology_id: str, term_id: str, params: Optional[GetTermRelativesParams] = None) -> schemas.responses.MultipleTerms

Get hierarchical ancestors for a term. See [get_term_parents()][ols_py.client.OlsClient.get_term_parents]

get_term_hierarchical_descendants(ontology_id: str, term_id: str, params: Optional[GetTermRelativesParams] = None) -> schemas.responses.MultipleTerms

Get hierarchical descendants for a term. See [get_term_parents()][ols_py.client.OlsClient.get_term_parents]

get_term_hierarchical_parents(ontology_id: str, term_id: str, params: Optional[GetTermRelativesParams] = None) -> schemas.responses.MultipleTerms

Get hierarchical parents for a term. See [get_term_parents()][ols_py.client.OlsClient.get_term_parents]

get_term_in_defining_ontology(iri: Optional[str] = None, params: Optional[schemas.requests.TermInDefiningOntologyParams] = None) -> schemas.responses.TermInDefiningOntology

Use the /terms/findByIdAndIsDefiningOntology/ to find a term in its defining ontology. This allows you to look up a term by IRI alone.

Parameters:

• iri (Optional[str], default: None ) –

  IRI for the term. You can either provide this, or use the params argument (not both).

• params (Optional[TermInDefiningOntologyParams], default: None ) –

  GET parameters. the /findByIdAndIsDefiningOntology/ endpoint allows "iri", "short_form", "obo_id", or "id"

Returns:

• TermInDefiningOntology –

  JSON data. Terms are at resp.embedded.terms

Raises:

• ValueError –

  if both/neither IRI and params arguments were given.

get_term_parents(ontology_id: str, term_id: str, params: Optional[GetTermRelativesParams] = None) -> schemas.responses.MultipleTerms

Get parents for a term.

Parameters:

• ontology_id (str) –

  Name of ontology, e.g. "go"

• term_id (str) –

  Term ID (URI, short form or obo ID)

• params (Optional[GetTermRelativesParams], default: None ) –

  optional pagination params, page and size. Default size is 20 items

Returns:

• MultipleTerms –

  response object. the actual terms are in a list at response.embedded.terms

get_terms(ontology_id: str, params: Optional[schemas.requests.GetTermsParams] = None) -> schemas.responses.MultipleTerms

Get multiple terms in a specific ontology, possibly filtering by iri, short_form or obo_id.

Parameters:

• params (Optional[GetTermsParams], default: None ) –

  Optional params. Filter by iri, short_form or obo_id, or specify the number of results with page and size

get_with_schema(schema: Type[S], path: str, params: Optional[ParamsMapping] = None) -> S

Get data from path and parse it with schema to return a pydantic object.

Parameters:

• schema (Type[S]) –

  Pydantic class/model inheriting from BaseModel

• path (str) –

  API path (excluding the base API url)

• params (Optional[ParamsMapping], default: None ) –

  Query parameters

Returns:

• S –

  Pydantic model instance created from schema

Raises:

• pydantic.ValidationError –

  if response data fails to validate.

search(query: str, params: Optional[schemas.requests.SearchParams] = None, add_wildcards: bool = False) -> schemas.responses.SearchResponse

Search for query using the /search API endpoint.

Parameters:

• query (str) –

  term(s) to search for

• params (Optional[SearchParams], default: None ) –

  dictionary of search parameters

• add_wildcards (bool, default: False ) –

  Add a wildcard * to each word in query - good for broad/flexible searches

Returns:

• SearchResponse –

select(query: str, params: Optional[schemas.requests.SelectParams] = None, add_wildcards: bool = False) -> schemas.responses.SearchResponse

Search for query using the /select API endpoint, which is supposed to be tuned to return good results for autocomplete.

Parameters:

• query (str) –

  term(s) to search for

• params (Optional[SelectParams], default: None ) –

  dictionary of optional parameters

• add_wildcards (bool, default: False ) –

  Add a wildcard * to each word in query - good for broad/flexible searches

Returns:

• SearchResponse –