From c689d7fb213b334fe53c4e9b02c935a5da333f6d Mon Sep 17 00:00:00 2001 From: irinaschubert Date: Tue, 14 Sep 2021 10:04:26 +0200 Subject: [PATCH] docs(typo): correct typo in documentation (#85) * Update dsp-tools-create.md * fix wrong quotes * correct obvious errors * correct wrong integer values * Update knora/README.md Co-authored-by: Balduin Landolt <33053745+BalduinLandolt@users.noreply.github.com> * delete incorrect new line * Update README.md Co-authored-by: Balduin Landolt <33053745+BalduinLandolt@users.noreply.github.com> --- docs/dsp-tools-create.md | 25 +- knora/README.md | 824 ++++++++++++++++++++++----------------- 2 files changed, 482 insertions(+), 367 deletions(-) diff --git a/docs/dsp-tools-create.md b/docs/dsp-tools-create.md index 0299ea25a..c1846e818 100644 --- a/docs/dsp-tools-create.md +++ b/docs/dsp-tools-create.md @@ -686,7 +686,7 @@ Represents a text that may contain standoff markup. }, "gui_element": "SimpleText", "gui_attributes": { - "maxlength": "255", + "maxlength": 255, "size": 80 } } @@ -728,7 +728,8 @@ Represents a date. It's a string with the format `calendar:start:end` Please note that the DateValue is an extremely flexible data type. It can represent an exact date or a date with a given uncertainty, and the date can be given in several calendars (currently the Gregorian and the Julian calendars are supported, with the Jewish and Islamic coming soon). Internally, a date is always represented as a start and end date. If start and end date -match, it's an exact date. A value like "1893" will automatically be expanded to a range from January 1st 1893 to December 31st 1893. +match, it's an exact date. A value like "1893" will automatically be expanded to a range from January 1st 1893 to December 31st +1893. - _calendar_ is either _GREGORIAN_ or _JULIAN_ - _start_ has the form _yyyy_-_mm_-_dd_. If only the year is given, the precision is to the year. If only the year and month is @@ -775,7 +776,7 @@ A number with decimal point. "maxlength=integer" and "size=integer" are optional. - _gui_attributes_: - `maxlength=integer` (optional): maximum number of characters accepted - - `size=integer"` (optional): size of the input field + - `size=integer` (optional): size of the input field *Example:* @@ -791,7 +792,7 @@ A number with decimal point. }, "gui_element": "SimpleText", "gui_attributes": { - "maxlength": "255", + "maxlength": 255, "size": 80 } } @@ -867,12 +868,12 @@ Represents an integer value. "maxlength=integer" and "size=integer" are optional. - _gui_attributes_: - `maxlength=integer` (optional): The maximum number of characters accepted - - `size=integer"` (optional): The size of the input field + - `size=integer` (optional): The size of the input field - `Spinbox`: A GUI element for _IntegerValue_. A text field with and "up"- and "down"-button for increment/decrement. The attributes "max=decimal" and "min=decimal" are optional. - _gui_attributes_: - - `max=integer` (optional): Maximal value - - `min=integer` (optional): Minimal value + - `max=decimal` (optional): Maximal value + - `min=decimal` (optional): Minimal value *Example:* @@ -933,7 +934,7 @@ Represents an URI "maxlength=integer" and "size=integer" are optional. - _gui_attributes_: - `maxlength=integer` (optional): The maximum number of characters accepted - - `size=integer"` (optional): The size of the input field + - `size=integer` (optional): The size of the input field *Example:* @@ -949,7 +950,7 @@ Represents an URI }, "gui_element": "SimpleText", "gui_attributes": { - "maxlength": "255", + "maxlength": 255, "size": 80 } } @@ -967,7 +968,7 @@ Represents a time-interval "maxlength=integer" and "size=integer" are optional. - _gui_attributes_: - `maxlength=integer` (optional): The maximum number of characters accepted - - `size=integer"` (optional): The size of the input field + - `size=integer` (optional): The size of the input field - `Interval`: not yet implemented. - _gui_attributes_: No attributes @@ -1163,8 +1164,8 @@ The following parent predefined resources are provided by DSP: - `hasComment` (1-n) - `isAnnotationOf` (1) - `LinkObj`: A resource class linking together several other, generic, resource classes. The class has the following properties: -- `hasComment` (1-n) -- `hasLinkTo` (1-n) + - `hasComment` (1-n) + - `hasLinkTo` (1-n) - `Region`: Represents a simple region. The class has the following properties: - `hasColor` (1) - `isRegionOf` (1) diff --git a/knora/README.md b/knora/README.md index 900549316..035b5a9d6 100644 --- a/knora/README.md +++ b/knora/README.md @@ -1,563 +1,677 @@ # Knora Library -This library offers classes and methods to manipulate a Knora based repository. -Most important it allow importing data by providing a methods to create new resources. +This library offers classes and methods to manipulate a Knora based repository (DSP). Most importantly, it allows importing data +by providing methods to create new ontologies and resources. ## Contents - [Basic methods](#basic-methods) - - [Knora()](#knora) - - [login()](#login) - - [logout](#logout) + - [Knora()](#knora) + - [login()](#login) + - [logout](#logout) - [Project methods()](#project-specific-methods) - - [get_existing_projects()](#get_existing_projects) - - [get_project()](#get_project) - - [project_exists()](#project_exists) - - [create_project()](#create_project) - - [update_project()](#update_project) - - [get_users()](#get_users) - - [create_user()](#create_user) - - [add_user_to_project()](#add_user_to_project) + - [get_existing_projects()](#get_existing_projects) + - [get_project()](#get_project) + - [project_exists()](#project_exists) + - [create_project()](#create_project) + - [update_project()](#update_project) + - [get_users()](#get_users) + - [create_user()](#create_user) + - [add_user_to_project()](#add_user_to_project) - [Ontology methods](#ontology-methods) - - [get_existing_ontologies()](#get_existing_ontologies) - - [get_project_ontologies()](#get_project_ontologies) - - [ontology_exists()](#ontology_exists) - - [get_ontology_lastmoddate()](#get_ontology_lastmoddate) - - [create_ontology()](#create_ontology) - - [delete_ontology()](#delete_ontology) - - [get_ontology_graph()](#get_ontology_graph) - - [create_res_class()](#create_res_class) - - [create_property()](#create_property) - - [create_cardinality()](#create_cardinality) + - [get_existing_ontologies()](#get_existing_ontologies) + - [get_project_ontologies()](#get_project_ontologies) + - [ontology_exists()](#ontology_exists) + - [get_ontology_lastmoddate()](#get_ontology_lastmoddate) + - [create_ontology()](#create_ontology) + - [delete_ontology()](#delete_ontology) + - [get_ontology_graph()](#get_ontology_graph) + - [create_res_class()](#create_res_class) + - [create_property()](#create_property) + - [create_cardinality()](#create_cardinality) - [Lists](#lists) - - [create_list_node()](#create_list_node) - - [get_lists()](#get_lists) - - [get_complete_list()](#get_complete_list) + - [create_list_node()](#create_list_node) + - [get_lists()](#get_lists) + - [get_complete_list()](#get_complete_list) - [Creating instances](#creating-instances) - - [create_resource()](#create_resource) - - [values parameter](#values-parameter) - - [Stillimage parameter](#stillimage-parameter) + - [create_resource()](#create_resource) + - [values parameter](#values-parameter) + - [Stillimage parameter](#stillimage-parameter) - [Other methods](#other-methods) - - [create_schema()](#create_schema) - - [reset_triplestore_content()](#reset_triplestore_content) + - [create_schema()](#create_schema) + - [reset_triplestore_content()](#reset_triplestore_content) - [SIPI](#sipi) - - [Sipi()](#Sipi) - - [upload_image()](#upload_image) + - [Sipi()](#Sipi) + - [upload_image()](#upload_image) - [BulkImport](#bulkImport) - - [Bulkimport()](#bulkimport) - - [add_resource()](#add_resource) - - [upload()](#upload) - + - [Bulkimport()](#bulkimport) + - [add_resource()](#add_resource) + - [upload()](#upload) + ## Knora -Knora is the base class which handles all the communication with the Knora backend. In order -to use Knora, the user has to submit his/her credentials to the Knora backend + +Knora is the base class which handles all the communication with the DSP API. In order to successfully use the API, credentials to +the DSP API have to be submitted. ### Basic methods -#### Knora() -Creates an access object for Knora. -```python3 +#### Knora() + +Creates an access object for the DSP API. + +```python Knora( - server: str, - prefixes: Dict[str, str] = None) -``` -- server: URL of the Knora API server -- prefixes: List of extra RDF-prefixes that are being used -- Example: ```con = Knora(args.server)``` - -#### login() -This method performs a login and stored the access token. -```python3 + server: str, + prefixes: Dict[str, str] = None) +``` + +- server: URL of the DSP server +- prefixes: List of extra RDF prefixes that are being used + +Example: + +``` +con = Knora(args.server) +``` + +#### login() + +Logs in the user and stores the access token. + +```python login(email: str, password: str) -``` -- email: Emailadress of user +``` + +- email: Email address of user - password: Password of user -- Example: ```con.login(args.user, args.password)``` -#### logout() -This method is used to logout from Knora and remove the access token. -```python3 +Example: + +``` +con.login(args.user, args.password) +``` + +#### logout() + +Logs out the user and removes the access token. + +```python logout() ``` -- Example: ```con.logout()``` + +Example: + +``` +con.logout() +``` ### Project specific methods -The following methods are used to add and modify projects and users -#### get_existing_projects() -Returns a list of all projects. Usually returns only the IRI's. If full ist true, returns all information. -```python3 +The following methods are used to add and modify projects and users. + +#### get_existing_projects() + +Returns a list of all projects. By default, only the project's IRI are returned. + +```python get_existing_projects(full: bool = False) ``` -- full: if True, returns not only ontology IRI's -#### get_project() -Returns information about a project given its shortcode. -```python3 +- full: if False (default), only the project's IRI are returned, if True, more information about the projects are returned + +#### get_project() + +Returns information about a project given its shortcode. + +```python get_project(shortcode: str) -> dict -``` +``` + +#### project_exists() + +Returns `True` if a project, given by its IRI, exists in the repository, `False` otherwise. -#### project_exists() -Returns true if a project given by the IRI is existing in the repository. -```python3 +```python project_exists(proj_iri: str) -> bool -``` -- proj_iri: IRI of thee project +``` + +- proj_iri: IRI of the project + +#### create_project() -#### create_project() -This method is used to create a new project. -```python3 +This method is used to create a new project. + +```python create_project( - shortcode: str, - shortname: str, - longname: str, - descriptions: Optional[Dict[str, str]] = None, - keywords: Optional[List[str]] = None, - logo: Optional[str] = None) -> str -``` -- shortcode: The Knora shortcode of the project + shortcode: str, + shortname: str, + longname: str, + descriptions: Optional[Dict[str, str]] = None, + keywords: Optional[List[str]] = None, + logo: Optional[str] = None) -> str +``` + +- shortcode: The shortcode of the project - shortname: The short name of the project -- longname: The long name of the project -- descriptions: [optional] Dict with the language short (e.g. "en", "de"...) as key -- keywords: [optional] List of keywords -- logo: [optional] Path to logo file (The logo must be already on the server) +- longname: The full name of the project +- descriptions: [optional] Dict with the language code (e.g. "en", "de") as key and the actual description as value +- keywords: [optional] List of keywords describing the project +- logo: [optional] Path to logo file (the logo has to be uploaded before it can be referenced) #### update_project() -This method is used to modify existing project data. All parameters except the shortcode (which cannot be changed) -are optional. -```python3 + +Modifies existing project data. All parameters except the shortcode (which cannot be changed) are optional. + +```python update_project( - shortcode: str, - shortname: str, - longname: str, - descriptions: Optional[Dict[str, str]] = None, - keywords: Optional[List[str]] = None, - logo: Optional[str] = None) -> str -``` -- shortcode: The Knora shortcode of the project + shortcode: str, + shortname: str, + longname: str, + descriptions: Optional[Dict[str, str]] = None, + keywords: Optional[List[str]] = None, + logo: Optional[str] = None) -> str +``` + +- shortcode: The shortcode of the project - shortname: The short name of the project -- longname: The long name of the project -- descriptions: [optional] Dict with the language short (e.g. "en", "de"...) as key -- keywords: [optional] List of keywords -- logo: [optional]Path to logo file - +- longname: The full name of the project +- descriptions: [optional] Dict with the language code (e.g. "en", "de") as key and the actual description as value +- keywords: [optional] List of keywords describing the project +- logo: [optional] Path to logo file (the logo has to be uploaded before it can be referenced) + #### get_users() -Get all users + +Returns a list of all users. + ``` get_users() ``` #### get_user() -Get information about a specific user -```python3 + +Returns information about a specific user given its IRI. + +```python get_user(user_iri: str) ``` -- user_iri: Knora IRI identifying the user + +- user_iri: The IRI of the user #### create_user() -Create a new user and returns it's new IRI. -```python3 + +Creates a new user and returns its IRI. + +```python create_user( - username: str, - email: str, - givenName: str, - familyName: str, - password: str, - lang: str = "en") -``` -- username: Username (shortname) + username: str, + email: str, + givenName: str, + familyName: str, + password: str, + lang: str = "en") +``` + +- username: Username - email: Email address of user – is used to identify the user - givenName: First name of the user - familyName: Family name of the user - password: Password -- lang: [optional] Language string of default language +- lang: [optional] Language code of default language #### add_user_to_project() -Add an existing user to a project. -```python3 + +Adds an existing user to a project. + +```python add_user_to_project( - user_iri: str, - project_iri: str) + user_iri: str, + project_iri: str) ``` + - user_iri: IRI of the user -- project_iri: IRI of the project +- project_iri: IRI of the project the user should have access to ### Ontology methods -Since by accidentely two persons could modify an ontology at the same time, a simple -mechanism has been implemented to avoid race conditions: Each modification of an ontology -requres the timestamp of the last modification time. Each manipulation of an ontology returns -this modification time. If the ontology has been modified from outside, the submitted -modification time will not fit and the modification is rejected. -Many methods need both the ontology IRI and the ontology name – the reason for this are performance -issues which eliminate a round trip to the Knora backend. + +Since several instances could modify an ontology at the same time, a simple mechanism has been implemented to avoid race +conditions: +A modification of an ontology requires the timestamp of its last modification. If the ontology has been modified before an update +is submitted, the submitted modification timestamp will not fit and the modification is rejected. Every manipulation of an +ontology returns its new last modification timestamp. + +Many ontology methods need the ontology IRI *and* the ontology name. The reason for this is better performance. With the IRI and +the name, round trips to the DSP backend are avoided. #### get_existing_ontologies() -Get short information about all ontologies existing. -```python3 + +Returns information about all existing ontologies. + +```python get_existing_ontologies() ``` #### get_project_ontologies() -Returns the ontologiees of a given project. -```python3 -get_project_ontologies( -project_code: str) -> Optional[dict] + +Returns the ontologies of a project given the project's IRI. + +```python +get_project_ontologies(project_code: str) -> Optional[dict] ``` + - project_code: Shortcode of project #### ontology_exists() -Test, if an ontology exists. -```python3 + +Returns `True` if the ontology, given by its IRI, exists on the DSP. + +```python ontology_exists(onto_iri: str) ``` + - onto_iri: IRI of the ontology #### get_ontology_lastmoddate() -Get the last modification date of a given ontology. -```python3 + +Returns the last modification date of a given ontology. + +```python get_ontology_lastmoddate(self, onto_iri: str) ``` + - onto_iri: IRI of the ontology #### create_ontology() -Create a new ontology. -```python3 + +Creates a new ontology. + +```python create_ontology( - onto_name: str, - project_iri: str, - label: str + onto_name: str, + project_iri: str, + label: str ) -> Dict[str, str] ``` + - onto_name: Name of the ontology - project_iri: IRI of the project the ontology belongs to -- returns: Dict with "onto_iri" and "last_onto_date" +- returns: Dict with the ontologies IRI and a timestamp of its last modification #### delete_ontology() -Deletes the given ontology. -```python3 + +Deletes the given ontology. + +```python delete_ontology( - onto_iri: str - last_onto_date = None) + onto_iri: str + last_onto_date = None) ``` -- onto_iri: IRO of the ontology -- last_onto_date: Timestamp of last modfication of ontology. It cannot -be deleted if the given date is earlier than the actual last modification -date of the ontology. + +- onto_iri: IRI of the ontology +- last_onto_date: Timestamp of the last modification of the ontology. It cannot be deleted if the given timestamp doesn't fit. #### get_ontology_graph() -Get the whole ontology as RDF (text/turtle). -```python3 + +Returns a given ontology as RDF (text/turtle). + +```python get_ontology_graph( - shortcode: str, - name: str) + shortcode: str, + name: str) ``` + - shortcode: Shortcode of the project - name: Name of the ontology #### create_res_class() -Create a new resource class in the ontology. -```python3 + +Creates a new resource class in the ontology. + +```python create_res_class( - onto_iri: str, - onto_name: str, - last_onto_date: str, - class_name: str, - super_class: List[str], - labels: Dict[str, str], - comments: Optional[Dict[str, str]] = None + onto_iri: str, + onto_name: str, + last_onto_date: str, + class_name: str, + super_class: List[str], + labels: Dict[str, str], + comments: Optional[Dict[str, str]] = None ) -> Dict[str, str] ``` -- onto_iri: IRI of the ontology where the new resource class should be added. -- onto_name: Name for the ontology. -- last_onto_date: Last modification time of ontology. -- class_name: Name of the new class to be added -- super_class: A list of super classes this class is derived from. Usually this -is just "Resource" for "knora-api:Resource" or another resource class including the prefix. -- labels: Dict with the language specific labels, e.g. ```{"en": "english label", "de": 2"german label"}```. -- comments: [optional] Dict with language specifics comments to the resource class. + +- onto_iri: IRI of the ontology the new resource class should be added to +- onto_name: Name of the ontology +- last_onto_date: Timestamp of the ontology's last modification +- class_name: Name of the new class +- super_class: A list of super classes this class is derived from. Usually, this is just "Resource" for "knora-api:Resource" or + another resource class including the prefix. +- labels: Dict with the language specific labels, e.g. `{"en": "English label", "de": "German label"}` +- comments: [optional] Dict with language specific comments about the resource class #### create_property() + Create a new property. -```python3 + +```python create_property( - onto_iri: str, - onto_name: str, - last_onto_date: str, - prop_name: str, - super_props: List[str], - labels: Dict[str, str], - gui_element: str, - gui_attributes: List[str] = None, - subject: Optional[str] = None, - object: Optional[str] = None, - comments: Optional[Dict[str, str]] = None + onto_iri: str, + onto_name: str, + last_onto_date: str, + prop_name: str, + super_props: List[str], + labels: Dict[str, str], + gui_element: str, + gui_attributes: List[str] = None, + subject: Optional[str] = None, + object: Optional[str] = None, + comments: Optional[Dict[str, str]] = None ) -> Dict[str, str] ``` -- onto_iri: IRI of the ontology. -- onto_name: Name of the ontology. -- last_onto_date: Last modification time of ontology. + +- onto_iri: IRI of the ontology the new resource class should be added to +- onto_name: Name of the ontology +- last_onto_date: Timestamp of the ontology's last modification - prop_name: Name of the property to be created -- super_props: List of super-properties, must be at least ```[knora-api:hasValue]```. But it is possible -to declare a property to be a descendant from another property from another ontology or from an external ontology (e.g. foaf:familyName). -Please note that all the prefixes used have to be declared at the construction of the Knora instance. -- labels: Dict of language dependent labels (```{"end": "Eng. label", "de": "Deutsches Label"```). -- gui_element: Gui-element dependent on object (data type). The are a hint for the generic user interface (e.g. SALSAH) -on how to display the field. Available gui elements are: - - salsah-gui:Colorpicker (attributes: ncolors='integer') - - salsah-gui:Date - - salsah-gui:Geometry - - salsah-gui:Geonames - - salsah-gui:Interval - - salsah-gui:List (attributes [required]: hlist='iri') - - salsah-gui:Pulldown (attributes [required]: hlist='iri') - - salsah-gui:Radio (attributes [required]: hlist='iri') - - salsah-gui:Richtext - - salsah-gui:Searchbox (attributes: numprops='integer') - - salsah-gui:SimpleText (attributes: maxlength='integer', size='integer') - - salsah-gui:Slider (attributes [required]: max='decimal', min='decimal') - - salsah-gui:Spinbox (attributes: max='decimal', min='decimal') - - salsah-gui:Textarea (attributes: cols='integer', rows='integer', width='percent'%, wrap="soft"|"hard") - - salsah-gui:Checkbox - - salsah-gui:Fileupload -- gui_attributes: see above -- subject: [optional] The resource the property belongs to. If a resource is used by several resourced, this field can b left empty. -- object: The value type the property points to, e.g. "TextValue", "IntValue" etc. (all value types supportted by Knora). The following object types are supported by Knora: - - salsah-gui:TextValue (gui_element: salsah-gui:SimpleText, salsah-gui:TextArea) A simple text value - - salsah-gui:ColorValue (gui_element: salsah-gui:Colorpicker) A web-color. - - salsah-gui:DateValue (gui_elment: Date): A Knora calendar date. - - salsah_gui:DecimalValue (gui_element: salsah-gui:SimpleText) A Decimal value. - - salsah_gui:GeomValue (gui_element: salsah-gui:Geometry) A geometry (region in an image) - - salsah_gui:GeonameValue (gui_element: salsah-gui:Geonames) A geographical locatiuoin identified by a geonames.org code. - - salsah_gui::IntValue (gui_element: salsah-gui:SimpleText, salsah-gui:Slider, salsah-gui:Spinbox) An integer value. - - salsah_gui:BooleanValue (gui_element: salsah-gui:Checkbox) A boolean value. - - salsah_gui:UriValue (gui_element: salsah-gui:SimpleText) An URI. - - salsah_gui:IntervalValue (gui_element: No Yet Implemented) An interval or time span. - - salsah_gui:ListValue (gui_element: salsah-gui:Pulldown, salsah-gui:Radio, salsah-gui:List) An entry from a list. -- comments: [optional] Dict with language specifics comments to the resource class. +- super_props: List of super-properties, must be at least `[knora-api:hasValue]`. But it is possible to declare a property to be a + descendant from another property from another ontology or from an external ontology (e.g. `foaf:familyName`). Please note that + all used prefixes have to be declared at the construction of the Knora instance. +- labels: Dict with the language specific labels, e.g. `{"en": "English label", "de": "German label"}` +- gui_element: GUI element that should be used. Supported GUI elements are: + - salsah-gui:Colorpicker (attributes: ncolors='integer') + - salsah-gui:Date + - salsah-gui:Geometry + - salsah-gui:Geonames + - salsah-gui:Interval + - salsah-gui:List (attributes [required]: hlist='iri') + - salsah-gui:Pulldown (attributes [required]: hlist='iri') + - salsah-gui:Radio (attributes [required]: hlist='iri') + - salsah-gui:Richtext + - salsah-gui:Searchbox (attributes: numprops='integer') + - salsah-gui:SimpleText (attributes: maxlength='integer', size='integer') + - salsah-gui:Slider (attributes [required]: max='decimal', min='decimal') + - salsah-gui:Spinbox (attributes: max='decimal', min='decimal') + - salsah-gui:Textarea (attributes: cols='integer', rows='integer', width='percent'%, wrap="soft"|"hard") + - salsah-gui:Checkbox + - salsah-gui:Fileupload +- gui_attributes: List of Gui attributes +- subject: [optional] The resource the property belongs to. If a resource is used by several resources, this field can be left + empty. +- object: The value type the property points to. The following object types are supported by DSP: + - salsah-gui:TextValue (gui_element: salsah-gui:SimpleText, salsah-gui:TextArea) A simple text value + - salsah-gui:ColorValue (gui_element: salsah-gui:Colorpicker) A web color + - salsah-gui:DateValue (gui_elment: Date) A Knora calendar date + - salsah_gui:DecimalValue (gui_element: salsah-gui:SimpleText) A Decimal value + - salsah_gui:GeomValue (gui_element: salsah-gui:Geometry) A geometry object (region in an image) + - salsah_gui:GeonameValue (gui_element: salsah-gui:Geonames) A geographical location identified by a geonames.org code + - salsah_gui:IntValue (gui_element: salsah-gui:SimpleText, salsah-gui:Slider, salsah-gui:Spinbox) An integer value + - salsah_gui:BooleanValue (gui_element: salsah-gui:Checkbox) A boolean value + - salsah_gui:UriValue (gui_element: salsah-gui:SimpleText) A URI + - salsah_gui:IntervalValue (gui_element: No Yet Implemented) An interval or time span + - salsah_gui:ListValue (gui_element: salsah-gui:Pulldown, salsah-gui:Radio, salsah-gui:List) An entry from a list +- comments: [optional] Dict with language specifics comments about the resource class #### create_cardinality() -Associate a property with a given resource and indicate the cardinality restriction. -```python3 + +Associates a property with a given resource and indicates the cardinality restriction. + +```python create_cardinality( - onto_iri: str, - onto_name: str, - last_onto_date: str, - class_iri: str, - prop_iri: str, - occurrence: str + onto_iri: str, + onto_name: str, + last_onto_date: str, + class_iri: str, + prop_iri: str, + occurrence: str ) -> Dict[str, str] ``` -- onto_iri: IRI of the ontology. -- onto_name: Name of the ontology. -- last_onto_date: Last modification time of ontology. -- class_iri: IRI of the resource class the property should be associated with. -- prop_iri: IRI of the property to be associated with the resource class. -- occurence: must be one of "1", "0-1", "0-n", "1-n" as string. + +- onto_iri: IRI of the ontology the new resource class should be added to +- onto_name: Name of the ontology +- last_onto_date: Timestamp of the ontology's last modification +- class_iri: IRI of the resource class the property should be associated with +- prop_iri: IRI of the property to be associated with the resource class +- occurrence: must be one of: "1", "0-1", "0-n" or "1-n" (as string) ### Lists -Lists (flat or hierarchical) are ordered named nodes that can be used to -describe controlled vocabularies, selections or hierarchical thesauri. A list -has a root node which gives the list a name. Subnodes define the list elements. In case of -hierarchical lists a subnode may hold further subnodes (recurively). -Lists are associated with a project. + +Lists (flat or hierarchical) are ordered named nodes that can be used as controlled vocabularies, selections or hierarchical +thesauri. A list has a root node where the list's name is defined. Subnodes represent the list elements. In case of hierarchical +lists, a subnode may hold further subnodes (recursively). Lists are always associated with a project. #### create_list_node() -Creates a list node Both root and subnodes, depending on parameters). -```python3 + +Creates a list node (root or subnode, depending on parameters). + +```python create_list_node( - project_iri: str, - labels: Dict[str, str], - comments: Optional[Dict[str, str]] = None, - name: Optional[str] = None, - parent_iri: Optional[str] = None + project_iri: str, + labels: Dict[str, str], + comments: Optional[Dict[str, str]] = None, + name: Optional[str] = None, + parent_iri: Optional[str] = None ) -> str ``` + - project_iri: The IRI of the project the list is associated with -- labels: Language dependent labels, e.g. ```{"en: "yes, "de": "nein"}```. -- comments: Language dependent comments to the node/list -- parent_iri: If None, it is a root note, otherwise the IRI of the parent list node (possibly the root note of the list). +- labels: Language dependent labels, e.g. `{"en": "yes", "de": "nein"}` +- comments: Language dependent comments to the node +- parent_iri: If `None`, it is a root node, otherwise the IRI of the parent node has to be provided (this could also be the root + node) #### get_lists() -Get information about the lists of a given project -```python3 + +Returns information about the lists of a given project. + +```python get_lists( -shortcode: str + shortcode: str ) -> Dict ``` + - shortcode: Shortcode of the project. #### get_complete_list() -Get all the data (nodes) of a specific list -```python3 + +Returns all nodes of a specific list. + +```python get_complete_list( -list_iri: str + list_iri: str ) -> Dict ``` -- list_iri: IRI of the list. + +- list_iri: IRI of the list ### Creating instances + In order to fill the repository with data, resource instances have to be created. #### create_resource() -This Method is used to create a new instance of a given resource. All the data -has to be passed to this function. -```python3 + +Creates a new instance of a given resource. All parameters are required. + +```python create_resource( - schema: Dict, - res_class: str, - label: str, - values: Dict, - stillimage = None + schema: Dict, + res_class: str, + label: str, + values: Dict, + stillimage = None ) -> Dict ``` -- schema: The schema is a Dict that contains information about the ontology. It will by created - by a call to "create_schema()", e.g. ```schema = con.create_schema(args.projectcode, args.ontoname)```. It - is used to validate the data supplied to create_resource for consistency with - the ontology. -- res_class: IRI of the resource class that should be instanciated + +- schema: The schema is a Dict that contains information about the ontology. It will be created by calling the method + `create_schema()`, e.g. `schema = con.create_schema(args.projectcode, args.ontoname)`. It is used to validate the data supplied + to `create_resource()` for consistency with the ontology. +- res_class: IRI of the resource class that should be instantiated - label: A string describing the instance -- values: a Dict describing all the values. See description below. -- stillimage: In case the Resource is a descendant of StillImagerepresentation, this - parameter is indicating where the uploaded file is to be find. See below +- values: A Dict describing all the values. See [example of values parameter](#values-parameter). +- stillimage: In case the resource is a descendant of `StillImageRepresentation`, this parameter contains the file path. See + [example of still image parameter](#still-image-parameter). ##### Values parameter + The values are a Dict in the form: -```python3 + +```python { - "propertyname": value, - "propertyname": value, - ... + "propertyname": value, + "propertyname": value, + ... } ``` -If the property belongs to the same ontology as the resource, the prefix should be omitted. -The value can either be a string or a Dict of the following form: -```python3 + +If the property belongs to the same ontology as the resource, the prefix should be omitted. The value can either be a string or a +Dict of the following form: + +```python { - "value": "the value", - "comment": "a comment to the value" + "value": "the value", + "comment": "a comment to the value" } -``` -_Note_: If the value is text with markup (standard mapping only allowed), then the -value must be an instance of KnoraStandoffXml, e.g.: -```python3 - ... - "richtextprop": { - 'value': KnoraStandoffXml("\n

this is text

with standoff"), - 'comment': "Text mit Markup" - }, +``` + +_Note_: If the value is text with markup (only standard mapping allowed), the value must be an instance of `KnoraStandoffXml`, +e.g.: + +```python ... +"richtextprop": { + 'value': KnoraStandoffXml( + "\n

this is text

with standoff"), + 'comment': "Text with Markup" +}, +... ``` -##### Stillimage parameter: -A stillimage has to be uploaded to Knora before it's SillImageRepresentation instance -can be created: -```python3 +##### Still image parameter: + +A still image has to be uploaded to DSP before its `StillImageRepresentation` instance can be created: + +```python sipi = Sipi(args.sipi, con.get_token()) -img = sipi.upload_image('example.tif') +img = sipi.upload_image("example.tif") ... an_image = con.create_resource(schema, - "object2", - { - "titleprop": "Stained glass", - "linkprop": inst1_info['iri'] - }, - img['uploadedFiles'][0]['internalFilename'] -) + "object2", + { + "titleprop": "Stained glass", + "linkprop": inst1_info['iri'] + }, + img['uploadedFiles'][0]['internalFilename'] + ) ``` ### Other methods #### create_schema() -This method extracts the ontology from the ontology information it gets from Knora. It -gets the ontology information as n3-data using the Knora API and concerts into a convenient -python dict that can be used for further processing. It is required by the bulk import processing -routines and be create_resource(). -```python3 + +Gets the ontology information from DSP API and converts it into a python Dict that can be used for further processing. It is used +by the bulk import and the `create_resource()` method. + +```python create_schema( - shortcode: str, - shortname: str + shortcode: str, + shortname: str ) -> Dict ``` + - shortcode: Shortcode of the ontology -- shortname: Shortname of the ontology +- shortname: Short name of the ontology #### reset_triplestore_content() -Empty the triple store. _Use with uttermost coution_ -Used on local test servers to clean up the local backend. + +Empties the triple store. _Use with uttermost caution._ Used on (local) test instances to clean up the (local) backend. ## SIPI + Sipi is the IIIF conformant image backend. ### Methods of Sipi class #### Sipi() -Constructor for Sipi -```python3 + +Creates a SIPI instance. + +```python Sipi( - sipiserver: str, - token: str + sipiserver: str, + token: str ) ``` + - sipiserver: URL of the SIPI server/endpoint -- token: Access token from Knora +- token: Access token from DSP API + Example: -```python3 + +```python sipi = Sipi(args.sipi, con.get_token()) ``` #### upload_image() + Uploads an image to the SIPI server. + ``` upload_image( filepath: str ) -> Dict ``` -- filepath: Path to file on local filesystem. J2K, TIF, JPEG and PNG images are supported. + +- filepath: Path to the file on the local filesystem. J2K, TIF, JPEG and PNG images are supported. ## Bulk import -The bulk import is used to import larger bunchs of data. + +The bulk import functionality is used to import multiple resources at once. ### BulkImport -Thee Bulkimport class handles all bulk import stuff + +Handles the bulk import. #### Bulkimport() -Constructor of a bulkimport instance -```python3 + +Creates a Bulkimport instance + +```python Bulkimport( - schema: Dict + schema: Dict ) -> Bulkimport ``` -- schema: see create_schema() + +- schema: See `create_schema()` #### add_resource() -Add an instance to the bulk import. -```python3 + +Adds an instance to the bulk import. + +```python add_resource( - resclass: str, - id: str, - label: str, - properties: Dict + resclass: str, + id: str, + label: str, + properties: Dict ) ``` -- resclass: Name of resource class (prefix may be omitted) -- id: a user defined ID that can be used to reference this resource by later resources. -- label: String desribing the instance -- properties: Dict of propertyname - value pairs. + +- resclass: Name of the resource class (prefix may be omitted) +- id: A user defined (internal) ID that can be used to reference this resource later during the bulk import +- label: String describing the instance +- properties: Dict of property name/value pairs #### upload() -Upload the data using the bulk import route. -```python3 + +Uploads the data using the bulk import route of the DSP API. + +```python upload( - user: str, - password: str, - hostname: str, - port: int + user: str, + password: str, + hostname: str, + port: int ) ``` -- user: username -- password: Password -- hostname: Hostname of Knora backend -- port: Portnumber the Knora backend uses - -# Examples +- user: Username +- password: Password +- hostname: Hostname of the DSP backend +- port: Port number the DSP backend uses