|
149 | 149 | "```python\n", |
150 | 150 | "from osw.express import OswExpress\n", |
151 | 151 | "\n", |
152 | | - "osw_obj = OswExpress(domain=\"wiki-dev.open-semantic-lab.org\")\n", |
| 152 | + "osw_obj = OswExpress(domain=\"demo.open-semantic-lab.org\")\n", |
153 | 153 | "\n", |
154 | 154 | "my_instance = MySubClass(\n", |
155 | 155 | " text=\"some text\",\n", |
|
219 | 219 | "\n", |
220 | 220 | "```bash\n", |
221 | 221 | "conda activate <your_environment> # optional\n", |
222 | | - "pip install osw-python\n", |
| 222 | + "pip install osw-python[tutorial]\n", |
223 | 223 | "```\n", |
| 224 | + "The option `[tutorial]` installs the library with the dependencies required for data import, like `deepl`, `geopy`\n", |
| 225 | + "and `openpyxl`.\n", |
224 | 226 | "\n", |
225 | 227 | "### From source\n", |
226 | 228 | "\n", |
|
232 | 234 | "git clone https://github.com/OpenSemanticLab/osw-python.git <target_directory>\n", |
233 | 235 | "cd <target_directory>\n", |
234 | 236 | "conda activate <your_environment> # optional\n", |
235 | | - "pip install [-e] .\n", |
| 237 | + "pip install [-e] .[tutorial]\n", |
236 | 238 | "```" |
237 | 239 | ] |
238 | 240 | }, |
|
292 | 294 | "cell_type": "code", |
293 | 295 | "source": [ |
294 | 296 | "# 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" |
296 | 298 | ], |
297 | 299 | "id": "509040ca218924ed", |
298 | 300 | "outputs": [], |
|
452 | 454 | "# Will run everytime the script is executed:\n", |
453 | 455 | "osw_obj.install_dependencies(dependencies)\n", |
454 | 456 | "\n", |
455 | | - "\n", |
456 | 457 | "# Static code checker will note 'Module not found' before the installation:\n", |
457 | 458 | "from osw.model.entity import Organization, Person, Room, Tutorial" |
458 | 459 | ], |
|
477 | 478 | "from typing import TYPE_CHECKING\n", |
478 | 479 | "from osw.express import import_with_fallback\n", |
479 | 480 | "\n", |
480 | | - "\n", |
481 | 481 | "# 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", |
484 | 483 | "\n", |
485 | 484 | "# Otherwise static code checker will note 'Module not found' before the installation:\n", |
486 | 485 | "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" |
488 | 487 | ], |
489 | 488 | "outputs": [], |
490 | 489 | "execution_count": null |
|
494 | 493 | "id": "40dc1839eeb1e503", |
495 | 494 | "metadata": {}, |
496 | 495 | "source": [ |
497 | | - "### Interact with an entity\n", |
| 496 | + "## Interact with an entity\n", |
498 | 497 | "\n", |
499 | 498 | "Data classes created by the code generator are based on Pydantic models, which provide validation and serialization.\n", |
500 | 499 | "\n", |
501 | | - "#### Creating an entity\n", |
| 500 | + "### Creating an entity\n", |
502 | 501 | "\n", |
503 | 502 | "To create an entity, you need to create an instance of the respective data class. The `__init__` method of the data \n", |
504 | 503 | "class expects keyword arguments for all fields. As per usual for Pydantic models, positional arguments are not \n", |
|
512 | 511 | "source": [ |
513 | 512 | "# Create a person\n", |
514 | 513 | "john = Person(\n", |
| 514 | + " name=\"John Doe\",\n", |
515 | 515 | " first_name=\"John\",\n", |
516 | 516 | " last_name=\"Doe\",\n", |
517 | 517 | " email=\"john.doe@example.com\"\n", |
|
544 | 544 | "source": [ |
545 | 545 | "# Should run without validation errors\n", |
546 | 546 | "john = Person(\n", |
| 547 | + " name=\"John Doe\",\n", |
547 | 548 | " first_name=\"John\",\n", |
548 | 549 | " surname=\"Doe\",\n", |
549 | 550 | " email=[\"john.doe@example.com\"],\n", |
|
557 | 558 | "id": "9aa534b206d8b486", |
558 | 559 | "metadata": {}, |
559 | 560 | "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." |
562 | 563 | ] |
563 | 564 | }, |
564 | 565 | { |
565 | 566 | "cell_type": "code", |
566 | 567 | "id": "d861fde54918bc05", |
567 | 568 | "metadata": {}, |
568 | 569 | "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", |
572 | 572 | "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())" |
575 | 575 | ], |
576 | 576 | "outputs": [], |
577 | 577 | "execution_count": null |
|
581 | 581 | "id": "f6dace23bf99c7f3", |
582 | 582 | "metadata": {}, |
583 | 583 | "source": [ |
584 | | - "#### Storing an entity\n", |
| 584 | + "### Storing an entity\n", |
585 | 585 | "\n", |
586 | 586 | "We can now store this entity in the OSL instance. The `store_entity` method uploads the entity to the OSL instance. " |
587 | 587 | ] |
|
595 | 595 | "# In this specific case equivalent to:\n", |
596 | 596 | "params = OswExpress.StoreEntityParam(\n", |
597 | 597 | " entities=[john],\n", |
598 | | - " namespace=get_namespace(john),\n", |
| 598 | + " namespace=john.get_namespace(),\n", |
599 | 599 | " parallel=False,\n", |
600 | 600 | " overwrite=\"keep existing\",\n", |
601 | 601 | " overwrite_per_class=None,\n", |
|
624 | 624 | "id": "639db64348bbd905", |
625 | 625 | "metadata": {}, |
626 | 626 | "source": [ |
627 | | - "#### Downloading an entity\n", |
| 627 | + "### Downloading an entity\n", |
628 | 628 | "\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", |
630 | 630 | "entity from the OSL instance and returns an instance of the respective data class. If the respective data class is \n", |
631 | 631 | "not already part of `osw.model.entity`, the data class is generated on-the-fly by default." |
632 | 632 | ] |
|
635 | 635 | "cell_type": "code", |
636 | 636 | "id": "ea1da2ff6d96808a", |
637 | 637 | "metadata": {}, |
638 | | - "source": [ |
639 | | - "john2 = osw_obj.load_entity(get_full_title(john))" |
640 | | - ], |
| 638 | + "source": "john2 = osw_obj.load_entity(john.get_iri())", |
641 | 639 | "outputs": [], |
642 | 640 | "execution_count": null |
643 | 641 | }, |
|
679 | 677 | "id": "d140b974b54155ce", |
680 | 678 | "metadata": {}, |
681 | 679 | "source": [ |
682 | | - "#### Modifying an entity\n", |
| 680 | + "### Modifying an entity\n", |
683 | 681 | "\n", |
684 | 682 | "To modify an entity, you can change the attributes of the entity instance. The attributes can be accessed and modified \n", |
685 | 683 | "like any other attribute of a Python object." |
|
691 | 689 | "metadata": {}, |
692 | 690 | "source": [ |
693 | 691 | "# Adding a new attribute\n", |
694 | | - "john2.middle_name = \"R.\"\n", |
| 692 | + "john2.middle_name = {\"R.\"}\n", |
695 | 693 | "# Changing an existing attribute \n", |
| 694 | + "john2.name = \"John R. Doe\"\n", |
696 | 695 | "john2.email = {\"john.doe@gmx.de\"}\n", |
697 | 696 | "\n", |
698 | 697 | "# Checking the made changes:\n", |
|
701 | 700 | "outputs": [], |
702 | 701 | "execution_count": null |
703 | 702 | }, |
| 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 | + }, |
704 | 740 | { |
705 | 741 | "cell_type": "markdown", |
706 | 742 | "id": "f42c1600ed17a059", |
707 | 743 | "metadata": {}, |
708 | 744 | "source": [ |
709 | | - "#### Storing an altered entity\n", |
| 745 | + "### Storing an altered entity\n", |
710 | 746 | "\n", |
711 | 747 | "Here the same applies as for [Storing an entity](#Storing-an-entity). BUT: overwriting entities is not possible with \n", |
712 | 748 | "default settings \"keep existing\". Therefore, you need to call the method `store_entity` passing a StoreEntityParam with \n", |
713 | 749 | "the attribute `overwrite` set to \"overwrite\".\n" |
714 | 750 | ] |
715 | 751 | }, |
| 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 | + }, |
716 | 763 | { |
717 | 764 | "metadata": {}, |
718 | 765 | "cell_type": "code", |
719 | 766 | "source": [ |
720 | 767 | "# 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))" |
722 | 769 | ], |
723 | 770 | "id": "77b507f13be1235b", |
724 | 771 | "outputs": [], |
|
730 | 777 | "source": [ |
731 | 778 | "# Option 2: Overwrite only entities of type Person\n", |
732 | 779 | "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)]))" |
734 | 781 | ], |
735 | 782 | "id": "19d4d48e95e0fe82", |
736 | 783 | "outputs": [], |
|
742 | 789 | "source": [ |
743 | 790 | "# Option 3: Overwrite only the email attribute of entities of type Person\n", |
744 | 791 | "osw_obj.store_entity(OSW.StoreEntityParam(\n", |
745 | | - " entities=[john2], overwrite_per_class=[\n", |
| 792 | + " entities=entities2store, overwrite_per_class=[\n", |
746 | 793 | " OSW.OverwriteClassParam(model=Person, overwrite=False,per_property={\"email\": True})]))" |
747 | 794 | ], |
748 | 795 | "id": "4fc037a10f95356a", |
|
777 | 824 | "metadata": {}, |
778 | 825 | "cell_type": "markdown", |
779 | 826 | "source": [ |
780 | | - "### Interact with files \n", |
| 827 | + "## Interact with files \n", |
781 | 828 | "\n", |
782 | | - "#### Download a file\n", |
| 829 | + "### Download a file\n", |
783 | 830 | "\n", |
784 | 831 | "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", |
785 | 832 | "available. (Execute the Upload a file section to upload a file to the OSL instance.) You can download the file with \n", |
|
793 | 840 | "source": [ |
794 | 841 | "from osw.express import osw_download_file\n", |
795 | 842 | "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", |
797 | 844 | " # , use_cached=True # Can be used to download the file only once, e.g., when developing code\n", |
798 | 845 | " # , overwrite=True # Can be used to avoid overwriting an existing file\n", |
799 | 846 | ")" |
|
825 | 872 | "cell_type": "code", |
826 | 873 | "source": [ |
827 | 874 | "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", |
829 | 876 | ") as file:\n", |
| 877 | + " file.open(\"r\")\n", |
830 | 878 | " print(file.read())" |
831 | 879 | ], |
832 | 880 | "id": "ff674c1413ca6b4b", |
|
837 | 885 | "metadata": {}, |
838 | 886 | "cell_type": "markdown", |
839 | 887 | "source": [ |
840 | | - "#### Round-Robin\n", |
| 888 | + "### Round-Robin\n", |
841 | 889 | "\n", |
842 | 890 | "Let's create a file, upload it to the OSL instance, download it and read and alter its content, before uploading it \n", |
843 | 891 | "again.\n" |
|
885 | 933 | "cell_type": "code", |
886 | 934 | "source": [ |
887 | 935 | "# 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" |
889 | 938 | ], |
890 | 939 | "id": "9647b490f90d2a0d", |
891 | 940 | "outputs": [], |
|
895 | 944 | "metadata": {}, |
896 | 945 | "cell_type": "markdown", |
897 | 946 | "source": [ |
898 | | - "### Interface data sources\n", |
| 947 | + "## Interface data sources\n", |
899 | 948 | "\n", |
900 | | - "#### Tabular data: Excel, CSV and others\n", |
| 949 | + "### Tabular data: Excel, CSV and others\n", |
901 | 950 | "\n", |
902 | 951 | "Let's create a demo table and save it to an Excel file. " |
903 | 952 | ], |
|
1008 | 1057 | " \"Email\": \"email\"\n", |
1009 | 1058 | "}\n", |
1010 | 1059 | "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", |
1011 | 1062 | "# Let's have a look at the first row\n", |
1012 | 1063 | "john_dict = data_df.iloc[0].to_dict()\n", |
1013 | 1064 | "print(john_dict)" |
|
1074 | 1125 | " self.first_name = self.FirstName\n", |
1075 | 1126 | " self.surname = self.LastName\n", |
1076 | 1127 | " 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", |
1077 | 1137 | " return True\n", |
1078 | 1138 | "\n", |
1079 | 1139 | "# Let's create a new instance of the PersonHelper class\n", |
|
0 commit comments