ISSUE-298 Create 'getting started' notebook

.github/workflows/build.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4 # Required to mount the Github Workspace to a volume
+        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
       - name: Lint OpenAPI Specification
         uses: addnab/docker-run-action@v3
         with:
@@ -25,6 +25,36 @@ jobs:
           run: |
             lint-openapi --warnings-limit 0 openapi.yaml
             exit $?
+  notebook_lint:
+    name: Lint Jupyter Notebook(s)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout`
+        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+      - name: Lint Jupyter Notebook(s)
+        uses: ResearchSoftwareActions/EnsureCleanNotebooksAction@1.1
+  notebook_test:
+    name: Test notebook(s)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+      - name: Launch tagbase-server stack via docker-compose
+        uses: isbang/compose-action@v1.5.1
+        with:
+          compose-file: "./docker-compose.yml"
+        env:
+          CUSTOM_VARIABLE: "test"
+          PGADMIN_DEFAULT_EMAIL: "tagtuna@gmail.com"
+          PGADMIN_DEFAULT_PASSWORD: "tagbase"
+          POSTGRES_PASSWORD: "tagbase"
+          POSTGRES_PORT: "5432"
+      - name: Setup Python
+        uses: actions/setup-python@v4
+      - name: Install dependencies
+        run: pip install pytest nbmake
+      - name: Run nbmake
+        run: pytest --nbmake ./examples/getting_started.ipynb
   sonarcloud:
     name: SonarCloud Analysis
     runs-on: ubuntu-latest

examples/getting_started.ipynb

@@ -0,0 +1,165 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Welcome to the [tagbase-server](https://github.com/tagbase/tagbase-server) developer getting started guide\n",
+    "\n",
+    "![Tagbase](https://github.com/tagbase/tagbase/wiki/images/tagbase.gif \"Tagbase\")\n",
+    "\n",
+    "# Purpose\n",
+    "\n",
+    "This notebook will demonstrate how **[pytagbase](https://github.com/tagbase/pytagbase)** can be used to programmatically interact with **[tagbase-server](https://github.com/tagbase/tagbase-server)** using the Python programming language.\n",
+    "\n",
+    "# Credits\n",
+    "\n",
+    "The data used in this notebook is credited as follows\n",
+    "\n",
+    "**O’Sullivan, J., Lowe, C.G., Sosa-Nishizaki, O. et al. A biologging database of juvenile white sharks from the northeast Pacific. Sci Data 9, 142 (2022). https://doi.org/10.1038/s41597-022-01235-3**. The below screenshots give an idea of the juvenile white shark tracks from the northeast Pacific.\n",
+    "\n",
+    "![Time Overlap](./ex1_timeoverlap.png \"Time Overlap\")\n",
+    "\n",
+    "![Recovered Tags](./ex2_recoveredtags.png \"Recovered Tags\")\n",
+    "\n",
+    "# Prerequisites\n",
+    "\n",
+    "* [Jupyter notebook](https://jupyter.org/install)\n",
+    "* [Docker Compose](https://docs.docker.com/compose/)\n",
+    "\n",
+    "# Learning outcomes\n",
+    "\n",
+    "By the end of the notebook, you will have learned how to...\n",
+    "* install **[pytagbase](https://github.com/tagbase/pytagbase)**; the Python SDK for tagbase-server\n",
+    "* execute some important functions offered by tagbase-server such as *data ingestion* and *acquiring information about tags*\n",
+    "\n",
+    "# More examples and documentation\n",
+    "\n",
+    "See the [documentation for API endpoints](https://github.com/tagbase/pytagbase#documentation-for-api-endpoints)\n",
+    "\n",
+    "# Support and issue tracking\n",
+    "\n",
+    "Please [get in touch with the project community](https://github.com/tagbase/tagbase-server/issues) if you have any problems using this notebook or would like to see other examples.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# testcontainers helps with setting up tagbase-server\n",
+    "!pip install testcontainers\n",
+    "\n",
+    "# Install pytagbase from source\n",
+    "!pip install git+https://github.com/tagbase/pytagbase.git"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from testcontainers.compose import DockerCompose\n",
+    "\n",
+    "\n",
+    "def ingest_file(api_instance, file_path, notes, type, version):\n",
+    "    \"\"\"\n",
+    "    Get network accessible file and execute ingestion\n",
+    "    \"\"\"\n",
+    "    try:\n",
+    "        api_response = api_instance.ingest_get(file_path, notes, type, version)\n",
+    "        print(\"The response of IngestApi->ingest_get:\\n\")\n",
+    "        pprint(api_response)\n",
+    "    except ApiException as e:\n",
+    "        print(\"Exception when calling IngestApi->ingest_get: %s\\n\" % e)\n",
+    "\n",
+    "\n",
+    "with DockerCompose(\".\", compose_file_name=[\"../docker-compose.yml\"]) as compose:\n",
+    "    compose._call_command(['docker-compose', 'build', '--build-arg', 'NGINX_PASS=\"tagbase\"', '--build-arg', 'NGINX_USER=\"tagbase\"', '--build-arg', 'POSTGRES_PASSWORD=\"tagbase\"', '--build-arg', 'POSTGRES_PORT=\"5432\"'])\n",
+    "    compose.start()\n",
+    "    stdout, stderr = compose.get_logs()\n",
+    "    if stderr:\n",
+    "        print(\"Errors\\n:{}\".format(stderr))\n",
+    "    \n",
+    "\n",
+    "    # Let the system properly initialize\n",
+    "    import time\n",
+    "    time.sleep(60)\n",
+    "    \n",
+    "    import pytagbase\n",
+    "    from pytagbase.rest import ApiException\n",
+    "    from pprint import pprint\n",
+    "    \n",
+    "    # Defining the host is optional and defaults to https://localhost/tagbase/api/v0.14.0\n",
+    "    # See configuration.py for a list of all supported configuration parameters.\n",
+    "    configuration = pytagbase.Configuration(\n",
+    "        host = \"https://localhost/tagbase/api/v0.14.0\",\n",
+    "        password = \"tagbase\",\n",
+    "        username = \"tagbase\",\n",
+    "    )\n",
+    "    # Need to bypass self-signed TLS certificates\n",
+    "    configuration.__setattr__(\"verify_ssl\", False)\n",
+    "    \n",
+    "    # Enter a context with an instance of the API client\n",
+    "    with pytagbase.ApiClient(configuration) as api_client:\n",
+    "        # Create an instance of the IngestApi class\n",
+    "        ingest_api_instance = pytagbase.IngestApi(api_client)\n",
+    "        file = 'file:///usr/src/app/tagbase_server/test/data/etuff/jws_19_19_ArgosTrans_eTUFF0.txt' # str | Location of a network accessible (file, ftp, http, https) file e.g. 'file:///usr/src/app/data/eTUFF-sailfish-117259.txt'.\n",
+    "        notes = 'Ingestion performed via getting_started Jupyter Notebook' # str | Free-form text field where details of submitted eTUFF file for ingest can be provided e.g. submitter name, etuff data contents (tag metadata and measurements + primary position data, or just secondary solution-positional meta/data) (optional)\n",
+    "        type = 'etuff' # str | Type of file to be ingested, defaults to 'etuff' (optional) (default to 'etuff')\n",
+    "        version = '1' # str | Version identifier for the eTUFF tag data file ingested (optional)\n",
+    "\n",
+    "        # Ingest one eTUFF file\n",
+    "        ingest_file(ingest_api_instance, file, notes, type, version)\n",
+    "        time.sleep(10)\n",
+    "\n",
+    "        # Create an instance of the TagsApi class\n",
+    "        tags_api_instance = pytagbase.TagsApi(api_client)\n",
+    "        try:\n",
+    "            # Get information about all tags\n",
+    "            api_response = tags_api_instance.list_tags()\n",
+    "            print(\"\\nThe response of TagsApi->list_tags:\\n\")\n",
+    "            pprint(api_response)\n",
+    "        except Exception as e:\n",
+    "            print(\"Exception when calling TagsApi->list_tags: %s\\n\" % e)\n",
+    "\n",
+    "        file2 = 'file:///usr/src/app/tagbase_server/test/data/etuff/jws_19_15_ArgosTrans_eTUFF0.txt'\n",
+    "        # Ingest another eTUFF file\n",
+    "        ingest_file(ingest_api_instance, file2, notes, type, version)\n",
+    "        time.sleep(10)\n",
+    "        \n",
+    "        tag_id = 2 # int | Existing tag id\n",
+    "        try:\n",
+    "            # Get information about the second file\n",
+    "            api_response = tags_api_instance.get_tag(tag_id)\n",
+    "            print(\"\\nThe response of TagsApi->get_tag:\\n\")\n",
+    "            pprint(api_response)\n",
+    "        except Exception as e:\n",
+    "            print(\"Exception when calling TagsApi->get_tag: %s\\n\" % e)\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}