{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Workspace\n",
    "=========\n",
    "\n",
    "The core element of a project is the ``Workspace``. A project Workspace holds core information about the author, version and all entities stored in the `geoh5` file. It also knows how to create the core structure needed by [Geoscience ANALYST](https://mirageoscience.com/mining-industry-software/geoscience-analyst/) for visualization.\n",
    "\n",
    "![workspace](./images/workspace.png)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creation\n",
    "\n",
    "You can create a blank workspace with the `.create` method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from geoh5py.workspace import Workspace\n",
    "\n",
    "# Create a new project\n",
    "workspace = Workspace.create(\"my_project.geoh5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![blankworkspace](./images/blankworkspace.png){width=\"50%\"}\n",
    "\n",
    "Et voila!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Opening and closing\n",
    "\n",
    "You can open an existing project by simply entering the desired file name on instantiation of the `Workspace` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "workspace = Workspace(\"my_project.geoh5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the `geoh5` file already exists on disk, the API will open the file and import the tree structure."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **Deprecation Warning**\n",
    "> In future releases, the implicite creation of a new Workspace from a file path will be deprecated. Users will be required\n",
    "> to use the `save()` method to explicitely write a file to disk."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, the `*.geoh5` file is accessed in \"read-write\" mode. In the eventuality that the file is already used by Geoscience ANALYST, the mode gets changed to \"read-only\". This prevents users from modifying the file while used in an active session, but still allows them to extract data from the workspace. The same restriction does not apply to multiple python processes, as permitted by the `Single Writer Multiple Reader (SWMR)` feature of HDF5."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(workspace.geoh5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After completing the read/write process, the workspace must be closed in order to release the file. Geoscience ANALYST does not allow reading on an opened file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "workspace.close()\n",
    "\n",
    "print(workspace._geoh5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Context manager\n",
    "\n",
    "Likewise, a workspace can be accessed via a context manager (the prefered way), which will handle closing the file at the of a process."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with Workspace(\"my_project.geoh5\") as workspace:\n",
    "    print(workspace.geoh5)\n",
    "    \n",
    "print(workspace._geoh5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## In-memory\n",
    "\n",
    "Starting from v0.8.0, it is possible to interact with a `Workspace` in memory. Users can omit to provide a path to an `h5file`, in which case the project is save as a `io.BytesIO` object. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "in_memory = Workspace()\n",
    "print(in_memory.h5file)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Likewise, an existing `geoh5` project stored as `io.BytesIO` can be provided directly. The example below shows how to read a `geoh5` as a raw byte object, then converted to a `io.BytesIO` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from io import BytesIO\n",
    "\n",
    "with open(\"my_project.geoh5\", \"rb\") as in_file:\n",
    "    byte_data = in_file.read()\n",
    "\n",
    "bytes_ws = Workspace(BytesIO(byte_data))\n",
    "\n",
    "print(bytes_ws.h5file)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `save` method can be used to convert the in-memory project to a file on disk. Users must provide a file name with path."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bytes_ws.save(\"./new_project.geoh5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After saving to disk, the `h5file` attribute is converted to a `Path` with reference to the `geoh5` structure on disk."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(bytes_ws.h5file)"
   ]
  }
 ],
 "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.9.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}