{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c2e79c7c-cc3e-47ff-a85c-78f500ff63f7",
   "metadata": {},
   "source": [
    "# Creating HDF files\n",
    "\n",
    "To work with HDF5 files, the \"wrapper\"-class `File` is used (equivalent to `h5py.File`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "f0ec5083-bfc0-46b9-9627-299cbd842838",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "using(\"h5py\")"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import h5rdmtoolbox as h5tbx\n",
    "h5tbx.use(None)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0e73ec28-d197-4086-ba25-766c188befbf",
   "metadata": {},
   "source": [
    "Creating a file does not require filename. If not specified, a **temporary file is created**. In this case the file-`mode` is `r+`, otherwise and if not specified, the default opening mode is `r` (read-only):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "3b363c60-21f7-408f-89b6-7fc9a77a6d3b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tmp0.hdf\n"
     ]
    }
   ],
   "source": [
    "# init file object with a temporary file:\n",
    "h5 = h5tbx.File()\n",
    "\n",
    "# create a dataset\n",
    "h5.create_dataset('velocity', data=1.3)\n",
    "\n",
    "# close the file object\n",
    "h5.close()\n",
    "\n",
    "# print the filename\n",
    "print(h5.hdf_filename.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36e23915-bc58-406f-85aa-7c77cae44937",
   "metadata": {},
   "source": [
    "Note, that the `h5rdmtoolbox` introduces `hdf_filename` to the `File`-object. This allows you to access the filename even if the file has been closed already. This is not possible with `h5py`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "91fbac7b-de16-451b-a498-ef5af6f88529",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Not a file or file object (not a file or file object)\n",
      "tmp0.hdf\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    print(h5.filename)\n",
    "except ValueError as e:\n",
    "    print(e)\n",
    "print(h5.hdf_filename.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e4edf0d-afac-4c22-af5c-8c83852d3a13",
   "metadata": {},
   "source": [
    "**A safer way to work with files** is to use python's context manager. This is highly recommended and used throughout the hole documentation and package.\n",
    "\n",
    "Thus, the above cell changes to:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "34b7e026-3f38-494c-bd86-17c786c3ecbb",
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "test.hdf\n"
     ]
    }
   ],
   "source": [
    "with h5tbx.File('test.hdf', 'w') as h5:\n",
    "    print(h5.hdf_filename.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48435b36-4615-4418-83fd-da302b937f80",
   "metadata": {},
   "source": [
    "Note: To inspect the file content, please visit the [file content visualization notebook](DumpFile.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d0d7a409-9a18-4ec6-8406-8a63f68b0cac",
   "metadata": {},
   "source": [
    "As stated above, the `hdf_filename` is a `pathlib.Path` object, which gives much more possibilities to work with the file, among many, deleting the file is very simple:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "58c032e2-f964-4d2b-bdfd-6666a66948a8",
   "metadata": {},
   "outputs": [],
   "source": [
    "h5.hdf_filename.unlink()"
   ]
  }
 ],
 "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.8.19"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}