{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Managing Files\n",
    "\n",
    "This notebook shows how you can manage files with the ThanoSQL library. We will cover how to upload files, get file information, and delete files.\n",
    "First, initialize a ThanoSQL client with your API token and engine URL."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from thanosql import ThanoSQL\n",
    "\n",
    "client = ThanoSQL(\n",
    "    api_token=\"THANOSQL_API_TOKEN\",\n",
    "    engine_url=\"THANOSQL_ENGINE_URL\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Uploading Files and Creating Folders"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can upload files from your local computer to your ThanoSQL workspace. By default, files will be uploaded to the user data root. You can use the `path` parameter to specify another folder location relative to the user data root. If the directory does not exist, the API call will return an error."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dir_path = \"path/to/existing/workspace/dir\"\n",
    "file_path = \"path/to/local/my_file.jpeg\"\n",
    "res = client.file.create(dir_path, file_path)\n",
    "assert res.content_info.name == \"my_file\"\n",
    "assert res.content_info.type == \"file\"\n",
    "assert res.content_info.path == \"path/to/existing/workspace/dir/my_file.jpeg\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use this API to create an empty folder. If the second parameter (`file`) is not set, an empty folder with the specified `path` will be created."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_dir_path = \"path/to/new/folder\"\n",
    "res = client.file.create(new_dir_path)\n",
    "assert res.content_info.name == \"folder\"\n",
    "assert res.content_info.type == \"directory\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Listing and Downloading Files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can get the list of files in a directory under the user data root using the `get()` function. By default, the function will list the contents of the user data root."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "res = client.file.get()\n",
    "res.content_info.content"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also specify the path to a target file or directory. Note that this function is not recursive; files inside subdirectories will not be listed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "client.file.get(\"path/to/existing/workspace/dir/my_file.jpeg\")\n",
    "# will output\n",
    "#\n",
    "# Content({\n",
    "#    \"content_info\": {\n",
    "#       \"name\": \"my_file\",\n",
    "# ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`get` can also be used to download files from your workspace to your local machine. You only need to specify \"download\" in the `option` parameter. Directory download is currently not supported."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "client.file.get(\"path/to/existing/workspace/dir/my_file.jpeg\", option=\"download\")\n",
    "# will output nothing except <Response [204]>, but my_file.jpeg will be downloaded to the current local directory"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Deleting Files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also delete files and directories from your workspace using the client. Note that deleting a directory will also delete all contents inside it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "client.file.delete(\"path/to/new/folder\")"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}