ialdev-core 0.1.0__py3-none-any.whl

iad/core/docs/locators.ipynb

@@ -0,0 +1,754 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "e363337a-c122-407a-9a38-adc2ea03e95c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from inu.utils.filesproc import Locator\n",
+    "from pathlib import Path\n",
+    "import os\n",
+    "\n",
+    "root = Path().cwd()\n",
+    "os.environ['CUSTOM_OS_ROOT'] = str(Path().home())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "13eb1e54-9a67-4652-9a8a-f293abe131d3",
+   "metadata": {},
+   "source": [
+    "# Locator"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "5011ce13-8115-4fee-99c7-6c90894ac61e",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "\u001B[0;31mInit signature:\u001B[0m\n",
+       "\u001B[0mLocator\u001B[0m\u001B[0;34m(\u001B[0m\u001B[0;34m\u001B[0m\n",
+       "\u001B[0;34m\u001B[0m    \u001B[0;34m*\u001B[0m\u001B[0mfolders\u001B[0m\u001B[0;34m:\u001B[0m \u001B[0;34m'PathT | Locator'\u001B[0m\u001B[0;34m,\u001B[0m\u001B[0;34m\u001B[0m\n",
+       "\u001B[0;34m\u001B[0m    \u001B[0menvar\u001B[0m\u001B[0;34m:\u001B[0m \u001B[0;34m'str'\u001B[0m \u001B[0;34m=\u001B[0m \u001B[0;32mNone\u001B[0m\u001B[0;34m,\u001B[0m\u001B[0;34m\u001B[0m\n",
+       "\u001B[0;34m\u001B[0m    \u001B[0msub\u001B[0m\u001B[0;34m:\u001B[0m \u001B[0;34m'PathT'\u001B[0m \u001B[0;34m=\u001B[0m \u001B[0;32mNone\u001B[0m\u001B[0;34m,\u001B[0m\u001B[0;34m\u001B[0m\n",
+       "\u001B[0;34m\u001B[0m    \u001B[0morder\u001B[0m\u001B[0;34m=\u001B[0m\u001B[0;34m'EIA'\u001B[0m\u001B[0;34m,\u001B[0m\u001B[0;34m\u001B[0m\n",
+       "\u001B[0;34m\u001B[0m\u001B[0;34m)\u001B[0m\u001B[0;34m\u001B[0m\u001B[0;34m\u001B[0m\u001B[0m\n",
+       "\u001B[0;31mDocstring:\u001B[0m     \n",
+       "Manages multiple locations in the file system and provides methods to find and valudate them.\n",
+       "\n",
+       "Each of the locations can be defined:\n",
+       " - explicitely as a path,\n",
+       " - as environment variable\n",
+       " - as another Locator\n",
+       "\n",
+       "Main functionality resides in ``Locator.existing_folders()`` method.\n",
+       "By default it returns iterator over actually existing folders at the time of the call.\n",
+       "\u001B[0;31mInit docstring:\u001B[0m\n",
+       "Define locations to check for usually known before the run-time.\n",
+       "\n",
+       "Locations are searched in order is defined by the string of following letters denoting:\n",
+       "  - *E*: folder from the Env variable\n",
+       "  - *I*: Internal fallback folders\n",
+       "  - *A*: Additional folders\n",
+       "\n",
+       "Every letter must be used no more than once.\n",
+       "Valid orders: '*IA*', '*E*', '*AIE*'.\n",
+       "\n",
+       ":param envar:       environment variable with search folder\n",
+       ":param default:     default search folder\n",
+       ":param sub:         sub-path relative to those defined in envar and defaults\n",
+       ":param order:       order of searching locations\n",
+       "\u001B[0;31mFile:\u001B[0m           ~/code/algodev/inu/utils/filesproc.py\n",
+       "\u001B[0;31mType:\u001B[0m           type\n",
+       "\u001B[0;31mSubclasses:\u001B[0m     "
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "Locator?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b521886f-3619-4885-89cd-ebd986d4be2e",
+   "metadata": {},
+   "source": [
+    "# Creation"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "94cd821b-fe50-470e-ade9-de5330d9e78e",
+   "metadata": {},
+   "source": [
+    "## Single Argument"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 60,
+   "id": "ad29c933-6fd7-460d-90d7-3f1e0a011bee",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Locator<EIA>$CUSTOM_OS_ROOT=/home/itayo [/tmp\n",
+       "\t/home/itayo/tmp]"
+      ]
+     },
+     "execution_count": 60,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "loc1 = Locator('/tmp', '~/tmp', envar='CUSTOM_OS_ROOT') # using environment variable\n",
+    "loc1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 65,
+   "id": "52cbb7ae-7b77-4c1b-be99-b2f4d34c065c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "loc2 = Locator(loc1, '/more/tmp') # using other Locator"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "27a32476-aba3-40c1-a916-d367169d361c",
+   "metadata": {},
+   "source": [
+    "## Search Order\n",
+    "Main functionality of the `Locator` class is iterate over provided locations:\n",
+    " - **E**nvironment Variable based folder\n",
+    " - **I**nternally defined list of folders\n",
+    " - **A**dditionally provided to a specific method\n",
+    "\n",
+    "Default: 'EIA'\n",
+    "\n",
+    "*order* argument exists for almost all of the methods, and allows not only change the search order, but also filter it.  \n",
+    "\n",
+    "### Iterators \n",
+    "There are two family of iterators over the locations:\n",
+    " - defined: does not checks if defined folders exist\n",
+    " - existing: yields only existing "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 66,
+   "id": "8e25ff6d-dbe8-4ed2-8148-9384d0afd114",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[PosixPath('/home/itayo'), PosixPath('/tmp'), PosixPath('/home/itayo/tmp')]"
+      ]
+     },
+     "execution_count": 66,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[*loc1.defined()]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 74,
+   "id": "e826e5ee-7b67-42a1-a404-0bdf16976119",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[PosixPath('/home/itayo'), PosixPath('/tmp')]"
+      ]
+     },
+     "execution_count": 74,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[*loc1.existing()]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 75,
+   "id": "834ac9d8-d176-4ac8-bc01-3ff41e964163",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[PosixPath('/tmp'), PosixPath('/home/itayo')]"
+      ]
+     },
+     "execution_count": 75,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[*loc1.existing(order='IE')]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d11e3cef-3c52-4237-955a-778b37c24aa2",
+   "metadata": {},
+   "source": [
+    "Shortcuts for `first_` elements:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 77,
+   "id": "0d74674b-0519-49e6-a638-ac8fc2ba1e3c",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(PosixPath('/home/itayo'), PosixPath('/tmp'))"
+      ]
+     },
+     "execution_count": 77,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "loc1.first_existing(), loc1.first_existing(order='AIE')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e3d1e568-0356-43c9-adc1-9894b1a1af49",
+   "metadata": {},
+   "source": [
+    "### Internal folders first, then environment variable"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ab4f4522-fe83-4e97-b2f9-c3176a1d208b",
+   "metadata": {},
+   "source": [
+    "### Internal, then environment, then explicit"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 78,
+   "id": "68b249f2-7946-4c20-b6ef-5aacfcfe447b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "loc6 = Locator(root, envar='CUSTOM_OS_ROOT', order='IEA')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 79,
+   "id": "4b1cb909-a230-4906-920b-0468188c3df7",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "1./home/itayo/code/algodev/inu/utils\n",
+      "2./home/itayo\n",
+      "3./home/itayo/code\n"
+     ]
+    }
+   ],
+   "source": [
+    "cnt = 1\n",
+    "for folder in loc6.existing(Path().home() / 'code'):\n",
+    "    print(f'{cnt}.{folder}')\n",
+    "    cnt += 1"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "46057bb0-aa49-4ea6-84ba-50f0b0821f94",
+   "metadata": {},
+   "source": [
+    "# Finding Files"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "40071cff-f18c-46e0-b26b-af225ed7d057",
+   "metadata": {},
+   "source": [
+    "## Using Iterator"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 80,
+   "id": "68c7e93c-86fa-4b43-ab31-e2dd0306539e",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "PosixPath('/home/itayo/code/algodev/inu/utils/filesproc.py')"
+      ]
+     },
+     "execution_count": 80,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "itr = loc5.find_file_iter('filesproc.py')\n",
+    "next(itr)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "15fa60ae-4207-4edf-86cc-384463641242",
+   "metadata": {},
+   "source": [
+    "## Using First Found"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 81,
+   "id": "662b9f0e-7606-4f90-9cf5-03dcf2521003",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "PosixPath('/home/itayo/code/algodev/inu/utils/filesproc.py')"
+      ]
+     },
+     "execution_count": 81,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "loc5.first_file('filesproc.py')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b3698533-6dd6-4a5e-8337-28d355f12cc5",
+   "metadata": {},
+   "source": [
+    "# Defined and Existing"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "654a40a5-e51f-4a89-9a18-c8a35b023d7c",
+   "metadata": {},
+   "source": [
+    "Defined locations inside the locator are not necessarily exists.  \n",
+    "So we distinguish between *defined* and *existing* iterators."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 82,
+   "id": "be0991d4-44aa-4aa6-b62d-76d42139ac3a",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Locator<IE>$FAKE_CUSTOM_OS_ROOT=/home/itayo/notreallyexists [/home/itayo/code/algodev/inu/utils]"
+      ]
+     },
+     "execution_count": 82,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "os.environ['FAKE_CUSTOM_OS_ROOT'] = str(Path().home() / 'notreallyexists')\n",
+    "loc7 = Locator(root, envar='FAKE_CUSTOM_OS_ROOT', order='IE')\n",
+    "loc7"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 83,
+   "id": "eba8be5c-3706-4f72-9494-cf15f81ef11f",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[PosixPath('/home/itayo/code/algodev/inu/utils'),\n",
+       " PosixPath('/home/itayo/notreallyexists')]"
+      ]
+     },
+     "execution_count": 83,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[*loc7.defined()]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 84,
+   "id": "51444a00-3261-4961-9abd-8aab6ab4c900",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[PosixPath('/home/itayo/code/algodev/inu/utils')]"
+      ]
+     },
+     "execution_count": 84,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[*loc7.existing()]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4a9205dc-c8c1-4735-832b-1aa51301c759",
+   "metadata": {},
+   "source": [
+    "# Reconfigure existing Locator\n",
+    "For special cases, it is possible to reconfigure the Locator after it's creation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 85,
+   "id": "ad1cde07-8593-4f3f-9601-20f80b4aa53b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "loc7.reconfigure(root.parent, '/tmp', '/another/one', envar='CUSTOM_OS_ROOT')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 86,
+   "id": "6521b187-4c1f-4826-8258-f88734974008",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Locator<IE>$CUSTOM_OS_ROOT=/home/itayo [/home/itayo/code/algodev/inu\n",
+       "\t/tmp\n",
+       "\t/another/one]"
+      ]
+     },
+     "execution_count": 86,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "loc7"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0234e9b8-665a-4f43-bd45-5e2a0af33b34",
+   "metadata": {},
+   "source": [
+    "# Sub-foldering"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 87,
+   "id": "9453b3bd-68fb-4151-be77-0735260f74d0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "loc4 = Locator(root, envar='CUSTOM_OS_ROOT')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 88,
+   "id": "ebd5320b-e5c9-48ab-9ef7-16ad64743477",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "loc8 = loc4 / 'code/algodev'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 89,
+   "id": "2882c9b7-7573-4518-92a1-9a4af758158b",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Locator<EIA|'/code/algodev'>$CUSTOM_OS_ROOT=/home/itayo [/home/itayo/code/algodev/inu/utils]"
+      ]
+     },
+     "execution_count": 89,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "loc8"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 91,
+   "id": "3cbedb30-1a8f-4f4b-a2d2-2f585dd40668",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "loc9 = loc8 / 'aviv'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 92,
+   "id": "9926ad6a-72a9-4b04-9f66-6a9cca7f9bc6",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Locator<EIA|'/code/algodev/aviv'>$CUSTOM_OS_ROOT=/home/itayo [/home/itayo/code/algodev/inu/utils]"
+      ]
+     },
+     "execution_count": 92,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "loc9"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 90,
+   "id": "f9618c95-9f14-410f-a6dc-d7296ced1ead",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "PosixPath('code/algodev')"
+      ]
+     },
+     "execution_count": 90,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "loc8.sub"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "21062e37-306d-45aa-a20c-3831d1d7a172",
+   "metadata": {},
+   "source": [
+    "# Operator overloading and dunder methods"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b8644c18-f5e6-4ddb-a02a-c1daeab048e7",
+   "metadata": {},
+   "source": [
+    "## +"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 94,
+   "id": "1ef45ffc-0f4f-4233-a280-c5537e1ba7cd",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[PosixPath('/home/itayo/code/algodev/inu/utils'),\n",
+       " PosixPath('/dev'),\n",
+       " PosixPath('/aviv')]"
+      ]
+     },
+     "execution_count": 94,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[dfnd for dfnd in (Locator(root) + ['/dev', '/aviv/']).defined()]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2396e072-f0cf-4919-b883-5670dad603d3",
+   "metadata": {},
+   "source": [
+    "## -"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 22,
+   "id": "339f7fbd-d096-43b5-8b5a-00edb0482b28",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[]"
+      ]
+     },
+     "execution_count": 22,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[dfnd for dfnd in (Locator(root) - root).defined()]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6eb6a1c5-b876-4c39-86dc-07e27718b59b",
+   "metadata": {},
+   "source": [
+    "## /"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "id": "74936891-a3bc-4dc9-8165-d2ffc546756d",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 23,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "(Locator(\"/tmp\", sub=\"one\") / \"two\").sub == (Locator(\"/tmp\", sub=\"one/two\")).sub"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6ed29e8a-12fb-4e02-baa3-59b96d16bec9",
+   "metadata": {},
+   "source": [
+    "## bool"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 24,
+   "id": "3749a41a-8d45-4d6b-9dc6-708ec2d98d67",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 24,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bool(loc8)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 25,
+   "id": "3b083f11-04dd-4b7e-9092-5875d4f059e4",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "False"
+      ]
+     },
+     "execution_count": 25,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bool(Locator())"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "algodev",
+   "language": "python",
+   "name": "algodev"
+  },
+  "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.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}