You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.rst
+31-50
Original file line number
Diff line number
Diff line change
@@ -13,18 +13,18 @@ The Python Linked Data API (pyLDAPI) is:
13
13
What is it?
14
14
-----------
15
15
16
-
This module contains only a small Python module which is intended to be added (imported) into a `Python Flask`_ installation in order to add a series of extra functions to endpoints to the ones defined by you as a Flask user (URL routes).
16
+
This module contains a small Python module which is intended to be added (imported) into a `Python Flask<http://flask.pocoo.org/>`_ installation to add a small library of ``Renderer`` classes which can be used to handle requests and return responses in a manner consistent with `Linked Data <https://en.wikipedia.org/wiki/Linked_data>`__ principles of operation.
17
17
18
-
.. _Python Flask: http://flask.pocoo.org/
18
+
The intention is to make it easy to "Linked Data-enable" web APIs.
19
19
20
20
An API using this module will get:
21
21
22
-
* an *alternates view* for each *Register* and *Object* that the API delivers
23
-
* if the API declares the appropriate *model views* for each item
22
+
* an *alt profile* for each endpoint that uses a ``Renderer`` class to return responses that the API delivers
23
+
* this is a *profile*, or *view* of the resource that lists all other available profiles
24
24
* a *Register of Registers*
25
25
* a start-up function that auto-generates a Register of Registers is run when the API is launched.
26
26
* a basic, over-writeable template for Registers' HTML & RDF
27
-
* all of the functionality defined by the W3C's specification `Content Negotiation by Profile`_
27
+
* all of the functionality defined by the W3C's `Content Negotiation by Profile<https://www.w3.org/TR/dx-prof-conneg/>`_ specification
28
28
* to allow for requests of content that conform to data specifications and profiles
29
29
30
30
The main parts of pyLDAPI are as follows:
@@ -37,23 +37,16 @@ The main parts of pyLDAPI are as follows:
37
37
38
38
Web requests arrive at a Web Server, such as *Apache* or *nginx*, which then forwards (some of) them on to *Flask*, a Python web framework. Flask calls Python functions for web requests defined in a request/function mapping and may call pyLDAPI elements. Flask need not call pyLDAPI for all requests, just as Apache/nginx need not forward all web request to flask. pyLDAPI may then draw on any Python data source, such as database APIs, and uses the *rdflib* Python module to formulate RDF responses.
39
39
40
-
.. _Content Negotiation by Profile: https://www.w3.org/TR/dx-prof-conneg/
41
-
42
40
Definitions
43
41
-----------
44
42
45
-
Alternates View
46
-
~~~~~~~~~~~~~~~
47
-
The *model view* that lists all other views. This API uses the definition of *alternates view* presented at `https://promsns.org/def/alt`_.
The *model view* that lists all other views. This API uses the definition of *alternates profile* presented at `https://promsns.org/def/alt <https://promsns.org/def/alt>`_.
50
46
51
47
Linked Data Principles
52
48
~~~~~~~~~~~~~~~~~~~~~~
53
-
The principles of making things available over the internet in both human and machine-readable forms. Codified by the World Wide Web Consortium. See `https://www.w3.org/standards/semanticweb/data`_.
The principles of making things available over the internet in both human and machine-readable forms. Codified by the World Wide Web Consortium. See `https://www.w3.org/standards/semanticweb/data <https://www.w3.org/standards/semanticweb/data>`_.
This is licensed under GNU General Public License (GPL) v3.0. See the `LICENSE deed <https://raw.githubusercontent.com/RDFLib/pyLDAPI/master/LICENSE>`_ for more details.
131
110
132
111
133
112
Contact
@@ -136,29 +115,31 @@ Contact
136
115
Dr Nicholas Car (lead)
137
116
~~~~~~~~~~~~~~~~~~~~~~
138
117
|*Data Systems Architect*
139
-
|`SURROUND Australia Pty Ltd`_
140
-
|`nicholas.car@surroundaustralia.com`_
141
-
|`https://orcid.org/0000-0002-8742-7730`_
142
-
143
-
.. _SURROUND Australia Pty Ltd: https://surroundaustralia.com
<td><ahref="{{ request.base_url }}?_view={{ v }}">{{ v }}</a></td>
24
+
<td><ahref="{{ request.base_url }}?_profile={{ v }}">{{ v }}</a></td>
25
25
<td>
26
26
{% for f in vals['formats'] %}
27
-
<ahref="{{ request.base_url }}?_view={{ v }}&_format={{ f }}">{{ f }}</a>
27
+
<ahref="{{ request.base_url }}?_profile={{ v }}&_format={{ f }}">{{ f }}</a>
28
28
{% if loop.index != vals['formats']|length %}<br />{% endif %}
29
29
{% endfor %}
30
30
</td>
@@ -35,7 +35,7 @@ Example of a generic alternates template:
35
35
</table>
36
36
{% endblock %}
37
37
38
-
The alternates view template is shared for both a Register's alternates view as well as a class instance item's alternates view. In any case, since a :class:`.RegisterRenderer` class and a :ref:`example-renderer-reference` class both inherit from the base class :class:`.Renderer`, then they can both easily render the alternates view by calling the base class' :func:`pyldapi.Renderer.render_alternates_view` method. One distinct difference is that pyLDAPI will handle the alternates view automatically for a :class:`.RegisterRenderer` whereas a :ref:`example-renderer-reference` will have to explicitly call the :func:`pyldapi.Renderer.render_alternates_view`.
38
+
The alternates profile template is shared for both a Register's alternates profile as well as a class instance item's alternates profile. In any case, since a :class:`.RegisterRenderer` class and a :ref:`example-renderer-reference` class both inherit from the base class :class:`.Renderer`, then they can both easily render the alternates profile by calling the base class' :func:`pyldapi.Renderer.render_alternates_profile` method. One distinct difference is that pyLDAPI will handle the alternates profile automatically for a :class:`.RegisterRenderer` whereas a :ref:`example-renderer-reference` will have to explicitly call the :func:`pyldapi.Renderer.render_alternates_profile`.
39
39
40
40
Example usage for a :ref:`example-renderer-reference`:
41
41
@@ -48,6 +48,6 @@ Example usage for a :ref:`example-renderer-reference`:
48
48
# this is an implementation of the abstract render() of the base class Renderer
49
49
defrender(self):
50
50
# ...
51
-
ifself.view=='alternates':
52
-
returnself.render_alternates_view() # render the alternates view for this class instance
51
+
ifself.profile=='alternates':
52
+
returnself.render_alternates_profile() # render the alternates profile for this class instance
Copy file name to clipboardexpand all lines: docs/source/register_template.rst
+3-3
Original file line number
Diff line number
Diff line change
@@ -31,8 +31,8 @@ Example of a generic register template:
31
31
{{ pagination.links }}
32
32
</td>
33
33
<tdstyle="vertical-align:top;">
34
-
<h3>Alternate views</h3>
35
-
<p>Different views of this register are listed at its <ahref="{{ request.base_url }}?_view=alternates">Alternate views</a> page.</p>
34
+
<h3>Alternate profiles</h3>
35
+
<p>Different profiles of this register are listed at its <ahref="{{ request.base_url }}?_profile=alternates">Alternate profiles</a> page.</p>
36
36
<h3>Automated Pagination</h3>
37
37
<p>To page through these items, use the query string arguments 'page' for the page number and 'per_page' for the number of items per page. HTTP <code>Link</code> headers of <code>first</code>, <code>prev</code>, <code>next</code> & <code>last</code> indicate URIs to the first, a previous, a next and the last page.</p>
38
38
<p>Example:</p>
@@ -73,4 +73,4 @@ Variables used by the register template:
73
73
pagination=pagination # pagination object from module flask_paginate
74
74
)
75
75
76
-
See :class:`.RegisterRenderer` for an example on how to render the register view.
76
+
See :class:`.RegisterRenderer` for an example on how to render the register profile.
:param register_items: The items within this register as a list of URI strings or tuples with string elements like (URI, label). They can also be tuples like (URI, URI, label) if you want to manually specify an item's class.
46
+
:param register_items: The items within this register as a list of URI strings or tuples with string elements
47
+
like (URI, label). They can also be tuples like (URI, URI, label) if you want to manually specify an item's
48
+
class.
47
49
:type register_items: list
48
-
:param contained_item_classes: The list of URI strings of each distinct class of item contained in this Register.
50
+
:param contained_item_classes: The list of URI strings of each distinct class of item contained in this
51
+
Register.
49
52
:type contained_item_classes: list
50
-
:param register_total_count: The total number of items in this Register (not of a page but the register as a whole).
53
+
:param register_total_count: The total number of items in this Register (not of a page but the register as a
54
+
whole).
51
55
:type register_total_count: int
52
-
:param views: A dictionary of named :class:`.View` objects available for this Register, apart from 'reg' which is auto-created.
53
-
:type views: dict
54
-
:param default_view_token: The ID of the default :class:`.View` (key of a view in the list of Views).
55
-
:type default_view_token: str
56
+
:param profiles: A dictionary of named :class:`.View` objects available for this Register, apart from 'reg'
57
+
which is auto-created.
58
+
:type profiles: dict
59
+
:param default_profile_token: The ID of the default :class:`.View` (key of a profile in the list of Views).
60
+
:type default_profile_token: str
56
61
:param super_register: A super-Register URI for this register. Can be within this API or external.
57
62
:type super_register: str
58
-
:param register_template: The Jinja2 template to use for rendering the HTML view of the register. If None, then it will default to try and use a template called :code:`alternates.html`.
63
+
:param register_template: The Jinja2 template to use for rendering the HTML profile of the register. If None,
64
+
then it will default to try and use a template called :code:`alt.html`.
59
65
:type register_template: str or None
60
-
:param per_page: Number of items to show per page if not specified in request. If None, then it will default to RegisterRenderer.DEFAULT_ITEMS_PER_PAGE.
66
+
:param per_page: Number of items to show per page if not specified in request. If None, then it will default to
67
+
RegisterRenderer.DEFAULT_ITEMS_PER_PAGE.
61
68
:type per_page: int or None
62
69
"""
63
-
ifviewsisNone:
64
-
views= {}
65
-
fork, vinviews.items():
70
+
ifprofilesisNone:
71
+
profiles= {}
72
+
fork, vinprofiles.items():
66
73
ifk=='reg':
67
74
raiseViewsFormatsException(
68
-
'You must not manually add a view with token \'reg\' as this is auto-created'
75
+
'You must not manually add a profile with token \'reg\' as this is auto-created'
<p>To page through these items, use query string arguments 'page' and 'per_page'. HTTP <code>Link</code> headers of <code>first</code>, <code>prev</code>, <code>next</code> & <code>last</code> are given in web responses.</p>
43
+
<p>Example, assuming 500 items, page 7, of 50 per page, is given by:</p>
44
+
<pre>.../?page=7&per_page=50
45
+
</pre>
46
+
<p>Link header with a response assuming 500 items would be:</p>
47
+
<pre>Link: <.../?per_page=500> rel="first",
48
+
<.../?per_page=500&page=6> rel="prev",
49
+
<.../?per_page=500&page=8> rel="next",
50
+
<.../?per_page=500&page=10> rel="last"
51
+
</pre>
52
+
<p>If you want to page through the whole collection, start at <code>first</code> and follow link headers until you reach <code>last</code> or until no <code>last</code> is given. You shouldn't try to calculate each <code>page</code> query string argument yourself.</p>
0 commit comments