{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2fb45dc8-5690-4499-be73-0f8998677db3",
   "metadata": {},
   "source": [
    "# Managing resources"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10bf4104-d2a3-4b2a-af8c-1921c99fa6c9",
   "metadata": {},
   "source": [
    "Controlling a web browser with Selenium requires several components:\n",
    "\n",
    "- a browser installed on the machine you are working on. This is the application that controlled by Selenium.\n",
    "- a driver that makes the links between the installed application and your code. The driver allows Selenium to control the browser with commands you provide.\n",
    "\n",
    "A good management on these components is essential to ensure the stability of your application. It can be easy to handle all of that in a dev environment but managing your resources in production can be trickier.\n",
    "\n",
    "`manen` provides several functions and classes whose purpose is to provide simple interfaces to manage browsers and drivers."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4b361669-f3c7-411a-91c4-606db22ea78b",
   "metadata": {},
   "source": [
    "## An API around your browsers and drivers\n",
    "\n",
    "Each browser has its own sub-package (defined in `manen.resource`), each one of them providing at least two classes:\n",
    "\n",
    "- `application`, implementing some methods in order to get the status of the installed browser.\n",
    "- `driver` which is a class used as interface with the driver resources, enabling to list and download any drivers available online.\n",
    "\n",
    "For now, only two browsers are fully supported by `manen`: Google Chrome and Brave.\n",
    "The support for other browsers such as Firefox is planned in the coming release.\n",
    "\n",
    "In the following example, we will work with Chrome."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "a1de2a32-12e2-4263-ad55-c01ad1acc507",
   "metadata": {},
   "outputs": [],
   "source": [
    "from manen.resource import chrome"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80976e3c-1234-407a-af71-d87fa2260521",
   "metadata": {},
   "source": [
    "Thanks to the `application` class, we can check that the browser is correctly installed and retrieve the current version."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "d3c6876d-fff1-4560-9fd4-04d3582c55f4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(98, 0, 4758, 102)"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assert chrome.application.is_installed()\n",
    "chrome_version = chrome.application.installed_version()\n",
    "chrome_version"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7571f92b-ee29-45a1-bac0-8aae6d1091f8",
   "metadata": {},
   "source": [
    "`manen` also provides the same interface for the browser Brave."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "88128f4f-9c56-4984-84e6-08293cfece1a",
   "metadata": {},
   "outputs": [],
   "source": [
    "from manen.resource import brave"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "f312d5fe-e983-4600-a94d-3135e5121e24",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(98, 1, 35, 101)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assert brave.application.is_installed()\n",
    "brave_version = brave.application.installed_version()\n",
    "brave_version"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "882eb00e-f4e9-4bf6-ad7b-e7f1ba024c37",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "ℹ All browser resource managers provided by <code>manen</code> will have slightly the same interface, and can be imported using the same path `manen.resource.{browser_name}`.\n",
    "</div>\n",
    "\n",
    "Thanks to the `application` interface, we checked that the first component needed to work with Selenium (the browser) is correctly installed.\n",
    "\n",
    "Let's interact with the second component: the driver. First step will be to list all the versions for the Chromedriver assets available online. To restrict the number of results, we will focus on the versions matching the installed version of Google Chrome."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "ae7dc599-365d-4d91-87f2-7adba43e15ae",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'version': (97, 0, 4692, 20),\n",
       "  'name': 'chromedriver_mac64.zip',\n",
       "  'updated_at': '2021-11-19T10:02:37.708Z',\n",
       "  'size': 8258658},\n",
       " {'version': (97, 0, 4692, 36),\n",
       "  'name': 'chromedriver_mac64.zip',\n",
       "  'updated_at': '2021-12-03T08:12:33.544Z',\n",
       "  'size': 8277983},\n",
       " {'version': (97, 0, 4692, 71),\n",
       "  'name': 'chromedriver_mac64.zip',\n",
       "  'updated_at': '2022-01-05T05:45:13.182Z',\n",
       "  'size': 8277283}]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "available_drivers = chrome.driver.list_versions(query='97.0.4692')\n",
    "available_drivers"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c246d868-f89a-42f4-a92c-f9cc6bad606a",
   "metadata": {},
   "source": [
    "You can also use the method `latest_release` to get the version number of the last chromedriver available. If Google Chrome is fully updated, you will be able to use this version to control the browser."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "3ec03bf0-5cfb-4b77-a3df-aaba16b884e7",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(98, 0, 4758, 102)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "latest_release = chrome.driver.latest_release()\n",
    "latest_release"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "652c4d7b-7122-4069-a9db-2920dae3188d",
   "metadata": {},
   "source": [
    "Now that we have a version of the Chromedriver compatible with our installed Chrome, let's download the binary file in order to be able to use it locally with Selenium. The drivers resource manager provides a method that will fetch the chromedriver archive and unzip it.\n",
    "\n",
    "Once downloaded, the driver will be stored in a folder inside `manen` directory, with the following path:\n",
    "```\n",
    "{manen_directory}/assets/drivers/{platform}/{browser}/{version}/{driver_name}\n",
    "```\n",
    "where:\n",
    "\n",
    "- `manen_directory` can be obtained with `manen.resource.local.LocalAsset.PATH`\n",
    "- `platform` is specific to the OS of the machine (for example on a Mac, it will be \"darwin\")\n",
    "- `version` is the version of the driver requested\n",
    "- `driver_name` is the name of the downloaded driver (\"chromedriver\" for Google Chrome and Brave)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "eab148a3-77ea-41b3-9fbc-db4dbbf5f106",
   "metadata": {},
   "outputs": [],
   "source": [
    "# A function to hide the path that is specific to each environment\n",
    "import re\n",
    "obfuscate = lambda path: re.sub('/Users/.*?/manen/', '/***/', path)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "04e7eb8f-8d52-444c-880c-51311e02fc9c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'/***/manen/assets/drivers/darwin/chrome/98.0.4758.102/chromedriver'"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "chromedriver_path = chrome.driver.download(version=latest_release)\n",
    "obfuscate(chromedriver_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d4c7691-8906-45f3-9b43-6bb5705e80ea",
   "metadata": {},
   "source": [
    "The download will always retrieve the file online; if the driver has already been downloaded, you can instead use the method `get`. This method will first check that the driver is not available locally and, if not, download it.\n",
    "\n",
    "For example, the following command will check if the last release for the Chromedriver 97.\\*.\\*.\\* is available in the local file sytem and download it if not. In any case, it returns the chromedriver path, that should be specified when instaciating a WebDriver."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "d0347459-d948-4074-9a08-419eb4ba2a09",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'/***/manen/assets/drivers/darwin/chrome/97.0.4692.71/chromedriver'"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "chromedriver_path = chrome.driver.get(query='97')\n",
    "obfuscate(chromedriver_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29dfc52d-0efc-4342-8ef7-d1e2900cb14e",
   "metadata": {},
   "source": [
    "Once downloaded, you can retrieved all the installed files using `manen.resource.local.LocalAsset`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "c76ee5dc-b6a8-4965-8129-e6dfdb3b7c50",
   "metadata": {},
   "outputs": [],
   "source": [
    "from manen.resource.local import LocalAsset as local"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "011dab95-770e-4bf2-8c57-6c407a3a4441",
   "metadata": {},
   "outputs": [],
   "source": [
    "obfuscate = lambda item: {**item, 'path': re.sub('/Users/.*?/manen/', '/***/', item['path'])}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "fcedbfa5-8f06-4c10-bec4-3bda87686a98",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'path': '/***/manen/assets/drivers/darwin/chrome/98.0.4758.102/chromedriver',\n",
       "  'version': '98.0.4758',\n",
       "  'browser': 'chrome',\n",
       "  'os': 'darwin'},\n",
       " {'path': '/***/manen/assets/drivers/darwin/chrome/97.0.4692.71/chromedriver',\n",
       "  'version': '97.0.4692',\n",
       "  'browser': 'chrome',\n",
       "  'os': 'darwin'}]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "[obfuscate(item) for item in local.list_drivers(browser='chrome')]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9fd74653-8d7f-4083-a69e-07d56967adb4",
   "metadata": {},
   "source": [
    "## Using the CLI"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b28ac791-9646-4649-8b4e-623aced7133a",
   "metadata": {},
   "source": [
    "The download of browser drivers can be done through `manen` CLI instead of using classes `driver`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "1c55d9ea-6752-400c-bd37-3d22e620b97a",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "usage: manen driver download [-h] [-i] [-b {chrome,brave}] [-p {Darwin,Linux}]\n",
      "                             [-v VERSION [VERSION ...]]\n",
      "\n",
      "Download one or several drivers for a specific browser on a given OS.\n",
      "\n",
      "optional arguments:\n",
      "  -h, --help            show this help message and exit\n",
      "  -i, --interactive     Set the specifications for the download through a\n",
      "                        serie of interactive questions. If specified, the\n",
      "                        options of the specifications group must not be set.\n",
      "\n",
      "specifications:\n",
      "  -b {chrome,brave}, --browser {chrome,brave}\n",
      "                        Browser that will be used to launch the Selenium/manen\n",
      "                        application.\n",
      "  -p {Darwin,Linux}, --platform {Darwin,Linux}\n",
      "                        Platform (OS) on which the driver binary will run.\n",
      "                        Note that 'Darwin' is for MacOS and you can use the\n",
      "                        alias 'Mac' for this OS.\n",
      "  -v VERSION [VERSION ...], --version VERSION [VERSION ...]\n",
      "                        List of driver versions to be downloaded\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "manen driver download -h"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "09815af9-bd0f-42a7-b849-17c3687b71cd",
   "metadata": {},
   "source": [
    "Let's download all the drivers we need with the CLI. At the end, the drivers will be available at the same location as it was downloaded through the API."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d0218dcf-826b-4792-9f61-4563545eab63",
   "metadata": {},
   "source": [
    "```shell\n",
    "$ manen driver download -i\n",
    "» Starting interactive CLI to download webdrivers...\n",
    "? What is your OS? Mac OS\n",
    "? For which browser do you want to download the drivers? Chrome / Brave\n",
    "? Choose the version you want to download. (Use arrow keys to move, <space> to select, <a> to toggle, <i> to invert)\n",
    "   ○ 95.0.4638.17\n",
    "   ○ 95.0.4638.54\n",
    "   ○ 95.0.4638.69\n",
    "   ○ 96.0.4664.18\n",
    "   ○ 96.0.4664.35\n",
    "   ○ 96.0.4664.45\n",
    "   ● 97.0.4692.20 (compatible with Chrome)\n",
    "   ● 97.0.4692.36 (compatible with Chrome)\n",
    " » ● 97.0.4692.71 (compatible with Chrome)\n",
    "   ○ 98.0.4758.48\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0355fe9",
   "metadata": {},
   "source": []
  }
 ],
 "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}