API Documentation

Skos module

This module contains a read-only model of the SKOS specification.

To complement the SKOS specification, some elements were borrowed from the SKOS-THES specification (eg. superordinate and subordinate array).

Added in version 0.2.0.

class skosprovider.skos.Collection(id, uri=None, concept_scheme=None, labels=None, notes=None, sources=None, members=None, member_of=None, superordinates=None, infer_concept_relations=True, extra_data=None)[source]

A SKOS Collection.

concept_scheme = None

The ConceptScheme this Collection is a part of.

extra_data: Graph | None = None

An optional RDF graph with extra data for this collection.

id = None

An id for this Collection within a vocabulary

infer_concept_relations = True

Should member concepts of this collection be seen as narrower concept of a superordinate of the collection?

label(language=None)[source]

Provide a single label for this collection.

This uses the label() function to determine which label to return.

Parameters:

language (string) – The preferred language to receive the label in. This should be a valid IANA language tag. If not specified or None, the default language of the concept_scheme will be used, falling back to any available label.

Return type:

skosprovider.skos.Label or None if no labels were found.

labels = []

A lst of skosprovider.skos.label instances.

member_of = []

A lst of collection ids.

members = []

A lst of concept or collection ids.

notes = []

A lst of skosprovider.skos.Note instances.

sources = []

A lst of skosprovider.skos.Source instances.

superordinates = []

A lst of concept ids.

type = 'collection'

The type of this concept or collection.

eg. ‘collection’

uri = None

A proper uri for this Collection

class skosprovider.skos.Concept(id, uri=None, concept_scheme=None, labels=None, notes=None, sources=None, broader=None, narrower=None, related=None, member_of=None, subordinate_arrays=None, matches=None, extra_data=None)[source]

A SKOS Concept.

broader = []

A lst of concept ids.

concept_scheme = None

The ConceptScheme this Concept is a part of.

extra_data: Graph | None = None

An optional RDF graph with extra data for this concept.

id = None

An id for this Concept within a vocabulary

eg. 12345

label(language=None)[source]

Provide a single label for this concept.

This uses the label() function to determine which label to return.

Parameters:

language (string) – The preferred language to receive the label in. This should be a valid IANA language tag or a list of language tags. If not specified or None, the default language of the concept_scheme will be used, falling back to any available label.

Return type:

skosprovider.skos.Label or None if no labels were found.

labels = []

A lst of Label instances.

matches = {}

A dictionary. Each key is a matchtype and contains a list of URI’s.

matchtypes = ['close', 'exact', 'related', 'broad', 'narrow']

Matches with Concepts in other ConceptSchemes.

This dictionary contains a key for each type of Match (close, exact, related, broad, narrow). Attached to each key is a list of URI’s.

member_of = []

A lst of collection ids.

narrower = []

A lst of concept ids.

notes = []

A lst of Note instances.

related = []

A lst of concept ids.

sources = []

A lst of skosprovider.skos.Source instances.

subordinate_arrays = []

A list of collection ids.

type = 'concept'

The type of this concept or collection.

eg. ‘concept’

uri = None

A proper uri for this Concept

eg. http://id.example.com/skos/trees/1

class skosprovider.skos.ConceptScheme(uri, labels=None, notes=None, sources=None, languages=None, default_language=None, extra_data=None)[source]

A SKOS ConceptScheme.

Parameters:
extra_data: Graph | None = None

An optional RDF graph with extra data for this conceptscheme.

label(language=None)[source]

Provide a single label for this conceptscheme.

This uses the label() function to determine which label to return.

Parameters:

language (string) – The preferred language to receive the label in. This should be a valid IANA language tag. If not specified or None, the default_language will be used, falling back to any available label.

Return type:

skosprovider.skos.Label or None if no labels were found.

labels = []

A lst of skosprovider.skos.label instances.

languages = []

A lst of languages that are being used in the ConceptScheme.

There’s no guarantuee that labels or notes in other languages do not exist.

notes = []

A lst of skosprovider.skos.Note instances.

sources = []

A lst of skosprovider.skos.Source instances.

uri = None

A URI for this conceptscheme.

class skosprovider.skos.Label(label, type='prefLabel', language='und', uri=None, label_types=None, extra_data=None)[source]

A SKOS Label.

extra_data: Graph | None = None

An optional RDF graph with extra data for this label.

static is_valid_type(type)[source]

Check if the argument is a valid SKOS label type.

Parameters:

type (string) – The type to be checked.

label = None

The label itself (eg. churches, trees, Spitfires, …)

label_types = []

Zero or more extra types for this label. These types should be URI’s that map to SKOS Concepts, adding some typing but nor formal semantics.

language = 'und'

The language the label is in (eg. en, en-US, nl, nl-BE).

type = 'prefLabel'

The type of this label (prefLabel, altLabel, hiddenLabel, ‘sortLabel’).

uri = None

A URI for this label.

valid_types = ['prefLabel', 'altLabel', 'hiddenLabel', 'sortLabel']

The valid types for a label

class skosprovider.skos.Note(note, type='note', language='und', markup=None, uri=None, extra_data=None)[source]

A SKOS Note.

extra_data: Graph | None = None

An optional RDF graph with extra data for this note.

is_literal()[source]

Returns True if this note has no URI.

is_object()[source]

Returns True if this note has a URI.

static is_valid_markup(markup)[source]

Check the argument is a valid type of markup.

Parameters:

markup (string) – The type to be checked.

static is_valid_type(type)[source]

Check if the argument is a valid SKOS note type.

Parameters:

type (string) – The type to be checked.

language = 'und'

The language the label is in (eg. en, en-US, nl, nl-BE).

markup = None

What kind of markup does the note contain?

If not None, the note should be treated as a certain type of markup. Currently only HTML is allowed.

note = None

The note itself

type = 'note'

The type of this note ( note, definition, scopeNote, …).

uri = None

A URI for this note.

valid_types = ['note', 'changeNote', 'definition', 'editorialNote', 'example', 'historyNote', 'scopeNote']

The valid types for a note.

class skosprovider.skos.Source(citation, markup=None, uri=None, extra_data=None)[source]

A Source for a concept, collection or scheme.

citation = None

A bibliographic citation for this source.

extra_data: Graph | None = None

An optional RDF graph with extra data for this source.

is_literal()[source]

Returns True if this source has no URI.

is_object()[source]

Returns True if this source has a URI.

static is_valid_markup(markup)[source]

Check the argument is a valid type of markup.

Parameters:

markup (string) – The type to be checked.

markup = None

What kind of markup does the source contain?

If not None, the source should be treated as a certain type of markup. Currently only HTML is allowed.

uri = None

A URI for this source.

skosprovider.skos.dict_to_label(dict)[source]

Transform a dict with keys label, type, language and uri into a Label.

Only the label key is mandatory. If type is not present, it will default to prefLabel. If language is not present, it will default to und.

If the argument passed is not a dict, this method just returns the argument.

skosprovider.skos.dict_to_note(dict)[source]

Transform a dict with keys note, type and language into a Note.

Only the note key is mandatory. If type is not present, it will default to note. If language is not present, it will default to und. If markup is not present it will default to None.

If the argument passed is already a Note, this method just returns the argument.

skosprovider.skos.dict_to_source(dict)[source]

Transform a dict with key ‘citation’ into a Source.

If the argument passed is already a Source, this method just returns the argument.

skosprovider.skos.filter_labels_by_language(labels, language)[source]

Filter a list of labels, leaving only labels of a certain language.

Matches the IANA language tag exactly (canonicalised via langcodes).

Changed in version 2.0.0: The broader parameter and the magic “any” value have been removed.

Parameters:
  • labels (list) – A list of Label.

  • language (str) – An IANA language string, eg. nl or nl-BE.

skosprovider.skos.find_best_label_for_type(labels, language, labeltype)[source]

Find the best label of a specific type in a given language.

Uses langcodes.closest_supported_match() to find the closest variant of the same language, e.g. nl matches nl-BE and en-AU prefers en-GB over en. Related languages such as hr and sr-Latn don’t match. Returns False if nothing matches.

Parameters:
  • labels (list) – A list of Label.

  • language (str) – An IANA language string, eg. nl or nl-BE.

  • labeltype (str) – Type of label to look for, eg. prefLabel.

skosprovider.skos.label(labels=None, language=None, sortLabel=False)[source]

Provide a label for a list of labels.

The items in the list of labels are assumed to be either instances of Label, or dicts with at least the key label in them. These will be passed to the dict_to_label() function.

Within each candidate language the function prefers a prefLabel over an altLabel (and a sortLabel over both when sortLabel=True). Hidden labels are never considered.

Language resolution:

  • Passing None (or omitting the argument) means “no preference” – any available label is returned.

  • Passing a specific IANA language tag such as en-GB will look for the closest label in the same language (see find_best_label_for_type()), e.g. en-AU prefers en-GB over en. The literal tag und behaves like any other tag and only matches labels explicitly tagged as und, i.e. labels without a language.

  • Passing a list of tags tries each in turn.

  • If no language-specific label can be found, the function falls back to returning any available label, regardless of language. If the list of labels is empty (or only contains hidden labels), None is returned.

Changed in version 2.0.0: The magic value “any” is no longer supported – pass None instead. None no longer means “labels explicitly tagged as und”; use the tag “und” for that. Language matching now picks the closest variant of the same language rather than collapsing straight to the primary language.

Changed in version 1.1: It is now possible to pass a list of languages.

Parameters:
  • labels – A list of Label (or dicts convertible to one).

  • language – The preferred language to receive the label in. This should be a valid IANA language tag, a list of such tags, or None.

  • sortLabel (boolean) – Should sortLabels be considered or not? If True, sortLabels will be preferred over prefLabels. Bear in mind that these are still language dependent. So, it’s possible to have a different sortLabel per language.

Return type:

A Label or None if no label could be found.

skosprovider.skos.pick_best_label(labels, type_order)[source]

Pick the best-typed label from a list, disregarding language.

skosprovider.skos.resolve_language(language, item)[source]

Combine an explicit language with the default language of a ConceptScheme, or of the concept scheme of a Concept or Collection.

Always returns a list so callers have a single return type to handle.

skosprovider.skos.valid_markup = [None, 'HTML']

Valid types of markup for a note or a source.

Providers module

This module provides an abstraction of controlled vocabularies.

This abstraction allows our application to work with both local and remote vocabs (be they SOAP, REST, XML-RPC or something else).

The basic idea is that we have skos providers. Each provider is an instance of a VocabularyProvider. The same class can thus be reused with different configurations to handle different vocabs. Generally speaking, every instance of a certain VocabularyProvider will deal with concepts and collections from a single conceptscheme.

class skosprovider.providers.DictionaryProvider(metadata: dict[str, ~typing.Any], concepts_and_collections: list[dict[str, ~typing.Any] | ~skosprovider.skos.Concept | ~skosprovider.skos.Collection], *, extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, **kwargs: ~typing.Any)[source]

A simple vocab provider that use a python list of dicts.

The provider expects a list with elements that are dicts that represent the concepts.

__init__(metadata: dict[str, ~typing.Any], concepts_and_collections: list[dict[str, ~typing.Any] | ~skosprovider.skos.Concept | ~skosprovider.skos.Collection], *, extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, **kwargs: ~typing.Any) → None[source]
Parameters:
  • metadata (dict) – A dictionary with keywords like language.

  • concepts_and_collections (list) – A list of dicts representing concepts and collections.

  • extra_data_loader – A callable that receives the dict of a single concept, collection, label, note or source and returns a rdflib.Graph or None. See skosprovider.extra_data for the available loaders. Defaults to ignore(). Labels, notes and sources passed as objects keep their own extra_data.

Changed in version 2.0.0: The second positional argument was renamed from list to concepts_and_collections to avoid shadowing the builtin. Callers that passed it as a keyword argument must be updated.

class skosprovider.providers.MemoryProvider(metadata, concepts_and_collections, **kwargs)[source]

A provider that keeps everything in memory.

The data is passed in the constructor of this provider as a lst of skosprovider.skos.Concept and skosprovider.skos.Collection instances.

__init__(metadata, concepts_and_collections, **kwargs)[source]
Parameters:

Changed in version 2.0.0: The second positional argument was renamed from list to concepts_and_collections to avoid shadowing the builtin. Callers that passed it as a keyword argument must be updated.

case_insensitive = True

Is searching for labels case insensitive?

By default a search for a label is done case insensitive. Older versions of this provider were case sensitive. If this behaviour is desired, this can be triggered by providing a case_insensitive keyword to the constructor.

expand(id)[source]

Expand a concept or collection to all it’s narrower concepts.

This method should recurse and also return narrower concepts of narrower concepts.

If the id passed belongs to a skosprovider.skos.Concept, the id of the concept itself should be include in the return value.

If the id passed belongs to a skosprovider.skos.Collection, the id of the collection itself must not be present in the return value In this case the return value includes all the member concepts and their narrower concepts.

Parameters:

id – A concept or collection id.

Return type:

A list of id’s or False if the concept or collection doesn’t exist.

find(query, **kwargs)[source]

Find concepts that match a certain query.

Currently query is expected to be a dict, so that complex queries can be passed. You can use this dict to search for concepts or collections with a certain label, with a certain type and for concepts that belong to a certain collection.

# Find anything that has a label of church.
provider.find({'label': 'church'})

# Find all concepts that are a part of collection 5.
provider.find({'type': 'concept', 'collection': {'id': 5})

# Find all concepts, collections or children of these
# that belong to collection 5.
provider.find({'collection': {'id': 5, 'depth': 'all'})

# Find anything that has a label of church.
# Preferentially display a label in Dutch.
provider.find({'label': 'church'}, language='nl')

# Find anything that has a match with an external concept
# Preferentially display a label in Dutch.
provider.find({
    'matches': {
        'uri': 'http://id.py.org/diff/types/of/trees/nr/1/the/larch'
    }}, language='nl')

# Find anything that has a label of lariks
# with a close match to an external concept
# Preferentially display a label in Dutch.
provider.find({
    'label': 'lariks',
    'matches': {
        'type': 'close',
        'uri': 'http://id.py.org/diff/types/of/trees/nr/1/the/larch'
    }}, language='nl')
Parameters:
  • query –

    A dict that can be used to express a query. The following keys are permitted:

    • label: Search for something with this label value. An empty label is equal to searching for all concepts.

    • type: Limit the search to certain SKOS elements. If not present or None, all is assumed:

    • collection: Search only for concepts belonging to a certain collection. This argument should be a dict with two keys:

      • id: The id of a collection. Required.

      • depth: Can be members or all. Optional. If not present, members is assumed, meaning only concepts or collections that are a direct member of the collection should be considered. When set to all, this method should return concepts and collections that are a member of the collection or are a narrower concept of a member of the collection.

    • matches: Search only for concepts having a match to a certain

      external concept. Since collections can’t have matches, this automatically excludes collections. The argument with two keys:

      • uri: The uri of the concept to match. Required.

      • type: The type of match, see matchtypes for the full list of options.

  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

Returns:

A lst of concepts and collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

get_all(**kwargs)[source]

Returns all concepts and collections in this provider.

Parameters:
  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

Returns:

A lst of concepts and collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

get_by_id(id)[source]

Get all information on a concept or collection, based on id.

Providers should assume that all id’s passed are strings. If a provider knows that internally it uses numeric identifiers, it’s up to the provider to do the typecasting. Generally, this should not be done by changing the id’s themselves (eg. from int to str), but by doing the id comparisons in a type agnostic way.

Since this method could be used to find both concepts and collections, it’s assumed that there are no id collisions between concepts and collections.

Return type:

skosprovider.skos.Concept or skosprovider.skos.Collection or False if the concept or collection is unknown to the provider.

get_by_uri(uri)[source]

Get all information on a concept or collection, based on a URI.

Return type:

skosprovider.skos.Concept or skosprovider.skos.Collection or False if the concept or collection is unknown to the provider.

get_children_display(id, **kwargs)[source]

Return a list of concepts or collections that should be displayed under this concept or collection.

Parameters:
  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

  • id (str) – A concept or collection id.

Returns:

A lst of concepts and collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

get_top_concepts(**kwargs)[source]

Returns all top-level concepts in this provider.

Top-level concepts are concepts that have no broader concepts themselves. They might have narrower concepts, but this is not mandatory.

Parameters:
  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

Returns:

A lst of concepts, NOT collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

get_top_display(**kwargs)[source]

Returns all concepts or collections that form the top-level of a display hierarchy.

As opposed to the get_top_concepts(), this method can possibly return both concepts and collections.

Parameters:
  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

Returns:

A lst of concepts and collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

class skosprovider.providers.SimpleCsvProvider(metadata: dict[str, ~typing.Any], reader: ~collections.abc.Iterable[list[str]], *, extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, label_extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, note_extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, source_extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, **kwargs: ~typing.Any)[source]

A provider that reads a simple csv format into memory.

The supported csv format looks like this: <id>,<preflabel>,<note>,<source>

This provider essentialy provides a flat list of concepts. This is commonly associated with short lookup-lists.

Added in version 0.2.0.

__init__(metadata: dict[str, ~typing.Any], reader: ~collections.abc.Iterable[list[str]], *, extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, label_extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, note_extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, source_extra_data_loader: ~collections.abc.Callable[[~typing.Any], ~rdflib.graph.Graph | None] = <function ignore>, **kwargs: ~typing.Any) → None[source]

Every extra_data loader receives the full csv row (a list) and returns a rdflib.Graph or None. They all default to ignore().

Parameters:
  • metadata – A metadata dictionary.

  • reader – A csv reader.

  • extra_data_loader – Loads the extra_data of the concept.

  • label_extra_data_loader – Loads the extra_data of the label.

  • note_extra_data_loader – Loads the extra_data of the note. Only called when the row has a note.

  • source_extra_data_loader – Loads the extra_data of the source. Only called when the row has a source.

class skosprovider.providers.VocabularyProvider(metadata, **kwargs)[source]

An interface that all vocabulary providers must follow.

__init__(metadata, **kwargs)[source]

Create a new provider and register some metadata.

Parameters:
  • uri_generator – An object that implements the skosprovider.uri.UriGenerator interface.

  • concept_scheme – A ConceptScheme. If not present, a default ConceptScheme will be created with the provider uri or a uri generated by the DefaultConceptSchemeUrnGenerator in combination with the provider id.

  • allowed_instance_scopes – A list of instance_scope keywords that can be us by the registry to check if this provider is compatible.

  • metadata (dict) –

    Metadata essential to this provider. Possible metadata:

    • id: A unique local identifier (a string or integer)

      for the vocabulary. Required.

    • uri: A unique identifier (a URI) for the vocabulary.

      Optional, but if not provided will be fetched from the conceptscheme.

    • default_language: Used to determine what language to use when

      returning labels if no language is specified. Will default to en if not specified.

    • subject: A list of subjects or tags that define what the

      provider is about or what the provider can handle. This information can then be used when querying a Registry for providers.

    • dataset: A dict detailing the dataset the

      conceptscheme and all concepts and collections are part of. Currently the contents of the dictionary are undefined except for a URI attribute that must be present.

allowed_instance_scopes = None

Indicates what instance_scopes this provider can safely accomodate. This will be checked by the registry upon registering a provider.

concept_scheme = None

The ConceptScheme this provider serves.

abstractmethod expand(id)[source]

Expand a concept or collection to all it’s narrower concepts.

This method should recurse and also return narrower concepts of narrower concepts.

If the id passed belongs to a skosprovider.skos.Concept, the id of the concept itself should be include in the return value.

If the id passed belongs to a skosprovider.skos.Collection, the id of the collection itself must not be present in the return value In this case the return value includes all the member concepts and their narrower concepts.

Parameters:

id – A concept or collection id.

Return type:

A list of id’s or False if the concept or collection doesn’t exist.

abstractmethod find(query, **kwargs) → list[SkosRef][source]

Find concepts that match a certain query.

Currently query is expected to be a dict, so that complex queries can be passed. You can use this dict to search for concepts or collections with a certain label, with a certain type and for concepts that belong to a certain collection.

# Find anything that has a label of church.
provider.find({'label': 'church'})

# Find all concepts that are a part of collection 5.
provider.find({'type': 'concept', 'collection': {'id': 5})

# Find all concepts, collections or children of these
# that belong to collection 5.
provider.find({'collection': {'id': 5, 'depth': 'all'})

# Find anything that has a label of church.
# Preferentially display a label in Dutch.
provider.find({'label': 'church'}, language='nl')

# Find anything that has a match with an external concept
# Preferentially display a label in Dutch.
provider.find({
    'matches': {
        'uri': 'http://id.py.org/diff/types/of/trees/nr/1/the/larch'
    }}, language='nl')

# Find anything that has a label of lariks
# with a close match to an external concept
# Preferentially display a label in Dutch.
provider.find({
    'label': 'lariks',
    'matches': {
        'type': 'close',
        'uri': 'http://id.py.org/diff/types/of/trees/nr/1/the/larch'
    }}, language='nl')
Parameters:
  • query –

    A dict that can be used to express a query. The following keys are permitted:

    • label: Search for something with this label value. An empty label is equal to searching for all concepts.

    • type: Limit the search to certain SKOS elements. If not present or None, all is assumed:

    • collection: Search only for concepts belonging to a certain collection. This argument should be a dict with two keys:

      • id: The id of a collection. Required.

      • depth: Can be members or all. Optional. If not present, members is assumed, meaning only concepts or collections that are a direct member of the collection should be considered. When set to all, this method should return concepts and collections that are a member of the collection or are a narrower concept of a member of the collection.

    • matches: Search only for concepts having a match to a certain

      external concept. Since collections can’t have matches, this automatically excludes collections. The argument with two keys:

      • uri: The uri of the concept to match. Required.

      • type: The type of match, see matchtypes for the full list of options.

  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

Returns:

A lst of concepts and collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

abstractmethod get_all(**kwargs) → list[SkosRef][source]

Returns all concepts and collections in this provider.

Parameters:
  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

Returns:

A lst of concepts and collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

abstractmethod get_by_id(id) → Concept | Collection | Literal[False][source]

Get all information on a concept or collection, based on id.

Providers should assume that all id’s passed are strings. If a provider knows that internally it uses numeric identifiers, it’s up to the provider to do the typecasting. Generally, this should not be done by changing the id’s themselves (eg. from int to str), but by doing the id comparisons in a type agnostic way.

Since this method could be used to find both concepts and collections, it’s assumed that there are no id collisions between concepts and collections.

Return type:

skosprovider.skos.Concept or skosprovider.skos.Collection or False if the concept or collection is unknown to the provider.

abstractmethod get_by_uri(uri) → Concept | Collection | Literal[False][source]

Get all information on a concept or collection, based on a URI.

Return type:

skosprovider.skos.Concept or skosprovider.skos.Collection or False if the concept or collection is unknown to the provider.

abstractmethod get_children_display(id, **kwargs) → list[SkosRef][source]

Return a list of concepts or collections that should be displayed under this concept or collection.

Parameters:
  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

  • id (str) – A concept or collection id.

Returns:

A lst of concepts and collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

get_metadata()[source]

Get some metadata on the provider or the vocab it represents.

Return type:

Dict.

abstractmethod get_top_concepts(**kwargs) → list[SkosRef][source]

Returns all top-level concepts in this provider.

Top-level concepts are concepts that have no broader concepts themselves. They might have narrower concepts, but this is not mandatory.

Parameters:
  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

Returns:

A lst of concepts, NOT collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

abstractmethod get_top_display(**kwargs) → list[SkosRef][source]

Returns all concepts or collections that form the top-level of a display hierarchy.

As opposed to the get_top_concepts(), this method can possibly return both concepts and collections.

Parameters:
  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

  • sort (string) – Optional. If present, it should either be id, label or sortlabel. The sortlabel option means the providers should take into account any sortLabel if present, if not it will fallback to a regular label to sort on.

  • sort_order (string) – Optional. What order to sort in: asc or desc. Defaults to asc

Returns:

A lst of concepts and collections. Each of these is a dict with the following keys:

  • id: id within the conceptscheme

  • uri: URI of the concept or collection

  • type: concept or collection

  • label: A label to represent the concept or collection. It is determined by looking at the language parameter, the default language of the provider and finally falls back to en.

get_vocabulary_id()[source]

Get a local identifier for the vocabulary.

Return type:

String or number.

get_vocabulary_uri()[source]

Get a URI for the vocabulary.

Return type:

String

uri_generator = None

The UriGenerator responsible for generating URIs for this provider.

Registry module

This module provides a registry for skos providers.

This registry helps us find providers during runtime. We can also apply some operations to all or several providers at the same time.

class skosprovider.registry.Registry(instance_scope='single', metadata=None)[source]

This registry collects all skos providers.

concept_scheme_uri_map = {}

Dictionary mapping concept scheme uri’s to vocabulary id’s.

find(query, **kwargs)[source]

Launch a query across all or a selection of providers.

# Find anything that has a label of church in any provider.
registry.find({'label': 'church'})

# Find anything that has a label of church with the BUILDINGS provider.
# Attention, this syntax was deprecated in version 0.3.0
registry.find({'label': 'church'}, providers=['BUILDINGS'])

# Find anything that has a label of church with the BUILDINGS provider.
registry.find({'label': 'church'}, providers={'ids': ['BUILDINGS']})

# Find anything that has a label of church with a provider
# marked with the subject 'architecture'.
registry.find({'label': 'church'}, providers={'subject': 'architecture'})

# Find anything that has a label of church in any provider.
# If possible, display the results with a Dutch label.
registry.find({'label': 'church'}, language='nl')

# Find anything that has a match with an external concept
# If possible, display the results with a Dutch label.
registry.find({
    'matches': {
        'uri': 'http://id.py.org/diff/types/of/trees/nr/1/the/larch'
    }}, language='nl')

# Find anything that has a label of lariks
# with a close match to an external concept
# If possible, display the results with a Dutch label.
provider.find({
    'matches': {
        'label': 'lariks',
        'type': 'close',
        'uri': 'http://id.py.org/diff/types/of/trees/nr/1/the/larch'
    }}, language='nl')
Parameters:
  • query (dict) – The query parameters that will be passed on to each find() method of the selected. providers.

  • providers (dict) – Optional. If present, it should be a dictionary. This dictionary can contain any of the keyword arguments available to the get_providers() method. The query will then only be passed to the providers confirming to these arguments.

  • language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

Returns:

a list of dict. Each dict has two keys: id and concepts.

get_all(**kwargs)[source]

Get all concepts from all providers.

# get all concepts in all providers.
registry.get_all()

# get all concepts in all providers.
# If possible, display the results with a Dutch label.
registry.get_all(language='nl')
Parameters:

language (string) – Optional. If present, it should be a language-tag. This language-tag is passed on to the underlying providers and used when selecting the label to display for each concept.

Returns:

a list of dict. Each dict has two keys: id and concepts.

get_by_uri(uri)[source]

Get a concept or collection by its uri.

Returns a single concept or collection if one exists with this uri. Returns False otherwise.

Parameters:

uri (string) – The uri to find a concept or collection for.

Raises:

ValueError – The uri is invalid.

Return type:

skosprovider.skos.Concept or skosprovider.skos.Collection

get_metadata()[source]

Get some metadata on the registry it represents.

Return type:

Dict.

get_provider(id)[source]

Get a provider by id or URI.

Parameters:

id (str) – The identifier for the provider. This can either be the id with which it was registered or the URI of the conceptscheme that the provider services.

Returns:

A skosprovider.providers.VocabularyProvider or False if the id or uri is unknown.

get_providers(**kwargs)[source]

Get all providers registered.

If keyword ids is present, get only the providers with these ids.

If keys subject is present, get only the providers that have this subject.

# Get all providers with subject 'biology'
registry.get_providers(subject='biology')

# Get all providers with id 1 or 2
registry.get_providers(ids=[1,2])

# Get all providers with id 1 or 2 and subject 'biology'
registry.get_providers(ids=[1,2], subject='biology']
Parameters:
  • ids (list) – Only return providers with one of the Ids or URIs.

  • subject (str) – Only return providers with this subject.

Returns:

A list of providers

instance_scope = 'single'
Indicates how the registry is being used. Options:
  • single: The registry is part of a script or a single process. It can be assumed to be operational for the entire duration of the process and there are no threads involved.

  • threaded_global: The registry is part of a program that uses threads, such as a typical web application. It’s attached to the global process and duplicated to threads, making it not thread safe. Proceed carefully with certain providers. Should generally only be used with applications that only use read-only providers that load all data in memory at startup and use no database connections or other kinds of sessions.

  • threaded_thread: The registry is part of a program that uses threads, such as a typical web application. It’s attached to a thread, such as a web request. The registry is instantiated for this thread/request and dies with this thread/request. This is needed for providers such as the SQLAlchemyProvider. Providers that use database connections or other session handling code generally require this.

metadata = {}

Dictionary containing metadata about this registry.

providers = {}

Dictionary containing all providers, keyed by id.

register_provider(provider)[source]

Register a skosprovider.providers.VocabularyProvider.

Parameters:

provider (skosprovider.providers.VocabularyProvider) – The provider to register.

Raises:

RegistryException – A provider with this id or uri has already been registered.

remove_provider(id)[source]

Remove the provider with the given id or URI.

Parameters:

id (str) – The identifier for the provider.

Returns:

A skosprovider.providers.VocabularyProvider or False if the id is unknown.

exception skosprovider.registry.RegistryException[source]

Uri module

This module provides utilities for working with URIs.

Added in version 0.3.0.

class skosprovider.uri.DefaultConceptSchemeUrnGenerator[source]

Generate a URN for a conceptscheme specific to skosprovider.

Used for generating default URIs for providers that do not have an explicit conceptscheme.

generate(**kwargs)[source]

Generate a URI based on parameters passed.

Parameters:

id – The id of the conceptscheme.

Return type:

string

class skosprovider.uri.DefaultUrnGenerator(vocabulary_id)[source]

Generate a URN specific to skosprovider.

Used for providers that do not implement a specific UriGenerator.

Parameters:

vocabulary_id – An identifier for the vocabulary we’re generating URIs for.

generate(**kwargs)[source]

Generate a URI based on parameters passed.

Parameters:

id – The id of the concept or collection.

Return type:

string

class skosprovider.uri.TypedUrnGenerator(vocabulary_id)[source]

Generate a URN specific to skosprovider that contains a type.

Parameters:

vocabulary_id – An identifier for the vocabulary we’re generating URIs for.

generate(**kwargs)[source]

Generate a URI based on parameters passed.

Parameters:
  • id – The id of the concept or collection.

  • type – What we’re generating a URI for: concept or collection.

Return type:

string

class skosprovider.uri.UriGenerator[source]

An abstract class for generating URIs.

abstractmethod generate(**kwargs)[source]

Generate a URI based on parameters passed.

class skosprovider.uri.UriPatternGenerator(pattern: str)[source]

Generate a URI based on a simple pattern.

generate(**kwargs)[source]

Generate a URI based on parameters passed.

Parameters:

id – The id of the concept or collection.

Return type:

string

skosprovider.uri.is_uri(uri)[source]

Check if a string is a valid URI according to rfc3987

Parameters:

uri (string)

Return type:

boolean

JsonLd module

This module contains functions dealing with jsonld reading and writing.

The extra_data of an object is merged into the dict of that object. Only the node with the uri of the object is merged, with the nodes it refers to embedded. Other nodes in the extra_data have no place in the dict and are dropped, so unlike an RDF dump, a JSON-LD dump can lose part of the extra_data.

Added in version 0.7.0.

Extra data module

Loaders and dumpers for the extra_data of skos objects.

In the skos model, extra_data is always a rdflib.Graph or None.

A loader receives the input of a single object (eg. the dict of a concept, label, note or source passed to a DictionaryProvider) and returns a rdflib.Graph or None.

A dumper receives a skos object and returns a dict that is merged into the dump of that object, or None.

The loaders from_turtle(), from_jsonld() and from_graph() read the extra_data key, the dumpers to_turtle(), to_jsonld() and to_graph() write it. ignore() can be used as both a loader and a dumper and is the default everywhere.

skosprovider.extra_data.dump_extra_data(dumper: Callable[[Concept | Collection | Label | Note | Source], dict[str, Any] | None], obj: Concept | Collection | Label | Note | Source) → dict[str, Any][source]

Call a dumper and wrap any error in an ExtraDataException.

Use extra_data_context() to describe which object was being dumped.

Returns:

A dict, empty when the dumper returned None.

skosprovider.extra_data.exception_context(description: str) → Iterator[None][source]

Describe which object is being processed when an ExtraDataException passes through.

The description is added as a note (PEP 678) to the exception. Nested contexts add one note each, innermost first.

Parameters:

description – Describes the object, eg. concept ‘1’.

skosprovider.extra_data.from_graph(data: dict[str, Any]) → Graph | None[source]

Pass a rdflib.Graph under extra_data through unchanged.

Returns:

The graph, or None when extra_data is missing.

skosprovider.extra_data.from_jsonld(data: dict[str, Any]) → Graph | None[source]

Load a JSON-LD dict under extra_data into a rdflib.Graph.

The dict is expected to contain its own @context. Both compact and expanded JSON-LD are supported.

Returns:

A graph, or None when extra_data is missing or None.

skosprovider.extra_data.from_turtle(data: dict[str, Any]) → Graph | None[source]

Load a turtle string under extra_data into a rdflib.Graph.

Returns:

A graph, or None when extra_data is missing or None.

skosprovider.extra_data.ignore(*_: object) → None[source]

An extra_data loader or dumper that ignores all extra_data.

Returns:

Always None.

skosprovider.extra_data.load_extra_data(loader: Callable[[Any], Graph | None], data: Any) → Graph | None[source]

Call a loader and wrap any error in an ExtraDataException.

Use extra_data_context() to describe which object was being loaded.

Returns:

A rdflib.Graph or None.

skosprovider.extra_data.to_graph(obj: Concept | Collection | Label | Note | Source) → dict[str, Graph] | None[source]

Dump the extra_data of a skos object unchanged under extra_data.

Returns:

A dict, or None when the object has no extra_data.

skosprovider.extra_data.to_jsonld(obj: Concept | Collection | Label | Note | Source) → dict[str, Any] | None[source]

Dump the extra_data of a skos object as a compact JSON-LD dict under extra_data.

The context is built from the namespace bindings of the graph, limited to the namespaces that are used by an IRI or datatype in the graph.

Returns:

A dict, or None when the object has no extra_data.

skosprovider.extra_data.to_turtle(obj: Concept | Collection | Label | Note | Source) → dict[str, str] | None[source]

Dump the extra_data of a skos object as a turtle string under extra_data.

Returns:

A dict, or None when the object has no extra_data.

Exceptions module

This module provides custom exceptions for skos providers.

Added in version 0.5.0.

exception skosprovider.exceptions.ConceptSchemeException[source]

Raised when a provider can not determine which conceptscheme to use.

Extends RuntimeError for backwards compatibility.

exception skosprovider.exceptions.ExtraDataException(message: str)[source]

Raised when loading or dumping the extra_data of a skos object fails.

The original error is available as __cause__.

exception skosprovider.exceptions.InvalidDataException[source]

Raised when data passed to skosprovider is not valid.

Extends ValueError for backwards compatibility.

exception skosprovider.exceptions.NotFoundException[source]

Raised when a concept or collection could not be found.

exception skosprovider.exceptions.ProviderUnavailableException(message)[source]

This exception can be raised by a provider if it’s unable to provide the thesaurus. This can occur when an underlying resource is unavailable (database connection, webservice, …). The message should contain some more information about the problem.

exception skosprovider.exceptions.SkosproviderException[source]

Base class for all exceptions raised by skosprovider.

Utils module

This module contains utility functions for dealing with skos providers.

skosprovider.utils.add_lang_to_html(htmltext, lang)[source]

Wrap a piece of HTML in a <div> carrying an xml:lang attribute.

If htmltext already consists of a single root <div>, the xml:lang attribute is merged into that existing element instead of adding another wrapper. This keeps the function idempotent under export/import round-trips where an importer may strip xml:lang but leave the wrapping div behind.

Added in version 0.7.0.

skosprovider.utils.dict_dumper(provider: ~skosprovider.providers.VocabularyProvider, extra_data_dumper: ~collections.abc.Callable[[~skosprovider.skos.Concept | ~skosprovider.skos.Collection | ~skosprovider.skos.Label | ~skosprovider.skos.Note | ~skosprovider.skos.Source], dict[str, ~typing.Any] | None] = <function ignore>) → list[dict[str, Any]][source]

Dump a provider to a format that can be passed to a skosprovider.providers.DictionaryProvider.

Parameters:
  • provider (skosprovider.providers.VocabularyProvider) – The provider that wil be turned into a dict.

  • extra_data_dumper – A callable that receives a concept, collection, label, note or source and returns a dict or None. The dict is merged into the dump of that object and overwrites keys that already exist. See skosprovider.extra_data for the available dumpers. Defaults to ignore().

Return type:

A list of dicts.

Added in version 0.2.0.

skosprovider.utils.extract_language(lang)[source]

Turn a language in our domain model into a IANA tag.

Added in version 0.7.0.

RDF Providers module

This module contains an RDFProvider, an implementation of the skosprovider.providers.VocabularyProvider interface that uses a rdflib.graph.Graph as input.

class skosprovider.rdf.providers.RDFProvider(metadata: dict[str, ~typing.Any], graph: ~rdflib.graph.Graph, *, extra_data_loader: ~collections.abc.Callable[[~rdflib.graph.Graph, ~rdflib.term.Node], ~rdflib.graph.Graph | None] = <function ignore>, **kwargs: ~typing.Any)[source]

A simple vocabulary provider that use an rdflib.graph.Graph as input. The provider expects a RDF graph with elements that represent the SKOS concepts and collections.

Please be aware that this provider needs to load the entire graph in memory.

When a concept scheme is passed or picked with concept_scheme_uri, check_in_scheme is set and the provider only takes concepts and collections into account that are explicitly linked to that concept scheme.

__init__(metadata: dict[str, ~typing.Any], graph: ~rdflib.graph.Graph, *, extra_data_loader: ~collections.abc.Callable[[~rdflib.graph.Graph, ~rdflib.term.Node], ~rdflib.graph.Graph | None] = <function ignore>, **kwargs: ~typing.Any) → None[source]
Parameters:

extra_data_loader – A callable that receives the graph and the node of a single concept scheme, concept or collection, or of a source, SKOS-XL label or note with a uri, and returns a rdflib.Graph or None. A source, label or note that is a blank node gets no extra_data. Defaults to ignore(). A concept scheme passed as concept_scheme keeps its own extra_data.

to_text(data: Any) → str[source]

Convert data of binary type or literal type to text.

Parameters:

data – The data to convert.

Returns:

text representation of the data

RDF Dumper module

This module dumps skos providers to an RDF graph.

skosprovider.rdf.dumper.rdf_concept_or_collection_dumper(provider: ~skosprovider.providers.VocabularyProvider, id_: str | int, *, extra_data_dumper: ~collections.abc.Callable[[~skosprovider.skos.Concept | ~skosprovider.skos.Collection | ~skosprovider.skos.Label | ~skosprovider.skos.Note | ~skosprovider.skos.Source | ~skosprovider.skos.ConceptScheme], ~rdflib.graph.Graph | None] = <function ignore>) → Graph[source]

Dump one concept or collection from a provider to a format that can be passed to a skosprovider.rdf.providers.RDFProvider.

Parameters:
Raises:

skosprovider.exceptions.NotFoundException – If the provider has no concept or collection with this id.

Return type:

rdflib.graph.Graph

skosprovider.rdf.dumper.rdf_conceptscheme_dumper(provider: ~skosprovider.providers.VocabularyProvider, *, extra_data_dumper: ~collections.abc.Callable[[~skosprovider.skos.Concept | ~skosprovider.skos.Collection | ~skosprovider.skos.Label | ~skosprovider.skos.Note | ~skosprovider.skos.Source | ~skosprovider.skos.ConceptScheme], ~rdflib.graph.Graph | None] = <function ignore>) → Graph[source]

Dump all information of the conceptscheme of a provider to a format that can be passed to a skosprovider.rdf.providers.RDFProvider.

Parameters:
Return type:

rdflib.graph.Graph

skosprovider.rdf.dumper.rdf_dumper(provider: ~skosprovider.providers.VocabularyProvider, *, extra_data_dumper: ~collections.abc.Callable[[~skosprovider.skos.Concept | ~skosprovider.skos.Collection | ~skosprovider.skos.Label | ~skosprovider.skos.Note | ~skosprovider.skos.Source | ~skosprovider.skos.ConceptScheme], ~rdflib.graph.Graph | None] = <function ignore>) → Graph[source]

Dump a provider to a format that can be passed to a skosprovider.rdf.providers.RDFProvider.

Parameters:
  • provider (skosprovider.providers.VocabularyProvider) – The provider that wil be turned into an rdflib.graph.Graph.

  • extra_data_dumper – A callable that receives the concept scheme, a concept or collection, or a source, label or note with a uri, and returns a rdflib.Graph or None. The graph is merged into the dump. A label with a uri is dumped as a SKOS-XL label, a note with a uri as a node with the text under rdf:value. The extra_data of a source, label or note without a uri is not dumped. Defaults to ignore().

Return type:

rdflib.graph.Graph