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:
- concept: Only return
skosprovider.skos.Concept
instances. - collection: Only return
skosprovider.skos.Collection
instances. - all: Return both
skosprovider.skos.Concept
andskosprovider.skos.Collection
instances.
- concept: Only return
- 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.
- query –
-
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
orskosprovider.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
orskosprovider.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.
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.
-
class
skosprovider_sqlalchemy.models.
Label
(label, labeltype_id='prefLabel', language_id=None)[source]¶ A label for a
Concept
,Collection
orConceptScheme
.
-
class
skosprovider_sqlalchemy.models.
LabelType
(name, description)[source]¶ A labelType according to skos.
-
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
orConceptScheme
.
-
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
andCollection
.
-
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 onskosprovider_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.- labels (list) – A list of
Listener that ensures related concepts have a bidirectional relationship.
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.
-
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
- provider – The