Skip to content
Permalink
Browse files
fix(docs): fix example in documentation (DSP-1740) (#99)
* fix documentation

* reformat files
  • Loading branch information
irinaschubert committed Sep 21, 2021
1 parent 18964d1 commit 11cdd72911e41d837a99579caf0d9d799b0360fc
Showing with 53 additions and 51 deletions.
  1. +3 −3 docs/dsp-tools-excel.md
  2. +10 −10 docs/dsp-tools-usage.md
  3. +4 −4 docs/index.md
  4. +1 −1 knora/dsplib/models/resource.py
  5. +1 −1 knora/dsplib/utils/expand_all_lists.py
  6. +34 −32 knora/knora.py
@@ -25,9 +25,9 @@ For further information about resources, see [here](./dsp-tools-create.md#resour

## Create the properties for a data model from an Excel file

With dsp-tools the `properties` section used in a data model (JSON) can be created from an Excel file. Only the first worksheet of
the Excel file is considered and only XLSX files are allowed. The `properties` section can be inserted into the ontology file and
then be uploaded onto a DSP server.
With dsp-tools the `properties` section used in a data model (JSON) can be created from an Excel file. Only the first
worksheet of the Excel file is considered and only XLSX files are allowed. The `properties` section can be inserted into
the ontology file and then be uploaded onto a DSP server.

The Excel sheet must have the following format:
![img-properties-example.png](assets/images/img-properties-example.png)
@@ -56,7 +56,7 @@ The following options are available:
- `-s` | `--server` _server_: URL of the DSP server (default: localhost:3333)
- `-u` | `--user` _username_: username used for authentication with the DSP API (default: root@example.com)
- `-p` | `--password` _password_: password used for authentication with the DSP API (default: test)
- `-P` | `--project` _shortcode_ | _shortname_ | _iri_: shortcode, shortname or
- `-P` | `--project` _shortcode_ | _shortname_ | _iri_: shortcode, shortname or (mandatory)
[IRI](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier) of the project
- `-v` | `--verbose`: If set, some information about the progress is printed to the console.

@@ -66,7 +66,7 @@ model from a DSP server `https://api.dsl.server.org` provided with the `-s` opti
the password `test` are used. The data model is saved into the output file `output_file.json`.

```bash
dsp-tools get -s https://api.dsl.server.org -u root@example.com -p test output_file.json
dsp-tools get -s https://api.dsl.server.org -u root@example.com -p test -P my_project output_file.json
```

## Upload data to a DSP server
@@ -128,11 +128,11 @@ found [here](./dsp-tools-excel.md#create-a-list-from-one-or-several-excel-files)
dsp-tools excel2resources excel_file.xlsx output_file.json
```

The command is used to create the resources section of an ontology from an Excel file. Therefore, an Excel file has to be provided
with the data in the first worksheet of the Excel file.
The command is used to create the resources section of an ontology from an Excel file. Therefore, an Excel file has to
be provided with the data in the first worksheet of the Excel file.

The following example shows how to create the resources section from an Excel file called `Resources.xlsx`. The output is written
to a file called `resources.json`.
The following example shows how to create the resources section from an Excel file called `Resources.xlsx`. The output
is written to a file called `resources.json`.

```bash
dsp-tools excel2resources Resources.xlsx resources.json
@@ -148,11 +148,11 @@ found [here](./dsp-tools-excel.md#create-the-resources-for-a-data-model-from-an-
dsp-tools excel2properties excel_file.xlsx output_file.json
```

The command is used to create the properties section of an ontology from an Excel file. Therefore, an Excel file has to be
provided with the data in the first worksheet of the Excel file.
The command is used to create the properties section of an ontology from an Excel file. Therefore, an Excel file has to
be provided with the data in the first worksheet of the Excel file.

The following example shows how to create the properties section from an Excel file called `Properties.xlsx`. The output is
written to a file called `properties.json`.
The following example shows how to create the properties section from an Excel file called `Properties.xlsx`. The output
is written to a file called `properties.json`.

```bash
dsp-tools excel2properties Properties.xlsx properties.json
@@ -24,9 +24,9 @@ dsp-tools helps you with the following tasks:
creates a JSON or XML file from one or several Excel files. The created data can either be integrated into an ontology
or be uploaded directly to a DSP server with `dsp-tools create`.
- [`dsp-tools excel2resources`](./dsp-tools-usage.md#create-resources-from-an-excel-file)
creates the ontology's resource section from an Excel file. The resulting section can be integrated into an ontology and then be
uploaded to a DSP server with `dsp-tools create`.
creates the ontology's resource section from an Excel file. The resulting section can be integrated into an ontology
and then be uploaded to a DSP server with `dsp-tools create`.
- [`dsp-tools excel2properties`](./dsp-tools-usage.md#create-properties-from-an-excel-file)
creates the ontology's properties section from an Excel file. The resulting section can be integrated into an ontology and then
be uploaded to a DSP server with `dsp-tools create`.
creates the ontology's properties section from an Excel file. The resulting section can be integrated into an ontology
and then be uploaded to a DSP server with `dsp-tools create`.

@@ -100,7 +100,7 @@ def __init__(self,
self._values[propname] = []
for val in vals:
if valcnt > 0 and (
propinfo.cardinality == Cardinality.C_0_1 or propinfo.cardinality == Cardinality.C_1):
propinfo.cardinality == Cardinality.C_0_1 or propinfo.cardinality == Cardinality.C_1):
raise BaseError(f'Cardinality does not allow multiple values for "{propname}"!')
if type(val) is Value:
self._values[propname].append(val)
@@ -20,7 +20,7 @@ def expand_lists_from_excel(data_model: Dict) -> List[str]:
for rootnode in lists:
# check if the folder parameter is used
if rootnode.get('nodes') is not None and isinstance(rootnode['nodes'], dict) and rootnode['nodes'].get(
'folder') is not None:
'folder') is not None:
# get the Excel files from the folder and crate the rootnode of the list
excel_folder = rootnode['nodes']['folder']
rootnode, excel_files = prepare_list_creation(excel_folder, rootnode.get('name'))
@@ -1,16 +1,16 @@
from typing import List, Set, Dict, Tuple, Optional, Any, Union
from urllib.parse import quote_plus
from rdflib import Graph
from lxml import etree
import requests
import json
import urllib
import pprint
import validators
import re
from rfc3987 import parse
import urllib
from pprint import pprint
import sys
from typing import List, Dict, Optional, Any, Union
from urllib.parse import quote_plus

import requests
import validators
from lxml import etree
from rdflib import Graph
from rfc3987 import parse

# TODO: recheck all the documentation of this file
"""
@@ -225,13 +225,13 @@ def project_exists(self, proj_iri: str) -> bool:
return proj_iri in projects

def create_project(
self,
shortcode: str,
shortname: str,
longname: str,
descriptions: Optional[Dict[str, str]] = None,
keywords: Optional[List[str]] = None,
logo: Optional[str] = None) -> str:
self,
shortcode: str,
shortname: str,
longname: str,
descriptions: Optional[Dict[str, str]] = None,
keywords: Optional[List[str]] = None,
logo: Optional[str] = None) -> str:
"""
Create a new project
@@ -273,13 +273,13 @@ def create_project(
return res["project"]["id"]

def update_project(
self,
shortcode: str,
shortname: Optional[str] = None,
longname: Optional[str] = None,
descriptions: Optional[Dict[str, str]] = None,
keywords: Optional[List[str]] = None,
logo: Optional[str] = None) -> str:
self,
shortcode: str,
shortname: Optional[str] = None,
longname: Optional[str] = None,
descriptions: Optional[Dict[str, str]] = None,
keywords: Optional[List[str]] = None,
logo: Optional[str] = None) -> str:
"""
Update project information
@@ -416,7 +416,8 @@ def create_group(self,

groupinfo = {
"name": name,
"description": description if isinstance(description, str) else list(map(lambda p: {"@language": p[0], "@value": p[1]}, description.items())),
"description": description if isinstance(description, str) else list(
map(lambda p: {"@language": p[0], "@value": p[1]}, description.items())),
"project": project_iri,
"status": status,
"selfjoin": selfjoin
@@ -454,7 +455,8 @@ def update_group(self,
groupinfo['name'] = name
done = True
if description is not None:
groupinfo['description'] = description if isinstance(description, str) else list(map(lambda p: {"@language": p[0], "@value": p[1]}, description.items()))
groupinfo['description'] = description if isinstance(description, str) else list(
map(lambda p: {"@language": p[0], "@value": p[1]}, description.items()))
done = True
if selfjoin is not None:
groupinfo['selfjoin'] = selfjoin
@@ -609,7 +611,7 @@ def create_user(self,
def update_user(self,
user_iri: str,
username: Optional[str] = None,
email: Optional[str] = None,
email: Optional[str] = None,
given_name: Optional[str] = None,
family_name: Optional[str] = None,
password: Optional[str] = None,
@@ -662,8 +664,8 @@ def add_user_to_project(self,
:param project_iri: IRI of the project
:return: None
"""
url = self.server + '/admin/users/iri/' + quote_plus(user_iri) + '/project-memberships/'\
+ quote_plus(project_iri)
url = self.server + '/admin/users/iri/' + quote_plus(user_iri) + '/project-memberships/' \
+ quote_plus(project_iri)
req = requests.post(url, headers={'Authorization': 'Bearer ' + self.token})
self.on_api_error(req)

@@ -1990,22 +1992,22 @@ def process_properties(propinfo: Dict, valuestr: any):
# first we check if the cardinality allows to add this property
if properties.get(prop_info["propname"]) is None: # this property-value is missing
if prop_info["card"] == 'cardinality' \
and prop_info["cardval"] == 1:
and prop_info["cardval"] == 1:
raise KnoraError(
resclass + " requires exactly one " + prop_info["propname"] + "-value: none supplied!")
if prop_info["card"] == 'minCardinality' \
and prop_info["cardval"] == 1:
and prop_info["cardval"] == 1:
raise KnoraError(
resclass + " requires at least one " + prop_info["propname"] + "-value: none supplied!")
continue
if type(properties[prop_info["propname"]]) is list:
if len(properties[prop_info["propname"]]) > 1:
if prop_info["card"] == 'maxCardinality' \
and prop_info["cardval"] == 1:
and prop_info["cardval"] == 1:
raise KnoraError(
resclass + " allows maximal one " + prop_info["propname"] + "-value: several supplied!")
if prop_info["card"] == 'cardinality' \
and prop_info["cardval"] == 1:
and prop_info["cardval"] == 1:
raise KnoraError(
resclass + " requires exactly one " + prop_info["propname"] + "-value: several supplied!")
for p in properties[prop_info["propname"]]:

0 comments on commit 11cdd72

Please sign in to comment.