Introduction

This library offers an implementation of the skosprovider.providers.VocabularyProvider interface against an Atramhasis backend. This allows you to use an Atramhasis instance as a central SKOS repository that can easily be called by other applications. Either through using this Skosprovider, or by using the services provided by Atramhasis directly.

While this library works with Atramhasis, the services that Atramhasis exposes are in fact provided by pyramid_skosprovider. So, if you’re not using Atramhasis, but do have a backend that implements the services offered by pyramid_skosprovider, you can use skosprovider_atramhasis as well.

Finally, if you have a backend that does not implement pyramid_skosprovider, but implements exactly the same services, you could use that as well.

Installation

To be able to use this library you need to have a modern version of Python installed. Currently we’re supporting the last 3 versions of Python 3.

This easiest way to install this library is through pip or easy install:

$ pip install skosprovider_atramhasis

This will download and install skosprovider_atramhasis and a few libraries it depends on.

Using the providers

For demonstration purposes of AtramhasisProvider, the following examples use the Flanders Heritage thesauri hosted at it’s own thesaurus website. You can adapt the examples with your own instance of Atramhasis, by changing the base_url and scheme_id.

Using AtramhasisProvider

The AtramhasisProvider is a general provider for the Atramhasis vocabularies. It’s use is identical to all other SKOSProviders. A base_url of the Atramhasis instance and a scheme_id are required to indicate the vocabulary to be used. Please consult Supported thesauri for a complete list.

For better perfomance in an environment with a skosprovider.registry.Registry we recommend manually providing the uri parameter as metadata. This can cut out the need for a call to the backend upon initialisation.

#!/usr/bin/python
# -*- coding: utf-8 -*-
'''
This script demonstrates using the AtramhasisProvider to get the concept of
'water tricks'.
'''

from skosprovider_atramhasis.providers import AtramhasisProvider

def main():
    # you can adapt this example by using the base_url of another
    # atramhasis-instance and provide an available scheme_id and
    # id within this conceptscheme
    provider = AtramhasisProvider(
        {'id': 'vioe-erfgoedtypes)'},
        base_url='https://thesaurus.onroerenderfgoed.be',
        scheme_id='ERFGOEDTYPES')
    id = 1524

    result = provider.get_by_id(id)


    print('Labels')
    print('------')
    for l in result.labels:
       print(l.language + ': ' + l.label + ' [' + l.type + ']')

    print('Notes')
    print('-----')
    for n in result.notes:
        print(n.language + ': ' + n.note + ' [' + n.type + ']')


if __name__ == "__main__":
    main()

Finding concepts

See the skosprovider_atramhasis.providers.AtramhasisProvider.find() method for a detailed description of how this works.

#!/usr/bin/python
# -*- coding: utf-8 -*-
'''
This script demonstrates using the AtramhasisProvider to find concepts with
'kerk' in their label
'''

from skosprovider_atramhasis.providers import AtramhasisProvider

def main():
    # you can adapt this example by using the base_url of another
    # atramhasis-instance and provide an available scheme_id and
    # the keyword to search for
    provider = AtramhasisProvider(
        {'id': 'vioe-erfgoedtypes)'},
        base_url='https://thesaurus.onroerenderfgoed.be',
        scheme_id='ERFGOEDTYPES')

    keyword = 'kerk'

    results = provider.find({
        'label': keyword,
        'type': 'concept'
    })


    print('Results')
    print('------')
    for result in results:
        print(result)

if __name__ == "__main__":
    main()

Using expand()

The expand method return the id’s of all the concepts that are narrower concepts of a certain concept or collection.

See the skosprovider_atramhasis.providers.AtramhasisProvider.expand() method for a detailed description of how this works.

#!/usr/bin/python
# -*- coding: utf-8 -*-
'''
This script demonstrates using the AtramhasisProvider to expand a concept
'''

from skosprovider_atramhasis.providers import AtramhasisProvider


def main():
    # you can adapt this example by using the base_url of another
    # atramhasis-instance and provide an available scheme_id and the id
    # within this concept scheme to expand
    provider = AtramhasisProvider(
        {'id': 'vioe-erfgoedtypes)'},
        base_url='https://thesaurus.onroerenderfgoed.be',
        scheme_id='ERFGOEDTYPES')
    id = 63 # Id for auxiliary buildings

    results = provider.expand(id)

    print('Results')
    print('------')
    for result in results:
        print(result)


if __name__ == "__main__":
    main()

Adding a cache

Skosprovider_atramhasis has to do a lot of HTTP requests. Depending on your use case, this might cause a lot of overhead. Therefor we’ve made it possible to add a Dogpile cache <https://dogpilecache.sqlalchemy.org/en/latest/>_. To configure the cache, simple add a cache_config key when instantiating the provider. This config will de passed to the Dogpile CacheRegion’s configure_from_config method.

#!/usr/bin/python
# -*- coding: utf-8 -*-
'''
This script demonstrates using the AtramhasisProvider to get concepts with or
without cache.
'''

from skosprovider_atramhasis.providers import AtramhasisProvider
import timeit

def main():
    # you can adapt this example by using the base_url of another
    # atramhasis-instance and provide an available scheme_id and
    # id within this conceptscheme
    id = 1524

    number = 50

    # No caching
    print('Fetching without cache')
    print('----------------------')

    provider = AtramhasisProvider(
        {'id': 'vioe-erfgoedtypes)'},
        base_url='https://thesaurus.onroerenderfgoed.be',
        scheme_id='ERFGOEDTYPES'
    )

    print('%d times: %.5f\n' % (number,
        timeit.timeit(lambda: provider.get_by_id(id),number=number)))


    # Only caching during the script
    print('Fetching with in memory cache')
    print('-----------------------------')

    provider = AtramhasisProvider(
        {'id': 'vioe-erfgoedtypes)'},
        base_url='https://thesaurus.onroerenderfgoed.be',
        scheme_id='ERFGOEDTYPES',
        cache_config={
            'cache.backend' : 'dogpile.cache.memory'
        }
    )

    print('%d times: %.5f\n' % (number,
        timeit.timeit(lambda: provider.get_by_id(id),number=number)))


    # Keep cache in between runs of the script
    # Value is considered valid for 1 day
    print('Fetching with file cache')
    print('------------------------')

    provider = AtramhasisProvider(
        {'id': 'vioe-erfgoedtypes)'},
        base_url='https://thesaurus.onroerenderfgoed.be',
        scheme_id='ERFGOEDTYPES',
        cache_config={
            'cache.backend': 'dogpile.cache.dbm',
            'cache.expiration_time': 60 * 60 * 24,
            'cache.arguments.filename': 'erfgoedtypes.dbm'
        }
    )

    print('%d times: %.5f\n' % (number,
        timeit.timeit(lambda: provider.get_by_id(id),number=number)))

if __name__ == "__main__":
    main()

Supported thesauri

Currently the only known publically available backed is Flanders Heritage Ageny’s own thesaurus website. It offers a range of thesauri dealing with cultural heritage in general and specifically in Flanders. Examples are a thesaurus of heritage types, a thesaurus of cultures and periods, a thesaurus of heritage even types, …