Skip to content

Commit 0ae37ca

Browse files
committed
Rework tutorial notebook to incorporate tests and feedback, as well as latest fixes and improvements
1 parent 557866f commit 0ae37ca

2 files changed

Lines changed: 101 additions & 39 deletions

File tree

‎docs/tutorials/basics.ipynb‎

Lines changed: 99 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@
149149
"```python\n",
150150
"from osw.express import OswExpress\n",
151151
"\n",
152-
"osw_obj = OswExpress(domain=\"wiki-dev.open-semantic-lab.org\")\n",
152+
"osw_obj = OswExpress(domain=\"demo.open-semantic-lab.org\")\n",
153153
"\n",
154154
"my_instance = MySubClass(\n",
155155
" text=\"some text\",\n",
@@ -219,8 +219,10 @@
219219
"\n",
220220
"```bash\n",
221221
"conda activate <your_environment> # optional\n",
222-
"pip install osw-python\n",
222+
"pip install osw-python[tutorial]\n",
223223
"```\n",
224+
"The option `[tutorial]` installs the library with the dependencies required for data import, like `deepl`, `geopy`\n",
225+
"and `openpyxl`.\n",
224226
"\n",
225227
"### From source\n",
226228
"\n",
@@ -232,7 +234,7 @@
232234
"git clone https://github.com/OpenSemanticLab/osw-python.git <target_directory>\n",
233235
"cd <target_directory>\n",
234236
"conda activate <your_environment> # optional\n",
235-
"pip install [-e] .\n",
237+
"pip install [-e] .[tutorial]\n",
236238
"```"
237239
]
238240
},
@@ -292,7 +294,7 @@
292294
"cell_type": "code",
293295
"source": [
294296
"# Define the wiki_domain for later reuse:\n",
295-
"wiki_domain = \"wiki-dev.open-semantic-lab.org\" # Replace with the domain of your OSL instance"
297+
"wiki_domain = \"demo.open-semantic-lab.org\" # Replace with the domain of your OSL instance"
296298
],
297299
"id": "509040ca218924ed",
298300
"outputs": [],
@@ -452,7 +454,6 @@
452454
"# Will run everytime the script is executed:\n",
453455
"osw_obj.install_dependencies(dependencies)\n",
454456
"\n",
455-
"\n",
456457
"# Static code checker will note 'Module not found' before the installation:\n",
457458
"from osw.model.entity import Organization, Person, Room, Tutorial"
458459
],
@@ -477,14 +478,12 @@
477478
"from typing import TYPE_CHECKING\n",
478479
"from osw.express import import_with_fallback\n",
479480
"\n",
480-
"\n",
481481
"# Will fetch and install dependencies only if not already installed:\n",
482-
"import_with_fallback(dependencies)\n",
483-
"\n",
482+
"import_with_fallback(dependencies, globals(), domain=wiki_domain)\n",
484483
"\n",
485484
"# Otherwise static code checker will note 'Module not found' before the installation:\n",
486485
"if TYPE_CHECKING:\n",
487-
" from osw.model.entity import Organization, Person, Room, Tutorial"
486+
" from osw.model.entity import Description, Label, Organization, Person, Room, Tutorial"
488487
],
489488
"outputs": [],
490489
"execution_count": null
@@ -494,11 +493,11 @@
494493
"id": "40dc1839eeb1e503",
495494
"metadata": {},
496495
"source": [
497-
"### Interact with an entity\n",
496+
"## Interact with an entity\n",
498497
"\n",
499498
"Data classes created by the code generator are based on Pydantic models, which provide validation and serialization.\n",
500499
"\n",
501-
"#### Creating an entity\n",
500+
"### Creating an entity\n",
502501
"\n",
503502
"To create an entity, you need to create an instance of the respective data class. The `__init__` method of the data \n",
504503
"class expects keyword arguments for all fields. As per usual for Pydantic models, positional arguments are not \n",
@@ -512,6 +511,7 @@
512511
"source": [
513512
"# Create a person\n",
514513
"john = Person(\n",
514+
" name=\"John Doe\",\n",
515515
" first_name=\"John\",\n",
516516
" last_name=\"Doe\",\n",
517517
" email=\"john.doe@example.com\"\n",
@@ -544,6 +544,7 @@
544544
"source": [
545545
"# Should run without validation errors\n",
546546
"john = Person(\n",
547+
" name=\"John Doe\",\n",
547548
" first_name=\"John\",\n",
548549
" surname=\"Doe\",\n",
549550
" email=[\"john.doe@example.com\"],\n",
@@ -557,21 +558,20 @@
557558
"id": "9aa534b206d8b486",
558559
"metadata": {},
559560
"source": [
560-
"Before storing the entity in the OSL instance, lets check at which full page title it will be stored. \n",
561-
"The full page title is derived from the `uuid` and the `namespace` of the entity."
561+
"Before storing the entity in the OSL instance, lets check at which IRI (full page title) it will be stored.\n",
562+
"The IRI is derived from the `uuid` and the `namespace` of the entity."
562563
]
563564
},
564565
{
565566
"cell_type": "code",
566567
"id": "d861fde54918bc05",
567568
"metadata": {},
568569
"source": [
569-
"from osw.utils.wiki import get_namespace, get_osw_id, get_full_title\n",
570-
"\n",
571-
"print(\"Namespace:\", get_namespace(john))\n",
570+
"print(\"Page name:\", john.name)\n",
571+
"print(\"Namespace:\", john.get_namespace())\n",
572572
"print(\"UUID:\", john.uuid)\n",
573-
"print(\"OSW-ID:\", get_osw_id(john.uuid))\n",
574-
"print(\"Full title:\", get_full_title(john))"
573+
"print(\"OSW-ID:\", john.get_osw_id())\n",
574+
"print(\"IRI:\", john.get_iri())"
575575
],
576576
"outputs": [],
577577
"execution_count": null
@@ -581,7 +581,7 @@
581581
"id": "f6dace23bf99c7f3",
582582
"metadata": {},
583583
"source": [
584-
"#### Storing an entity\n",
584+
"### Storing an entity\n",
585585
"\n",
586586
"We can now store this entity in the OSL instance. The `store_entity` method uploads the entity to the OSL instance. "
587587
]
@@ -595,7 +595,7 @@
595595
"# In this specific case equivalent to:\n",
596596
"params = OswExpress.StoreEntityParam(\n",
597597
" entities=[john],\n",
598-
" namespace=get_namespace(john),\n",
598+
" namespace=john.get_namespace(),\n",
599599
" parallel=False,\n",
600600
" overwrite=\"keep existing\",\n",
601601
" overwrite_per_class=None,\n",
@@ -624,9 +624,9 @@
624624
"id": "639db64348bbd905",
625625
"metadata": {},
626626
"source": [
627-
"#### Downloading an entity\n",
627+
"### Downloading an entity\n",
628628
"\n",
629-
"To download an entity, you need to provide the full page title of the entity. The `download_entity` method downloads the\n",
629+
"To download an entity, you need to provide the IRI of the entity. The `download_entity` method downloads the\n",
630630
"entity from the OSL instance and returns an instance of the respective data class. If the respective data class is \n",
631631
"not already part of `osw.model.entity`, the data class is generated on-the-fly by default."
632632
]
@@ -635,9 +635,7 @@
635635
"cell_type": "code",
636636
"id": "ea1da2ff6d96808a",
637637
"metadata": {},
638-
"source": [
639-
"john2 = osw_obj.load_entity(get_full_title(john))"
640-
],
638+
"source": "john2 = osw_obj.load_entity(john.get_iri())",
641639
"outputs": [],
642640
"execution_count": null
643641
},
@@ -679,7 +677,7 @@
679677
"id": "d140b974b54155ce",
680678
"metadata": {},
681679
"source": [
682-
"#### Modifying an entity\n",
680+
"### Modifying an entity\n",
683681
"\n",
684682
"To modify an entity, you can change the attributes of the entity instance. The attributes can be accessed and modified \n",
685683
"like any other attribute of a Python object."
@@ -691,8 +689,9 @@
691689
"metadata": {},
692690
"source": [
693691
"# Adding a new attribute\n",
694-
"john2.middle_name = \"R.\"\n",
692+
"john2.middle_name = {\"R.\"}\n",
695693
"# Changing an existing attribute \n",
694+
"john2.name = \"John R. Doe\"\n",
696695
"john2.email = {\"john.doe@gmx.de\"}\n",
697696
"\n",
698697
"# Checking the made changes:\n",
@@ -701,24 +700,72 @@
701700
"outputs": [],
702701
"execution_count": null
703702
},
703+
{
704+
"metadata": {},
705+
"cell_type": "code",
706+
"source": [
707+
"# Let's create an organization and link it to the person\n",
708+
"org = Organization(\n",
709+
" name=\"Doe, Inc.\",\n",
710+
" label=[Label(text=\"Doe, Inc.\")],\n",
711+
" description=[Description(text=\"The John Doe Company\")],\n",
712+
" manager=[john2.get_iri()]\n",
713+
")\n",
714+
"# And another one that is linked to both the person and the first organization\n",
715+
"org2 = Organization(\n",
716+
" name=\"Doe Group, Inc.\",\n",
717+
" label=[Label(text=\"Doe Group, Inc.\")],\n",
718+
" description=[Description(text=\"The Doe Group\")],\n",
719+
" manager=[john2.get_iri()],\n",
720+
" member_ous=[org.get_iri()]\n",
721+
")"
722+
],
723+
"id": "b4425d8e6b1cbe62",
724+
"outputs": [],
725+
"execution_count": null
726+
},
727+
{
728+
"metadata": {},
729+
"cell_type": "markdown",
730+
"source": [
731+
"Here we have created links between Entities for the first time. The `get_iri` method returns the full title of the to\n",
732+
" be created page(s), which replaces the pointers Python use where ever you reference an object by variable. JSON has\n",
733+
" to use resolvable IRIs to realize this reference.\n",
734+
"\n",
735+
"Note: We are already working on a feature to automatically resolve these references, so you can use the Python\n",
736+
"pointers in the future!"
737+
],
738+
"id": "df52cc2f7dd2f13"
739+
},
704740
{
705741
"cell_type": "markdown",
706742
"id": "f42c1600ed17a059",
707743
"metadata": {},
708744
"source": [
709-
"#### Storing an altered entity\n",
745+
"### Storing an altered entity\n",
710746
"\n",
711747
"Here the same applies as for [Storing an entity](#Storing-an-entity). BUT: overwriting entities is not possible with \n",
712748
"default settings \"keep existing\". Therefore, you need to call the method `store_entity` passing a StoreEntityParam with \n",
713749
"the attribute `overwrite` set to \"overwrite\".\n"
714750
]
715751
},
752+
{
753+
"metadata": {},
754+
"cell_type": "code",
755+
"source": [
756+
"# Define entities to be stored\n",
757+
"entities2store = [john2, org, org2]"
758+
],
759+
"id": "a7f9540af0850525",
760+
"outputs": [],
761+
"execution_count": null
762+
},
716763
{
717764
"metadata": {},
718765
"cell_type": "code",
719766
"source": [
720767
"# Option 1: Overwrite all entities\n",
721-
"osw_obj.store_entity(OSW.StoreEntityParam(entities=[john2], overwrite=True))"
768+
"osw_obj.store_entity(OSW.StoreEntityParam(entities=entities2store, overwrite=True))"
722769
],
723770
"id": "77b507f13be1235b",
724771
"outputs": [],
@@ -730,7 +777,7 @@
730777
"source": [
731778
"# Option 2: Overwrite only entities of type Person\n",
732779
"osw_obj.store_entity(OSW.StoreEntityParam(\n",
733-
" entities=[john2], overwrite_per_class=[OSW.OverwriteClassParam(model=Person, overwrite=True)]))"
780+
" entities=entities2store, overwrite_per_class=[OSW.OverwriteClassParam(model=Person, overwrite=True)]))"
734781
],
735782
"id": "19d4d48e95e0fe82",
736783
"outputs": [],
@@ -742,7 +789,7 @@
742789
"source": [
743790
"# Option 3: Overwrite only the email attribute of entities of type Person\n",
744791
"osw_obj.store_entity(OSW.StoreEntityParam(\n",
745-
" entities=[john2], overwrite_per_class=[\n",
792+
" entities=entities2store, overwrite_per_class=[\n",
746793
" OSW.OverwriteClassParam(model=Person, overwrite=False,per_property={\"email\": True})]))"
747794
],
748795
"id": "4fc037a10f95356a",
@@ -777,9 +824,9 @@
777824
"metadata": {},
778825
"cell_type": "markdown",
779826
"source": [
780-
"### Interact with files \n",
827+
"## Interact with files \n",
781828
"\n",
782-
"#### Download a file\n",
829+
"### Download a file\n",
783830
"\n",
784831
"Let's say you have already uploaded a file to the instance of OSL you are connected to and have the URL to the file \n",
785832
"available. (Execute the Upload a file section to upload a file to the OSL instance.) You can download the file with \n",
@@ -793,7 +840,7 @@
793840
"source": [
794841
"from osw.express import osw_download_file\n",
795842
"local_file = osw_download_file(\n",
796-
" \"https://wiki-dev.open-semantic-lab.org/wiki/File:OSWaa635a571dfb4aa682e43b98937f5dd3.pdf\"\n",
843+
" \"https://demo.open-semantic-lab.org/wiki/File:OSW98a720defe8349cab010ca1fc3528aee.pdf\",\n",
797844
" # , use_cached=True # Can be used to download the file only once, e.g., when developing code\n",
798845
" # , overwrite=True # Can be used to avoid overwriting an existing file\n",
799846
")"
@@ -825,8 +872,9 @@
825872
"cell_type": "code",
826873
"source": [
827874
"with osw_download_file(\n",
828-
" \"https://wiki-dev.open-semantic-lab.org/wiki/File:OSWac9224e1a280449dba71d945b1581d57.txt\", overwrite=True\n",
875+
" \"https://demo.open-semantic-lab.org/wiki/File:OSW2c08f45151ee4b518485ed68cf73c5e5.txt\", overwrite=True\n",
829876
") as file:\n",
877+
" file.open(\"r\")\n",
830878
" print(file.read())"
831879
],
832880
"id": "ff674c1413ca6b4b",
@@ -837,7 +885,7 @@
837885
"metadata": {},
838886
"cell_type": "markdown",
839887
"source": [
840-
"#### Round-Robin\n",
888+
"### Round-Robin\n",
841889
"\n",
842890
"Let's create a file, upload it to the OSL instance, download it and read and alter its content, before uploading it \n",
843891
"again.\n"
@@ -885,7 +933,8 @@
885933
"cell_type": "code",
886934
"source": [
887935
"# Delete WikiFile from OSW instance after you are done with it\n",
888-
"wiki_file.delete()"
936+
"wiki_file.delete()\n",
937+
"# Error: InsufficientPermission, if you do not have the required rights"
889938
],
890939
"id": "9647b490f90d2a0d",
891940
"outputs": [],
@@ -895,9 +944,9 @@
895944
"metadata": {},
896945
"cell_type": "markdown",
897946
"source": [
898-
"### Interface data sources\n",
947+
"## Interface data sources\n",
899948
"\n",
900-
"#### Tabular data: Excel, CSV and others\n",
949+
"### Tabular data: Excel, CSV and others\n",
901950
"\n",
902951
"Let's create a demo table and save it to an Excel file. "
903952
],
@@ -1008,6 +1057,8 @@
10081057
" \"Email\": \"email\"\n",
10091058
"}\n",
10101059
"data_df.rename(columns=mapping, inplace=True)\n",
1060+
"# Auto create the name\n",
1061+
"data_df[\"name\"] = data_df[\"first_name\"] + \" \" + data_df[\"surname\"]\n",
10111062
"# Let's have a look at the first row\n",
10121063
"john_dict = data_df.iloc[0].to_dict()\n",
10131064
"print(john_dict)"
@@ -1074,6 +1125,15 @@
10741125
" self.first_name = self.FirstName\n",
10751126
" self.surname = self.LastName\n",
10761127
" self.email = {self.Email}\n",
1128+
" self.name = f\"{self.first_name} {self.surname}\"\n",
1129+
" if self.middle_name:\n",
1130+
" self.name = f\"{self.first_name} {self.middle_name} {self.surname}\"\n",
1131+
" return True\n",
1132+
"\n",
1133+
" def transform_references(self, dd: dict = None) -> bool:\n",
1134+
" super().transform_references()\n",
1135+
" if self.organization:\n",
1136+
" self.organization = set([org.get_iri() for org in self.organization])\n",
10771137
" return True\n",
10781138
"\n",
10791139
"# Let's create a new instance of the PersonHelper class\n",

‎setup.cfg‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,8 @@ dataimport =
9191
openpyxl
9292
UI =
9393
pysimplegui
94+
tutorial =
95+
%(dataimport)s
9496
all =
9597
%(dataimport)s
9698
%(DB)s

0 commit comments

Comments
 (0)