API Documentation

Providers module

class skosprovider_sqlalchemy.providers.SQLAlchemyProvider(metadata, session, **kwargs)[source]

A skosprovider.providers.VocabularyProvider that uses SQLAlchemy as backend.

expand(concept_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.
expand_strategy = 'recurse'

Determines how the expand method will operate. Options are:

  • recurse: Determine all narrower concepts by recursivly querying the database. Can take a long time for concepts that are at the top of a large hierarchy.
  • visit: Query the database’s Visitation table. This table contains a nested set representation of each conceptscheme. Actually creating the data in this table needs to be scheduled.
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.python.org/different/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.python.org/different/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(concept_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.

This method will only find concepts or collections whose URI is actually stored in the database. It will not find anything that has no URI in the database, but does have a matching URI after generation.

Return type:skosprovider.skos.Concept or skosprovider.skos.Collection or False if the concept or collection is unknown to the provider.
get_children_display(thing_id, **kwargs)[source]

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

Parameters:thing_id – A concept or collection id.
Return type:A list of concepts and collections. For each an id is present and a label. The label is determined by looking at the **kwargs parameter, the default language of the provider and falls back to en if nothing is present. If the id does not exist, return False.
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.

Return type:Returns a list of concepts and collections. For each an id is present and a label. The label is determined by looking at the **kwargs parameter, the default language of the provider and falls back to en if nothing is present.

Models module

class skosprovider_sqlalchemy.models.Collection(**kwargs)[source]

A collection as know by skos.

class skosprovider_sqlalchemy.models.Concept(**kwargs)[source]

A concept as know by skos.

class skosprovider_sqlalchemy.models.ConceptScheme(**kwargs)[source]

A skos conceptscheme.

class skosprovider_sqlalchemy.models.Initialiser(session)[source]

Initialises a database.

Adds necessary values for labelType, noteType and language to the database.

The list of languages added by default is very small and will probably need to be expanded for your local needs.

init_all()[source]

Initialise all objects (labeltype, notetype, language).

init_labeltype()[source]

Initialise the labeltypes.

init_languages()[source]

Initialise the languages.

Only adds a small set of languages. Will probably not be sufficient for most use cases.

init_matchtypes()[source]

Initialise the matchtypes.

init_notetype()[source]

Initialise the notetypes.

class skosprovider_sqlalchemy.models.Label(label, labeltype_id='prefLabel', language_id=None)[source]

A label for a Concept, Collection or ConceptScheme.

class skosprovider_sqlalchemy.models.LabelType(name, description)[source]

A labelType according to skos.

class skosprovider_sqlalchemy.models.Language(id, name)[source]

A Language.

class skosprovider_sqlalchemy.models.Match(**kwargs)[source]

A match between a Concept in one ConceptScheme and those in another one.

class skosprovider_sqlalchemy.models.MatchType(name, description)[source]

A matchType according to skos.

class skosprovider_sqlalchemy.models.Note(note, notetype_id, language_id, markup=None)[source]

A note for a Concept, Collection or ConceptScheme.

class skosprovider_sqlalchemy.models.NoteType(name, description)[source]

A noteType according to skos.

class skosprovider_sqlalchemy.models.Source(citation, markup=None)[source]

The source where a certain piece of information came from.

class skosprovider_sqlalchemy.models.Thing(**kwargs)[source]

Abstract class for both Concept and Collection.

class skosprovider_sqlalchemy.models.Visitation(**kwargs)[source]

Holds several nested sets.

The visitation object and table hold several nested sets. Each skosprovider_sqlalchemy.models.Visitation holds the positional information for one conceptplacement in a certain nested set.

Each conceptscheme gets its own separate nested set.

skosprovider_sqlalchemy.models.label(labels=[], language='any', sortLabel=False)[source]

Provide a label for a list of labels.

Deprecated since version 0.5.0: Please use skosprovider.skos.label(). Starting with skosprovider 0.6.0, the function can function on skosprovider_sqlalchemy.models.Label instances as well.

Parameters:
  • labels (list) – A list of labels.
  • language (str) – The language for which a label should preferentially be returned. This should be a valid IANA language tag.
  • 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_sqlalchemy.models.related_concepts_append_listener(target, value, initiator)[source]

Listener that ensures related concepts have a bidirectional relationship.

skosprovider_sqlalchemy.models.related_concepts_remove_listener(target, value, initiator)[source]

Listener to remove a related concept from both ends of the relationship.

Utils module

class skosprovider_sqlalchemy.utils.VisitationCalculator(session)[source]

Generates a nested set for a conceptscheme.

visit(conceptscheme)[source]

Visit a skosprovider_sqlalchemy.models.Conceptscheme and calculate a nested set representation.

Parameters:conceptscheme – A skosprovider_sqlalchemy.models.Conceptscheme for which the nested set will be calculated.
skosprovider_sqlalchemy.utils.import_provider(provider: skosprovider.providers.VocabularyProvider, session: sqlalchemy.orm.session.Session, conceptscheme: skosprovider_sqlalchemy.models.ConceptScheme = None) → skosprovider_sqlalchemy.models.ConceptScheme[source]

Import a provider into a SQLAlchemy database.

Parameters:
  • provider – The skosprovider.providers.VocabularyProvider to import. Since the SQLAlchemy backend uses integers as keys, this backend should have id values that can be cast to int.
  • conceptscheme – A skosprovider_sqlalchemy.models.Conceptscheme to import the provider into. This should be an empty scheme so that there are no possible id clashes. If no conceptscheme is provided, one will be created.
  • session – A sqlalchemy.orm.session.Session.
Returns:

The conceptscheme that holds the concepts and collections. Either the same conceptscheme that was passed into the provider, or the one that was created by this function.

Return type:

skosprovider_sqlalchemy.models.Conceptscheme