Pyramid Skosprovider¶
This library helps to integrate skosprovider in a Pyramid application.
Support¶
If you have questions regarding Pyramid_Skosprovider, feel free to contact us. Any bugs you find or feature requests you have, you can add to our issue tracker. If you’re unsure if something is a bug or intentional, or you just want to have a chat about this library or SKOS in general, feel free to join the Atramhasis discussion forum. While these are separate software projects, they are being run by the same people and they integrate rather tightly.
Installation¶
To install pyramid_skosprovider, use pip
pip install pyramid_skosprovider
To activate pyramid_skosprovider, just include it.
config = Configurator()
config.include('pyramid_skosprovider')
This will create a skosprovider.registry.Registry
and add it to
the pyramid application registry.
Usage¶
To get a skosprovider.registry.Registry
instance, call
pyramid_skosprovider.get_skos_registry()
with the current
application registry.
Eg. in a view:
from pyramid_skosprovider import get_skos_registry
def my_view(request):
skos = get_skos_registry(request.registry)
providers = skos.get_providers()
# ...
Alternatively you can get the registry as an attribute of a pyramid request:
from pyramid_skosprovider import get_skos_registry
def my_view(request):
skos = request.skos_registry
providers = skos.get_providers()
# ...
For a real-world example of an integration of pyramid_skosprovider in a Pyramid application, have a look at Atramhasis, a SKOS vocabulary editor partially built upon this library.
Service Documentation¶
This library takes your skosproviders and makes them available as REST services. The pyramid_skosprovider serves JSON as a REST service so it can be used easily inside a AJAX webbrowser call or by an external program.
The following API can be used by clients:
-
GET
/uris
¶ Find more information on a certain URI. This can map to eiter a concept, collection or conceptscheme that is known by the current SKOS registry.
Example request:
GET /uris?uri=urn:x-skosprovider:trees HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "id": "TREES", "uri": "urn:x-skosprovider:trees", "type": "concept_scheme" }
Example request:
GET /uris/?uri=http://python.com/trees/larch HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "id": "1", "uri": "http://python.com/trees/larch", "type": "concept", "concept_scheme": { "id": "TREES", "uri": "urn:x-skosprovider:trees" } }
Query Parameters: - uri – The URI to search for.
Status Codes: - 200 OK – The URI maps to something known by pyramid_skosprovider, either a conceptscheme, a concept or collection.
- 404 Not Found – The URI can’t be found by pyramid_skosprovider.
-
GET
/c
¶ Search for concepts or collections, no matter what scheme they’re a part of.
Although it is possible to search a single conceptscheme with just this endpoint, for performance reasons it is advised to use
GET /conceptschemes/{scheme_id}/c
.Example request:
GET /c HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Range: items 0-2/232 Content-Type: application/json; charset=UTF-8 [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" }, { "id": 3, "uri": "urn:x-skosprovider:TREES:3", "type": "collection", "label": "Bomen per soort" } ]
Example request:
GET /c?type=concept&providers.subject=external&sort=uri HTTP/1.1 Host: localhost:6543 Accept: application/json
Query Parameters: - type – Define if you want to show concepts or collections. Leave blank to show both.
- mode – Allows for special processing mode for dijitFilteringSelect. Makes it possible to use wildcards in the label parameter.
- label – Shows all concepts and collections that have this search string in one of their labels.
- language – Returns the label with the corresponding language-tag if present.
If the language is not present for this concept/collection, it falls back to
1) the default language of the provider. 2) ‘en’ 3) any label.
Eg.
?language=nl
to show the dutch labels of the concepts/collections. - sort – Define if you want to sort the results by a given field. Otherwise items are returned
in an indeterminate order. Prefix with ‘+’ to sort ascending, ‘-‘ to sort descending.
eg.
?sort=-label
to sort all results descending by label. - providers.ids – A comma separated list of concept scheme id’s. The query
will only be passed to the providers with these id’s. eg.
?providers.ids=TREES, PARROTS
will only list concepts from these two providers. - providers.subject – A subject can be registered with a skosprovider in
the registry. Adding this search parameter means that the query will only
be passed on to providers that have been tagged with this subject. Eg.
?providers.subject=external
to only query the providers that have been marked with the subject external.
Request Headers: - Range – Can be used to request a certain set of results.
eg.
items=0-24
requests the first 25 results.
Response Headers: - Content-Range – Tells the client what set of results is being returned
eg.
items=0-24/306
means the first 25 out of 306 results are being returned.
Status Codes: - 200 OK – The concepts in this conceptscheme were found.
-
GET
/conceptschemes
¶ Get all registered conceptschemes.
Example request:
GET /conceptschemes HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:42:34 GMT [ { "id": "TREES", "uri": "urn:x-skosprovider:trees", "label": "Different types of trees." } ]
Status Codes: - 200 OK – The list of conceptschemes was found.
-
GET
/conceptschemes/{scheme_id}
¶ Get information about a concept scheme.
Example request:
GET /conceptschemes/TREES HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Length: 15 Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:45:37 GMT Server: waitress { "id": "TREES", "uri": "urn:x-skosprovider:trees", "label": "Different types of trees.", "labels": [ {"type": "prefLabel", "language": "en", "label": "Different types of trees."}, {"type": "prefLabel", "language": "nl", "label": "Verschillende soorten bomen."} ] }
Example request:
-.. sourcecode:: http
GET /conceptschemes/PLANTS HTTP/1.1 Host: localhost:6543 Accept: application/jsonExample response:
HTTP/1.1 404 Not Found Content-Length: 775 Content-Type: text/html; charset=UTF-8 Date: Tue, 15 Apr 2014 20:32:52 GMT Server: waitress
Status Codes: - 200 OK – The conceptscheme was found.
- 404 Not Found – The conceptscheme was not found.
-
GET
/conceptschemes/{scheme_id}/topconcepts
¶ Get all top concepts in a certain conceptscheme. These are all the concepts in the conceptscheme that have no broader concept.
Example request:
GET /conceptschemes/TREES/topconcepts HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:47:33 GMT Server: waitress [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" } ]
Query Parameters: - language – Returns the label with the corresponding language-tag if present.
If the language is not present for this concept/collection, it falls back to
1) the default language of the provider. 2) ‘en’ 3) any label.
Eg.
?language=nl
to show the dutch labels of the concepts/collections.
Status Codes: - 200 OK – The topconcepts in this conceptscheme were found.
- 404 Not Found – The conceptscheme was not found.
- language – Returns the label with the corresponding language-tag if present.
If the language is not present for this concept/collection, it falls back to
1) the default language of the provider. 2) ‘en’ 3) any label.
Eg.
-
GET
/conceptschemes/{scheme_id}/displaytop
¶ Get the top of a display hierarchy. Depending on the underlying provider this will be a list of Concepts and Collections.
Example request:
GET /conceptschemes/TREES/displaytop HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:47:33 GMT Server: waitress [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" } ]
Query Parameters: - language – Returns the label with the corresponding language-tag if present.
If the language is not present for this concept/collection, it falls back to
1) the default language of the provider. 2) ‘en’ 3) any label.
Eg.
?language=nl
to show the dutch labels of the concepts/collections.
Status Codes: - 200 OK – The concepts and collections were found.
- 404 Not Found – The conceptscheme was not found.
- language – Returns the label with the corresponding language-tag if present.
If the language is not present for this concept/collection, it falls back to
1) the default language of the provider. 2) ‘en’ 3) any label.
Eg.
-
GET
/conceptschemes/{scheme_id}/c
¶ Search for concepts or collections in a scheme.
Example request:
GET /conceptschemes/TREES/c HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Length: 117 Content-Range: items 0-2/3 Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:47:33 GMT Server: waitress [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" }, { "id": 3, "uri": "urn:x-skosprovider:TREES:3", "type": "collection", "label": "Bomen per soort" } ]
Example request:
GET /conceptschemes/PLANTS/c HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 404 Not Found Content-Length: 775 Content-Type: text/html; charset=UTF-8 Date: Tue, 15 Apr 2014 20:32:52 GMT Server: waitress
Query Parameters: - type – Define if you want to show concepts or collections. Leave blank to show both.
- mode – Allows for special processing mode for dijitFilteringSelect. Makes it possible to use wildcards in the label parameter.
- label – Shows all concepts and collections that have this search string in one of their labels.
- collection – Get information about the content of a collection. Expects to be passed an id of a collection in this scheme. Will restrict the search to concepts or collections that are a member of this collection or a narrower concept of a member.
- language – Returns the label with the corresponding language-tag if present.
If the language is not present for this concept/collection, it falls back to
1) the default language of the provider. 2) ‘en’ 3) any label.
Eg.
?language=nl
to show the dutch labels of the concepts/collections. - sort – Define if you want to sort the results by a given field. Otherwise items are returned
in an indeterminate order. Prefix with ‘+’ to sort ascending, ‘-‘ to sort descending.
eg.
?sort=-label
to sort all results descending by label.
Request Headers: - Range – Can be used to request a certain set of results.
eg.
items=0-24
requests the first 25 results.
Response Headers: - Content-Range – Tells the client was set of results is being returned
eg.
items=0-24/306
means the first 25 out of 306 results are being returned.
Status Codes: - 200 OK – The concepts in this conceptscheme were found.
- 404 Not Found – The conceptscheme was not found.
-
GET
/conceptschemes/{scheme_id}/c/{c_id}
¶ Get information about a concept or collection.
Example request:
GET /conceptschemes/TREES/c/1 HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:49:27 GMT Server: waitress { "broader": [], "narrower": [], "notes": [ {"note": "A type of tree.", "type": "definition", "language": "en"} ], "labels": [ {"type": "prefLabel", "language": "en", "label": "The Larch"}, {"type": "prefLabel", "language": "nl", "label": "De Lariks"} ], "type": "concept", "id": "1", "uri": "urn:x-skosprovider:TREES:1", "related": [], "label": "The Larch", "matches": { "close": [ "http://id.python.org/different/types/of/trees/nr/1/the/larch" ] }, "concept_scheme": { "uri": "urn:x-foo:bar" } }
Example request:
GET /conceptschemes/TREES/c/4 HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 404 Not Found Content-Length: 775 Content-Type: text/html; charset=UTF-8 Date: Tue, 15 Apr 2014 20:06:12 GMT Server: waitress
Status Codes: - 200 OK – The concept was found in the conceptscheme.
- 404 Not Found – The concept was not found in the conceptscheme or the conceptscheme was not found.
-
GET
/conceptschemes/{scheme_id}/c/{c_id}/displaychildren
¶ Get a list of Collections and Concepts that should be displayed as children of this Concept or Collection.
Example request:
GET /conceptschemes/TREES/c/3/displaychildren HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:49:27 GMT Server: waitress [ { "id": "1", "uri": "urn:x-skosprovider:TREES:1", "type": "concept", "label": "De Lariks" }, { "id": "2", "uri": "urn:x-skosprovider:TREES:2", "type": "concept", "label": "De Paardekastanje" } ]
Query Parameters: - language – Returns the label with the corresponding language-tag if present.
If the language is not present for this concept/collection, it falls back to
1) the default language of the provider. 2) ‘en’ 3) any label.
Eg.
?language=nl
to show the dutch labels of the concepts/collections.
Status Codes: - 200 OK – The concept was found in the conceptscheme.
- 404 Not Found – The concept was not found in the conceptscheme or the conceptscheme was not found.
- language – Returns the label with the corresponding language-tag if present.
If the language is not present for this concept/collection, it falls back to
1) the default language of the provider. 2) ‘en’ 3) any label.
Eg.
-
GET
/conceptschemes/{scheme_id}/c/{c_id}/expand
¶ 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.- Returns A list of id’s or
HTTPNotFound
if the concept or collection doesn’t - exist.
Example request:
GET /conceptschemes/TREES/c/3/expand HTTP/1.1 Host: localhost:6543 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Mon, 14 Apr 2014 14:49:27 GMT Server: waitress [1 , 2]
Status Codes: - 200 OK – The concept/collection was found in the conceptscheme.
- 404 Not Found – The concept/collection was not found in the conceptscheme or the conceptscheme was not found.
- Returns A list of id’s or
API Documentation¶
General¶
-
pyramid_skosprovider.
get_skos_registry
(registry)[source]¶ Get the
skosprovider.registry.Registry
attached to this pyramid application.Return type: skosprovider.registry.Registry
Utils¶
This module contains a few utility functions.
Renderers¶
This module contains function for rendering SKOS objects to JSON.
-
pyramid_skosprovider.renderers.
collection_adapter
(obj, request)[source]¶ Adapter for rendering a
skosprovider.skos.Collection
to json.Parameters: obj (skosprovider.skos.Collection) – The collection to be rendered. Return type: dict
-
pyramid_skosprovider.renderers.
concept_adapter
(obj, request)[source]¶ Adapter for rendering a
skosprovider.skos.Concept
to json.Parameters: obj (skosprovider.skos.Concept) – The concept to be rendered. Return type: dict
-
pyramid_skosprovider.renderers.
label_adapter
(obj, request)[source]¶ Adapter for rendering a
skosprovider.skos.Label
to json.Parameters: obj (skosprovider.skos.Label) – The label to be rendered. Return type: dict
-
pyramid_skosprovider.renderers.
note_adapter
(obj, request)[source]¶ Adapter for rendering a
skosprovider.skos.Note
to json.Parameters: obj (skosprovider.skos.Note) – The note to be rendered. Return type: dict
-
pyramid_skosprovider.renderers.
source_adapter
(obj, request)[source]¶ Adapter for rendering a
skosprovider.skos.Source
to json.Parameters: obj (skosprovider.skos.Source) – The source to be rendered. Return type: dict
History¶
0.8.0 (2017-07-12)¶
- Return an HTTP 404 response when a conceptscheme could not be found. (#24)
- Add universal wheel distribution. (#23)
- Add support for sorting on a SortLabel. This means a client can now ask to sort the results either on id, label or sortlabel. See the skosprovider docs for more on the sortlabel. This basically allows for arbitrary sorting per language so it’s possible to eg. sort Historical periods chronologically. (#26) [cahytinne]
0.7.0 (2016-08-11)¶
- Sort case insensitive when sorting by label. This is a BC break, although to most users it might actually be a bug fix. (#16) [TalissaJoly]
- Add the markup attribute to Note json representations. This is a new addition to skosprovider 0.6.0 that allows marking that a note contains some markup (currently only HTML).
- Looking for a certain URI is now done with a query parameter in stead of in the path of a resource. So, /uris/urn:x-skosprovider:trees should now be called as /uris?uri=urn:x-skosprovider:trees. The old way is deprecated. It will still function under version 0.7.0, but will be removed in a future version. (#19)
- Add support for the sources attribute, a new feature in skosprovider 0.6.0
- Add support for languages to Conceptschemes, a new feature in skosprovider 0.6.0 that allows detailing what languages a conceptscheme uses.
- Move JSON renderers to their own file and fix some language handling issues. (#22)
- Add support for Python 3.5
0.6.0 (2015-03-02)¶
- Allow the client to specify in which language labels should preferentially
be returned. This can be chosen by adding a
language
parameter to certain query strings. If not present, pyramid_skosprovider falls back on pyramid’s locale negotiation. (#10) (#14) [dieuska] - Expose a provider’s expand method. This returns the narrower transitive closure for a certain concept or collection. (#11) [dieuska]
- Some documentation updates.
0.5.0 (2014-12-19)¶
- Conceptschemes expose information on the subject they’re tagged with. [BartSaelen]
- A new search endpoint for searching across conceptschemes was added. Search syntax is the same as for searching within a single scheme, but the collection parameter is not accepted. Two extra parameters were added for limiting the search to a subset of available conceptschemes. (#8)
- A new endpoint for looking up a certain URI was added. This endpoint does not redirect to an external URI, but lets a client know where more information about this URI can be found (eg. in which conceptscheme a concept lives). (#7)
0.4.0 (2014-10-23)¶
- Compatibility with skosprovider 0.4.0
- Drop support for Python 2.6 and Python 3.2.
- Expose notes on collections.
- Expose matches on concepts (collections don’t have matches).
- Expose subordinate_arrays on concepts and superordinates on collections.
- Integrate concept scheme information. Concepts and collections passed through the service now contain the uri of the concept scheme they belong to. The concept scheme endpoint now also exposes information like a uri, a list of labels and notes.
0.3.0 (2014-06-24)¶
- Expose information about top concepts.
- Expose information about display top and display children.
- Fix a bug with returning concepts and collections not on the first page of data through the Range header. (#3)
- Added support for sorting. (#4, #5) [cedrikv]
0.2.0 (2014-05-14)¶
- Compatibility with skosprovider 0.3.0
- Added service documentation (#1)
0.1.1 (2014-04-10)¶
- Code coverage by coveralls.
- Removed unit tests from resulting package.
- Moved documentation to Sphinx.
- Reorganisation of tests.
- Changed to py.test as testrunner.
- Some Flake8 fixes.
0.1.0 (2013-05-16)¶
- Initial version
- Includes json views based on the interfaces skosprovider offers.
- Adds a skosprovider registry to the pyramid request.