From d76a62025d1d4c2075294702082e5d7addb65102 Mon Sep 17 00:00:00 2001 From: irinaschubert Date: Mon, 30 Aug 2021 17:48:23 +0200 Subject: [PATCH 1/7] Update dsp-tools-create.md --- docs/dsp-tools-create.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dsp-tools-create.md b/docs/dsp-tools-create.md index b34de367b..bf3611b4c 100644 --- a/docs/dsp-tools-create.md +++ b/docs/dsp-tools-create.md @@ -1163,8 +1163,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) From 5b8ee9f4d8125a3964193e54348f555dcd1d075f Mon Sep 17 00:00:00 2001 From: irinaschubert Date: Mon, 13 Sep 2021 11:34:39 +0200 Subject: [PATCH 2/7] fix wrong quotes --- docs/dsp-tools-create.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/dsp-tools-create.md b/docs/dsp-tools-create.md index ac0681efd..1674545eb 100644 --- a/docs/dsp-tools-create.md +++ b/docs/dsp-tools-create.md @@ -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:* @@ -867,7 +868,7 @@ 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_: @@ -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:* @@ -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 From 4d0d4e4cae0f9669d71923edebbedb232dcaf390 Mon Sep 17 00:00:00 2001 From: irinaschubert Date: Mon, 13 Sep 2021 13:29:46 +0200 Subject: [PATCH 3/7] correct obvious errors --- knora/README.md | 751 ++++++++++++++++++++++++++++-------------------- 1 file changed, 435 insertions(+), 316 deletions(-) diff --git a/knora/README.md b/knora/README.md index 900549316..9ae3c0c53 100644 --- a/knora/README.md +++ b/knora/README.md @@ -1,563 +1,682 @@ # 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. 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 Knora backend. In order to use Knora, the user has to submit +his/her credentials to the Knora backend ### Basic methods -#### Knora() -Creates an access object for Knora. -```python3 +#### Knora() + +Creates an access object for Knora. + +```python Knora( - server: str, - prefixes: Dict[str, str] = None) -``` + 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)``` +- prefixes: List of extra RDF prefixes that are being used + +Example: -#### login() -This method performs a login and stored the access token. -```python3 +``` +con = Knora(args.server) +``` + +#### login() + +This method performs a login and stored 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() + +This method is used to log out from Knora and remove 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 +#### get_existing_projects() + +Returns a list of all projects. Usually returns only the IRI's. If full ist true, returns all information. + +```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 True, returns not only ontology IRI's + +#### get_project() + +Returns information about a project given its shortcode. + +```python get_project(shortcode: str) -> dict -``` +``` + +#### project_exists() -#### project_exists() -Returns true if a project given by the IRI is existing in the repository. -```python3 +Returns true if a project given by the IRI is existing in the repository. + +```python project_exists(proj_iri: str) -> bool -``` -- proj_iri: IRI of thee project +``` -#### create_project() -This method is used to create a new project. -```python3 +- proj_iri: IRI of the project + +#### create_project() + +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 Knora short code 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 +- descriptions: [optional] Dict with the language code (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) +- logo: [optional] Path to logo file (the logo must be already on the server) #### update_project() + This method is used to modify existing project data. All parameters except the shortcode (which cannot be changed) -are optional. -```python3 +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 Knora short code 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 +- descriptions: [optional] Dict with the language code (e.g. "en", "de"...) as key - keywords: [optional] List of keywords -- logo: [optional]Path to logo file - +- logo: [optional] Path to logo file + #### get_users() -Get all users + +Get all users + ``` get_users() ``` #### get_user() -Get information about a specific user -```python3 + +Get information about a specific user + +```python get_user(user_iri: str) ``` + - user_iri: Knora IRI identifying 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 (short name) - 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 + +Add 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 ### 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: +Each modification of an ontology requires the timestamp of its last modification time. Each manipulation of an ontology returns +its new modification time. If the ontology has been modified before an update is submitted, the submitted modification time will +not fit and the modification is rejected. + +Many methods need the ontology IRI and the ontology name – the reason for this are performance issues which eliminate a round trip +to the Knora backend. #### get_existing_ontologies() -Get short information about all ontologies existing. -```python3 + +Get short information about all ontologies existing. + +```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 given project. + +```python +get_project_ontologies(project_code: str) -> Optional[dict] ``` -- project_code: Shortcode of project + +- project_code: Short code of project #### ontology_exists() -Test, if an ontology exists. -```python3 + +Tests if an ontology exists. + +```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 + +Get 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 + +Create 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" #### 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 + +Get the whole ontology as RDF (text/turtle). + +```python get_ontology_graph( - shortcode: str, - name: str) + shortcode: str, + name: str) ``` -- shortcode: Shortcode of the project + +- shortcode: Short code of the project - name: Name of the ontology #### create_res_class() -Create a new resource class in the ontology. -```python3 + +Create 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"}```. + +- onto_iri: IRI of the ontology the new resource class should be added to +- onto_name: Name of the ontology +- last_onto_date: Last modification time of ontology +- 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 specifics comments to 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. - 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 +- 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 (```{"en": "English label", "de": "Deutsches Label"```). +- gui_element: GUI element dependent on object (data type). They are a hint for a (generic) graphical 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. +- 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. #### 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. +- 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 (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 (recursively). Lists are 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 +- 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 note, otherwise the IRI of the parent list node (possibly the root note of the list). #### get_lists() + Get information about the lists of a given project -```python3 + +```python get_lists( -shortcode: str + shortcode: str ) -> Dict ``` -- shortcode: Shortcode of the project. + +- shortcode: Short code of the project. #### get_complete_list() + Get all the data (nodes) of a specific list -```python3 + +```python get_complete_list( -list_iri: str + list_iri: str ) -> Dict ``` + - 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 + +This Method is used to create a new instance of a given resource. All the data has to be passed to this function. + +```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. + +- 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 - 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 +- stillimage: In case the Resource is a descendant of StillImagerepresentation, this parameter is indicating where the uploaded + file is to be found. See below ##### 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 (standard mapping only allowed), then 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 Knora before its SillImageRepresentation 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 + +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(). + +```python create_schema( - shortcode: str, - shortname: str + shortcode: str, + shortname: str ) -> Dict ``` + - shortcode: Shortcode of the ontology - shortname: Shortname of the ontology #### reset_triplestore_content() -Empty the triple store. _Use with uttermost coution_ + +Empty the triple store. _Use with uttermost caution_ Used on local test servers to clean up the local backend. ## SIPI + Sipi is the IIIF conformant image backend. ### Methods of Sipi class #### Sipi() + Constructor for Sipi -```python3 + +```python Sipi( - sipiserver: str, - token: str + sipiserver: str, + token: str ) ``` + - sipiserver: URL of the SIPI server/endpoint - token: Access token from Knora + 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. ## Bulk import -The bulk import is used to import larger bunchs of data. + +The bulk import is used to import multiple resources at once. ### BulkImport -Thee Bulkimport class handles all bulk import stuff + +The BulkImport class handles the bulk import #### Bulkimport() -Constructor of a bulkimport instance -```python3 + +Constructor of a BulkImport instance + +```python Bulkimport( - schema: Dict + schema: Dict ) -> Bulkimport ``` + - schema: see create_schema() #### add_resource() + Add an instance to the bulk import. -```python3 + +```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. +- properties: Dict of property name/value pairs. #### upload() + Upload the data using the bulk import route. -```python3 + +```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 - +- port: Port number the Knora backend uses From 44593e0fdc2f9ddd88879b16c6c173b3cc8a6bcf Mon Sep 17 00:00:00 2001 From: irinaschubert Date: Mon, 13 Sep 2021 13:30:07 +0200 Subject: [PATCH 4/7] correct wrong integer values --- docs/dsp-tools-create.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/dsp-tools-create.md b/docs/dsp-tools-create.md index 1674545eb..1ad02f7f2 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 } } @@ -729,6 +729,7 @@ Please note that the DateValue is an extremely flexible data type. It can repres 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. - _calendar_ is either _GREGORIAN_ or _JULIAN_ @@ -792,7 +793,7 @@ A number with decimal point. }, "gui_element": "SimpleText", "gui_attributes": { - "maxlength": "255", + "maxlength": 255, "size": 80 } } @@ -872,8 +873,8 @@ Represents an integer value. - `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:* @@ -950,7 +951,7 @@ Represents an URI }, "gui_element": "SimpleText", "gui_attributes": { - "maxlength": "255", + "maxlength": 255, "size": 80 } } From 78ca91bbe0ae1be86907834f89ecede6c40d6aff Mon Sep 17 00:00:00 2001 From: irinaschubert Date: Tue, 14 Sep 2021 08:29:21 +0200 Subject: [PATCH 5/7] Update knora/README.md Co-authored-by: Balduin Landolt <33053745+BalduinLandolt@users.noreply.github.com> --- knora/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/knora/README.md b/knora/README.md index 9ae3c0c53..c920f6303 100644 --- a/knora/README.md +++ b/knora/README.md @@ -50,8 +50,8 @@ providing methods to create new ontologies and resources. ## 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 use Knora, the user has to submit +his/her credentials to the DSP API ### Basic methods From a0c289b50200b48cfbddcf3a1293ed650eeada88 Mon Sep 17 00:00:00 2001 From: irinaschubert Date: Tue, 14 Sep 2021 08:32:34 +0200 Subject: [PATCH 6/7] delete incorrect new line --- docs/dsp-tools-create.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/dsp-tools-create.md b/docs/dsp-tools-create.md index 1ad02f7f2..c1846e818 100644 --- a/docs/dsp-tools-create.md +++ b/docs/dsp-tools-create.md @@ -729,7 +729,6 @@ Please note that the DateValue is an extremely flexible data type. It can repres 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. - _calendar_ is either _GREGORIAN_ or _JULIAN_ From 6cdb17f831f74524c526ee041596edb10133558e Mon Sep 17 00:00:00 2001 From: irinaschubert Date: Tue, 14 Sep 2021 09:46:11 +0200 Subject: [PATCH 7/7] Update README.md --- knora/README.md | 237 ++++++++++++++++++++++++------------------------ 1 file changed, 116 insertions(+), 121 deletions(-) diff --git a/knora/README.md b/knora/README.md index c920f6303..035b5a9d6 100644 --- a/knora/README.md +++ b/knora/README.md @@ -1,7 +1,7 @@ # Knora Library -This library offers classes and methods to manipulate a Knora based repository. Most importantly, it allows importing data by -providing methods to create new ontologies and 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 @@ -50,14 +50,14 @@ providing methods to create new ontologies and resources. ## Knora -Knora is the base class which handles all the communication with the DSP API. In order to use Knora, the user has to submit -his/her credentials to the DSP API +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. +Creates an access object for the DSP API. ```python Knora( @@ -65,7 +65,7 @@ Knora( prefixes: Dict[str, str] = None) ``` -- server: URL of the Knora API server +- server: URL of the DSP server - prefixes: List of extra RDF prefixes that are being used Example: @@ -76,7 +76,7 @@ con = Knora(args.server) #### login() -This method performs a login and stored the access token. +Logs in the user and stores the access token. ```python login(email: str, password: str) @@ -93,7 +93,7 @@ con.login(args.user, args.password) #### logout() -This method is used to log out from Knora and remove the access token. +Logs out the user and removes the access token. ```python logout() @@ -107,17 +107,17 @@ con.logout() ### Project specific methods -The following methods are used to add and modify projects and users +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. +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 +- full: if False (default), only the project's IRI are returned, if True, more information about the projects are returned #### get_project() @@ -129,7 +129,7 @@ get_project(shortcode: str) -> dict #### project_exists() -Returns true if a project given by the IRI is existing in the repository. +Returns `True` if a project, given by its IRI, exists in the repository, `False` otherwise. ```python project_exists(proj_iri: str) -> bool @@ -151,17 +151,16 @@ create_project( logo: Optional[str] = None) -> str ``` -- shortcode: The Knora short code of the project +- 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 code (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. +Modifies existing project data. All parameters except the shortcode (which cannot be changed) are optional. ```python update_project( @@ -173,16 +172,16 @@ update_project( logo: Optional[str] = None) -> str ``` -- shortcode: The Knora short code of the project +- 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 code (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() @@ -190,13 +189,13 @@ get_users() #### get_user() -Get information about a specific user +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() @@ -212,7 +211,7 @@ create_user( lang: str = "en") ``` -- username: Username (short name) +- 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 @@ -221,7 +220,7 @@ create_user( #### add_user_to_project() -Add an existing user to a project. +Adds an existing user to a project. ```python add_user_to_project( @@ -230,22 +229,22 @@ add_user_to_project( ``` - 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 several instances could modify an ontology at the same time, a simple mechanism has been implemented to avoid race conditions: -Each modification of an ontology requires the timestamp of its last modification time. Each manipulation of an ontology returns -its new modification time. If the ontology has been modified before an update is submitted, the submitted modification time will -not fit and the modification is rejected. +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 methods need the ontology IRI and the ontology name – the reason for this are performance issues which eliminate a round trip -to the Knora backend. +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. +Returns information about all existing ontologies. ```python get_existing_ontologies() @@ -253,17 +252,17 @@ get_existing_ontologies() #### get_project_ontologies() -Returns the ontologies of a given project. +Returns the ontologies of a project given the project's IRI. ```python get_project_ontologies(project_code: str) -> Optional[dict] ``` -- project_code: Short code of project +- project_code: Shortcode of project #### ontology_exists() -Tests if an ontology exists. +Returns `True` if the ontology, given by its IRI, exists on the DSP. ```python ontology_exists(onto_iri: str) @@ -273,7 +272,7 @@ ontology_exists(onto_iri: str) #### get_ontology_lastmoddate() -Get the last modification date of a given ontology. +Returns the last modification date of a given ontology. ```python get_ontology_lastmoddate(self, onto_iri: str) @@ -283,7 +282,7 @@ get_ontology_lastmoddate(self, onto_iri: str) #### create_ontology() -Create a new ontology. +Creates a new ontology. ```python create_ontology( @@ -295,7 +294,7 @@ create_ontology( - 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() @@ -312,7 +311,7 @@ delete_ontology( #### get_ontology_graph() -Get the whole ontology as RDF (text/turtle). +Returns a given ontology as RDF (text/turtle). ```python get_ontology_graph( @@ -320,12 +319,12 @@ get_ontology_graph( name: str) ``` -- shortcode: Short code of the project +- shortcode: Shortcode of the project - name: Name of the ontology #### create_res_class() -Create a new resource class in the ontology. +Creates a new resource class in the ontology. ```python create_res_class( @@ -341,12 +340,12 @@ create_res_class( - onto_iri: IRI of the ontology the new resource class should be added to - onto_name: Name of the ontology -- last_onto_date: Last modification time of 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 +- 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 specifics comments to the resource class. +- 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() @@ -368,16 +367,15 @@ create_property( ) -> 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 (```{"en": "English label", "de": "Deutsches Label"```). -- gui_element: GUI element dependent on object (data type). They are a hint for a (generic) graphical user interface (e.g. SALSAH) - on how to display the field. Available GUI elements are: +- 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 @@ -394,23 +392,22 @@ create_property( - 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 +- 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, e.g. "TextValue", "IntValue" etc. (all value types supportted by Knora). The - following object types are supported by Knora: +- 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 (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. + - 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() @@ -427,19 +424,18 @@ create_cardinality( ) -> 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. -- occurrence: must be one of: "1", "0-1", "0-n" or "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 (recursively). -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() @@ -456,13 +452,14 @@ create_list_node( ``` - project_iri: The IRI of the project the list is associated with -- labels: Language dependent labels, e.g. ```{"en": "yes", "de": "nein"}```. +- 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 note, otherwise the IRI of the parent list node (possibly the root note of the list). +- 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 +Returns information about the lists of a given project. ```python get_lists( @@ -470,11 +467,11 @@ get_lists( ) -> Dict ``` -- shortcode: Short code of the project. +- shortcode: Shortcode of the project. #### get_complete_list() -Get all the data (nodes) of a specific list +Returns all nodes of a specific list. ```python get_complete_list( @@ -482,7 +479,7 @@ get_complete_list( ) -> Dict ``` -- list_iri: IRI of the list. +- list_iri: IRI of the list ### Creating instances @@ -490,7 +487,7 @@ 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. +Creates a new instance of a given resource. All parameters are required. ```python create_resource( @@ -502,14 +499,14 @@ create_resource( ) -> 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 found. 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 @@ -533,7 +530,7 @@ Dict of the following form: } ``` -_Note_: If the value is text with markup (standard mapping only allowed), then the value must be an instance of KnoraStandoffXml, +_Note_: If the value is text with markup (only standard mapping allowed), the value must be an instance of `KnoraStandoffXml`, e.g.: ```python @@ -548,7 +545,7 @@ e.g.: ##### Still image parameter: -A still image has to be uploaded to Knora before its SillImageRepresentation instance can be created: +A still image has to be uploaded to DSP before its `StillImageRepresentation` instance can be created: ```python sipi = Sipi(args.sipi, con.get_token()) @@ -568,9 +565,8 @@ an_image = con.create_resource(schema, #### 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(). +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( @@ -580,12 +576,11 @@ create_schema( ``` - 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 caution_ -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 @@ -595,7 +590,7 @@ Sipi is the IIIF conformant image backend. #### Sipi() -Constructor for Sipi +Creates a SIPI instance. ```python Sipi( @@ -605,7 +600,7 @@ Sipi( ``` - sipiserver: URL of the SIPI server/endpoint -- token: Access token from Knora +- token: Access token from DSP API Example: @@ -623,19 +618,19 @@ upload_image( ) -> 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 multiple resources at once. +The bulk import functionality is used to import multiple resources at once. ### BulkImport -The BulkImport class handles the bulk import +Handles the bulk import. #### Bulkimport() -Constructor of a BulkImport instance +Creates a Bulkimport instance ```python Bulkimport( @@ -643,11 +638,11 @@ Bulkimport( ) -> Bulkimport ``` -- schema: see create_schema() +- schema: See `create_schema()` #### add_resource() -Add an instance to the bulk import. +Adds an instance to the bulk import. ```python add_resource( @@ -658,14 +653,14 @@ add_resource( ) ``` -- 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 property name/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. +Uploads the data using the bulk import route of the DSP API. ```python upload( @@ -676,7 +671,7 @@ upload( ) ``` -- user: username +- user: Username - password: Password -- hostname: Hostname of Knora backend -- port: Port number the Knora backend uses +- hostname: Hostname of the DSP backend +- port: Port number the DSP backend uses