{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quickstart\n",
    "\n",
    "## Using the File API Client\n",
    "\n",
    "Using the notebook utilities provided by `evo-sdk-common` you can easily interact with the File API in a Jupyter notebook environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evo.notebooks import ServiceManagerWidget\n",
    "\n",
    "manager = await ServiceManagerWidget.with_auth_code(\n",
    "    client_id=\"your-client-id\",\n",
    "    cache_location=\"./notebook-data\",\n",
    ").login()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## FileAPIClient\n",
    "\n",
    "The `FileAPIClient` wraps endpoint functionality to provide a cohesive interface to the underlying API client implementation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evo.files import FileAPIClient\n",
    "\n",
    "connector = manager.get_connector()\n",
    "\n",
    "file_client = FileAPIClient.from_context(manager)\n",
    "service_health = await file_client.get_service_health()\n",
    "\n",
    "print(f\"File API is {service_health.status.name.lower()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### List files\n",
    "\n",
    "Listing content is simple, just call the `FileAPIClient.list_files()` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "offset = 0\n",
    "while True:\n",
    "    page = await file_client.list_files(offset=offset, limit=10)\n",
    "    if offset == 0:\n",
    "        print(f\"Found {page.total} file{'' if page.total == 1 else 's'}\")\n",
    "    for file in page:\n",
    "        print(f\"{file.path}: ({file.id}) Version: {file.version_id}\")\n",
    "    if page.is_last:\n",
    "        break\n",
    "    offset = page.next_offset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evo.files import FileMetadata\n",
    "\n",
    "service_files = await file_client.list_all_files(limit_per_request=50)\n",
    "\n",
    "\n",
    "# Pretty print all files.\n",
    "def display_files(files: list[FileMetadata]):\n",
    "    n_files = len(files)\n",
    "    print(f\"Found {n_files} file{'' if n_files == 1 else 's'}\")\n",
    "    for file in files:\n",
    "        print(f\"{file.path}: ({file.id}) Version: {file.version_id}\")\n",
    "\n",
    "\n",
    "display_files(service_files)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Upload/update a file by path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "path = \"points.csv\"\n",
    "\n",
    "# Prepare an upload context by path.\n",
    "ctx = await file_client.prepare_upload_by_path(path)\n",
    "\n",
    "# Use the upload context to upload the file.\n",
    "await ctx.upload_from_path(\"data/points.csv\", connector.transport)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get a file by path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the FileMetadata\n",
    "points = await file_client.get_file_by_path(path)\n",
    "print(f\"Found {points.path}: UUID({points.id}) Version:{points.version_id}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get the versions of the file by path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "versions = await file_client.list_versions_by_path(path)\n",
    "print(f\"Versions found for {path}:\")\n",
    "for version in versions:\n",
    "    print(version.version_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Download a specific version by path and version ID"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a specific version by path and version ID. Change the list index to pick a different version.\n",
    "version_id = versions[0].version_id\n",
    "print(f\"Fetching version {version_id}\")\n",
    "points_version = await file_client.get_file_by_path(path, version_id=version_id)\n",
    "print(f\"Found {points_version.path}: UUID({points_version.id}) Version:{points_version.version_id}\")\n",
    "\n",
    "print(\"---\")\n",
    "\n",
    "# Download the version\n",
    "print(f\"Downloading version {version_id}\")\n",
    "\n",
    "# Prepare a download by path and version ID.\n",
    "ctx = await file_client.prepare_download_by_path(path, version_id=version_id)\n",
    "\n",
    "# Use the download context to download the file.\n",
    "file_location = await ctx.download_to_cache(manager.cache, connector.transport)\n",
    "print(f\"File downloaded to {str(file_location)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Delete a file by path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evo.common.exceptions import NotFoundException\n",
    "\n",
    "await file_client.delete_file_by_path(path)\n",
    "try:\n",
    "    points = await file_client.get_file_by_path(path)\n",
    "    print(\"File was not deleted!\")\n",
    "except NotFoundException:\n",
    "    print(\"File deleted successfully\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Find ID of a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# List items and copy one of the file IDs\n",
    "file_id = service_files[0].id\n",
    "print(file_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get a file by ID"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get points and versions by ID\n",
    "points = await file_client.get_file_by_id(file_id)\n",
    "print(f\"Found {points.path}: ({points.id}) Version: {points.version_id}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get the versions of the file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "versions = await file_client.list_versions_by_id(file_id)\n",
    "print(f\"Versions found for {file_id}:\")\n",
    "for version in versions:\n",
    "    print(version.version_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Download a specific version by ID and version ID"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a specific version by ID and version ID\n",
    "version_id = versions[0].version_id\n",
    "print(f\"Fetching version {version_id}\")\n",
    "points_version = await file_client.get_file_by_id(file_id, version_id=version_id)\n",
    "print(f\"Found {points_version.path}: UUID({points_version.id}) Version:{points_version.version_id}\")\n",
    "\n",
    "print(\"---\")\n",
    "\n",
    "# Download version\n",
    "print(f\"Downloading version {version_id}\")\n",
    "\n",
    "# Prepare a download context with the file ID and version ID\n",
    "ctx = await file_client.prepare_download_by_id(file_id, version_id=version_id)\n",
    "\n",
    "# Use the download context to download the file\n",
    "file_location = await ctx.download_to_cache(manager.cache, connector.transport)\n",
    "print(f\"File downloaded to {str(file_location)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Update a file by ID"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prepare an upload context using the file ID\n",
    "# The file ID must already exist in the service\n",
    "ctx = await file_client.prepare_upload_by_id(file_id)\n",
    "\n",
    "# Use the upload context to upload the file\n",
    "await ctx.upload_from_path(\"data/points.csv\", connector.transport)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Delete a file by ID"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evo.common.exceptions import GoneException\n",
    "\n",
    "await file_client.delete_file_by_id(file_id)\n",
    "try:\n",
    "    points = await file_client.get_file_by_id(file_id)\n",
    "    print(\"File was not deleted!\")\n",
    "except GoneException:\n",
    "    print(\"File deleted successfully\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## API documentation\n",
    "\n",
    "For more information about the File API, visit the [Seequent developer portal](https://developer.seequent.com/docs/guides/file)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "evo-python-sdk",
   "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.10.18"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
