API Documentation¶

Skos module¶

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

New in version 0.2.0.

class skosprovider.skos.Collection(id, uri=None, labels=, []members=, []member_of=[])[source]¶

A SKOS Collection.

id = None¶: An id for this Collection within a vocabulary

label(language=u'any')[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.µ
Return type:	`skosprovider.skos.Label` or False if no labels was found.

labels = []¶: A lst of skosprovider.skos.label instances.

member_of = []¶: A lst of concept or collection ids.

members = []¶: A lst of concept ids.

type = u'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, labels=, []notes=, []broader=, []narrower=, []related=, []member_of=[])[source]¶

A SKOS Concept.

id = None¶

An id for this Concept within a vocabulary

eg. 12345

label(language=u'any')[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.
Return type:	`skosprovider.skos.Label` or False if no labels was found.

type = u'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=[])[source]¶

A SKOS ConceptScheme.

Parameters:	uri (string) – A URI for this conceptscheme. labels (list) – A list of `skosprovider.skos.Label` instances.

label(language=u'any')[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.
Return type:	`skosprovider.skos.Label` or False if no labels was found.

labels = []¶: A list of labels for this conceptscheme.

uri = None¶: A URI for this conceptscheme.

class skosprovider.skos.Label(label, type=u'prefLabel', language=None)[source]¶

A SKOS 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, ...)

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

type = u'prefLabel'¶: The type of this label ( prefLabel, altLabel, hiddenLabel).

valid_types = [u'prefLabel', u'altLabel', u'hiddenLabel']¶: The valid types for a label

class skosprovider.skos.Note(note, type=u'note', language=None)[source]¶

A SKOS Note.

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 = None¶: The language the label is in (eg. en, en-US, nl, nl-BE).

note = None¶: The note itself

type = u'note'¶: The type of this note ( note, definition, scopeNote, ...).

valid_types = [u'note', u'changeNote', u'definition', u'editorialNote', u'example', u'historyNote', u'scopeNote']¶: The valid types for a note

skosprovider.skos.dict_to_label(dict)[source]¶

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

If the argument passed is already a Label, 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.

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

skosprovider.skos.label(labels=, []language=u'any')[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.

This method tries to find a label by looking if there’s a pref label for the specified language. If there’s no pref label, it looks for an alt label. It disregards hidden labels.

If language ‘any’ was specified, all labels will be considered, regardless of language.

To find a label without a specified language, pass None as language.

If a language or None was specified, and no label could be found, this method will automatically try to find a label in some other language.

Finally, if no label could be found, None is returned.

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.

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

An interface that all vocabulary providers must follow.

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.

expand_concept(id)[source]¶

Expand a concept to the concept itself and all it’s narrower concepts.

Deprecated since version 0.2.0: This method has been deprecated, please use expand().

Parameters:	id – A concept id.
Return type:	A list of id’s or False if the concept 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'})

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 all is assumed:
- concept: Only return skosprovider.skos.Concept instances.
- collection: Only return skosprovider.skos.Collection instances.
- all: Return both skosprovider.skos.Concept and skosprovider.skos.Collection instances.
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.

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 **kwargs 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.

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 **kwargs 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:	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 **kwargs 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.

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.

Returns:	A `lst` of concepts, NOTcollections. 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 **kwargs 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.

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 **kwargs parameter, the default language of the provider and finally falls back to en.

get_vocabulary_id()[source]¶

Get an identifier for the vocabulary.

Return type:	String or number.

class skosprovider.providers.MemoryProvider(metadata, list, **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.

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.

class skosprovider.providers.DictionaryProvider(metadata, list, **kwargs)[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.

class skosprovider.providers.SimpleCsvProvider(metadata, reader, **kwargs)[source]¶

A provider that reads a simple csv format into memory.

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

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

New in version 0.2.0.

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[source]¶

This registry collects all skos providers.

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 the BUILDINGS provider.
registry.find({'label': 'church'}, providers=['BUILIDINGS'])

Parameters:	providers (list) – Optional. If present, it should be a list of skosprovider id’s. The query will then only be passed to these providers. query (dict) – The query parameters that will be passed on to each `find()` method of the selected. `providers`.
Returns:	a list of `dict`. Each dict has two keys: id and concepts.

get_all()[source]¶

Get all concepts from all providers.

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.
Return type:	`skosprovider.skos.Concept` or `skosprovider.skos.Collection`

get_provider(id)[source]¶

Get a provider by id.

Parameters:	id (str) – The identifier for the provider.
Returns:	A `skosprovider.providers.VocabularyProvider` or False if the id is unknown.

get_providers(**kwargs)[source]¶

Get all providers registered.

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

register_provider(provider)[source]¶

Register a skosprovider.providers.VocabularyProvider.

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

remove_provider(id)[source]¶

Remove the provider with the given id.

Parameters:	id (str) – The identifier for the provider.
Returns:	A `skosprovider.providers.VocabularyProvider` or False if the id is unknown.

Uri module¶

This module provides utilities for working with URIS.

New in version 0.3.0.

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.

generate(**kwargs)[source]¶: Generate a URI based on parameters passed.

class skosprovider.uri.UriPatternGenerator(pattern)[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

Utils module¶

This module contains utility functions for dealing with skos providers.

skosprovider.utils.dict_dumper(provider)[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.
Return type:	A list of dicts.

New in version 0.2.0.