{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9fdeb776-f17c-42a5-84fb-765c19d5c6c3",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Learning materials, sources, references"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b3969792-c3ea-490b-8f5a-463da33ce0c4",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Python-specific"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ada8a3b-89e3-41ca-8748-9c8746b0b563",
   "metadata": {},
   "source": [
    "* https://docs.python.org/3/\n",
    "    * https://docs.python.org/3/tutorial/ read through this\n",
    "    * https://docs.python.org/3/library/ before you start implementing something or looking for pip packages\n",
    "        * https://docs.python.org/3/library/asyncio.html asynchronous I/O\n",
    "        * https://docs.python.org/3/library/ctypes.html to load C-like DLLs\n",
    "        * https://docs.python.org/3/library/unittest.html one of testing options\n",
    "    * https://docs.python.org/3/extending/ if you need C\n",
    "    * https://docs.python.org/3/whatsnew/ there's a lot of important stuff posted there, actually (e.g. `match` keyword)\n",
    "    * https://docs.python.org/3/reference/ in-depth about python itself\n",
    "        * https://docs.python.org/3/reference/datamodel.html the most important part from that reference\n",
    "* https://peps.python.org/\n",
    "    * https://peps.python.org/pep-0008/ python style guide\n",
    "    * https://peps.python.org/pep-0020 the zen of python\n",
    "    * https://peps.python.org/pep-0257 docstrings\n",
    "    * ~~https://peps.python.org/pep-0333 please no~~\n",
    "* https://wiki.python.org/moin/FrontPage at the moment of writing, haven't read much of it"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05a28df4-45f8-4004-9e47-1a8132378499",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# Introduction\n",
    "This notebook mostly features topics that are (IMO) overlooked.\n",
    "* environment; there are a lot of choices for where to develop and where to deploy; I'll try to gather and classify as much viable options as I can.\n",
    "* [typing](https://docs.python.org/3/library/typing.html); not everyone knows about annotations' existence (let alone that of the module); typing greatly enhances programmer's performance in any PL, and python is not an exception to that.\n",
    "* [data model](https://docs.python.org/3/reference/datamodel.html); python has a very strict and simple data model behind it; once you understand it, things like [\"why this attribute returns a totally different thing\"](https://docs.python.org/3/reference/datamodel.html#object.__getattr__) will be more obvious.\n",
    "* working with files; there are approaches beyond `open`+`.write`/`.read`.\n",
    "* [asyncio](https://docs.python.org/3/library/asyncio.html); the only correct way to do IO, if you don't wish to waste time and memory.\n",
    "* obscure new features; [`match`](https://docs.python.org/3/tutorial/controlflow.html#match-statements), [`Self`](https://peps.python.org/pep-0673/), [`type | type`](https://peps.python.org/pep-0604/), etc.; they are important, but not omnipresent as per their (in-language) [novelty](https://docs.python.org/3/whatsnew/index.html).\n",
    "* [styling](https://peps.python.org/pep-0008/).\n",
    "* testing (no link, because testing is quite diverse); not only unit tests; I'm still relatively incompetent at it, so things will be described from quite a limited perspective.\n",
    "\n",
    "Most sections will eventually include \"***prerequisites:***\" part (things you need to know before looking into this section); things required are mostly found in the official tutorial."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32ac085e-703e-41c9-99dc-e6bd7ce0d0ec",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# Environment"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "07390193-fdde-4bee-aec4-f5b3227dea06",
   "metadata": {
    "tags": []
   },
   "source": [
    "# [typing](https://docs.python.org/3/library/typing.html)\n",
    "module: https://docs.python.org/3/library/typing.html  \n",
    "relevant PEP: https://peps.python.org/pep-0484/\n",
    "\n",
    "Even a dynamically typed language can sometimes, at least, declare types. Python has built-in support for that via annotations.\n",
    "\n",
    "***prerequisites:** [functions](https://docs.python.org/3/tutorial/controlflow.html#defining-functions)*\n",
    "\n",
    "***also mentioned here:** [`match`](https://docs.python.org/3/tutorial/controlflow.html#match-statements)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "5477e321-dc9a-4c9a-a4b6-a2549c0c0d37",
   "metadata": {},
   "outputs": [],
   "source": [
    "import typing"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "990298fd-f154-45c7-b9a7-af63ae6e7c4e",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## Declaring a type"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de9d52c9-6df3-4427-b316-587b56347cd4",
   "metadata": {
    "tags": []
   },
   "source": [
    "### For a [variable](https://peps.python.org/pep-0526/)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "0e87b508-7845-4678-8134-884643f52213",
   "metadata": {},
   "outputs": [],
   "source": [
    "num0: int\n",
    "num0 = 1\n",
    "num1: int = 1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ccde8fee-3003-4842-bec8-8f118e95b17e",
   "metadata": {
    "tags": []
   },
   "source": [
    "### For a [function](https://docs.python.org/3/library/typing.html#callable)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "0a72a4e0-0e01-498f-b770-e48116d5a97b",
   "metadata": {},
   "outputs": [],
   "source": [
    "def fn0(x: int) -> int:\n",
    "    return x\n",
    "\n",
    "\n",
    "fn1: typing.Callable[[int], int]\n",
    "def fn1(x):\n",
    "    return x"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36c05f51-5422-41c7-a461-7f766c04b088",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Of a [generic](https://docs.python.org/3/library/typing.html#generics)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "267accf3-6ab5-421a-a349-04d21669e586",
   "metadata": {},
   "outputs": [],
   "source": [
    "list0: list[int] = [0, 1]\n",
    "dict0: dict[str, int] = {'0': 0, '1': 1}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a52cf44c-aa01-40c9-9adc-e838da385b28",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Of a [union](https://docs.python.org/3/library/stdtypes.html#types-union)\n",
    "see also:\n",
    "https://peps.python.org/pep-0604/\n",
    "https://docs.python.org/3/library/typing.html#typing.Union"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "eef4b91f-9a86-4d40-a049-d54f6a6f230f",
   "metadata": {},
   "outputs": [],
   "source": [
    "optional0: int | None = 0\n",
    "optional1: typing.Union[int, None] = None\n",
    "optional2: typing.Optional[int] = None\n",
    "optional2 = -1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "82158316-a752-4bcf-bd6f-c4cde017096b",
   "metadata": {
    "tags": []
   },
   "source": [
    "### example with [`match`](https://docs.python.org/3/tutorial/controlflow.html#match-statements)\n",
    "though annotations don't usually influence anything during runtime, they make programming easier"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "de6fd23d-1a81-47cc-ba84-b2f97ebe2cb3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('12', '12', None)"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def join(a: list[int] | set[str] | None) -> str | None:\n",
    "    match a:\n",
    "        case list():\n",
    "            return ''.join(map(str, a))\n",
    "        case set():\n",
    "            return ''.join(a)\n",
    "        case _:\n",
    "            return None\n",
    "\n",
    "result: tuple[str | None, str | None, str | None] = join([1, 2]), join({\"1\", \"2\"}), join(None)\n",
    "result"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c726cf29-f81e-4e52-95f1-128057fe4d0a",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# [Data model](https://docs.python.org/3/reference/datamodel.html)\n",
    "https://docs.python.org/3/reference/datamodel.html\n",
    "\n",
    "***prerequisites:** [classes](https://docs.python.org/3/tutorial/classes.html)*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a56ce30-37b4-463f-a446-895198dc0db8",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# Working with files\n",
    "related tutorial section: https://docs.python.org/3/tutorial/inputoutput.html\n",
    "\n",
    "There are a lot of ways, and directly using `open`+`.write`/`.read` is probably not fit for you task. So I decided not to link one specific external article to this section.\n",
    "\n",
    "***prerequisites:** variables, [strings](https://docs.python.org/3/tutorial/introduction.html#strings)*\n",
    "\n",
    "***also mentioned here:** [`with`](https://peps.python.org/pep-0343/)*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "daec179e-49a7-441e-95b4-d1b5d2c489fb",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## [`pathlib`](https://docs.python.org/3/library/pathlib.html), [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)\n",
    "One of the most overlooked python's modules is [`pathlib`](https://docs.python.org/3/library/pathlib.html).\n",
    "Even more rare is the knowledge that [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) objects have [`.open`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.open), [`.write_*`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.write_text) and [`.read_*`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.read_text) methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "b25fe82a-f87e-425d-81b4-bf1c0c2baf0f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5\n",
      "6\n",
      "\n"
     ]
    }
   ],
   "source": [
    "import pathlib\n",
    "tmp = pathlib.Path('tmp/')\n",
    "tmp.mkdir(exist_ok=True)\n",
    "example_txt = tmp / 'example.txt'\n",
    "example_txt.touch(exist_ok=True)\n",
    "example_txt.write_text(f'{2+3}\\n{2*3}\\n')\n",
    "print(example_txt.read_text())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e39ce1a-3396-45c9-bcad-19784326c32e",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## File(-like) objects -- [streams](https://docs.python.org/3/library/io.html).\n",
    "https://docs.python.org/3/library/io.html\n",
    "Returned by `open(...)` and `pathlib.Path(...).open(...)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "c59f89f6-d222-4382-8459-dd72c00f746e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5\n",
      "6\n",
      "\n",
      "5\n",
      "\n",
      "6\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# avoid using `open` outside `with` (`with` better guarantees file's closure)\n",
    "with open(example_txt, 'w') as f:\n",
    "    f.write(f'{2+3}\\n{2*3}\\n')\n",
    "with open(example_txt) as f:\n",
    "    print(f.read())\n",
    "with open(example_txt) as f:\n",
    "    for line in f:\n",
    "        print(line)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be63bbdc-4a21-4ed5-b0cb-0dd5f8a447c0",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# The [`with`](https://peps.python.org/pep-0343/) statement.\n",
    "~~AKA the reason I can't quit python~~\n",
    "\n",
    "statement itself: https://docs.python.org/3/reference/compound_stmts.html#with  \n",
    "relevant PEP: https://peps.python.org/pep-0343/  \n",
    "the datamodel it represents: https://docs.python.org/3/reference/datamodel.html#context-managers"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6519c846-90fd-4828-9861-3cac9954880f",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# [asyncio](https://docs.python.org/3/library/asyncio.html)\n",
    "If you do anything with IO, you should probably do it **asynchronously**  \n",
    "https://docs.python.org/3/library/asyncio.html\n",
    "\n",
    "***prerequisites:** [functions](https://docs.python.org/3/tutorial/controlflow.html#defining-functions)*\n",
    "\n",
    "***recommended before reading:** [classes](https://docs.python.org/3/tutorial/classes.html)*\n",
    "\n",
    "***also mentioned here:** [`with`](https://peps.python.org/pep-0343/)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "ffc18b3f-f63a-4556-bc24-d3a7d69756ac",
   "metadata": {},
   "outputs": [],
   "source": [
    "import asyncio"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c0fe1271-d784-4c45-9294-795a6b01b785",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## Background\n",
    "The most prominent use of async IO is undoubtably anything that has to do with JavaScript (the web programming language).  \n",
    "Due to \\{1) limitations in performance 2) single-threaded environment (that can't allow any freezes) 3) constantly working with high-latency IO (because internet, client- and server-side) of high frequency (and high (number-wise) loads for servers)\\}, JS kind of has to resort to using an event loop.  \n",
    "All IO in JS is forced to be async.  \n",
    "In browsers that is to prevent incompetent or malicious actors from killing your browser (or parts of it).  \n",
    "In Node that is to prevent unnecessary blocking of code to achieve better performance.  \n",
    "Ryan Dahl on Node.js:  \n",
    "https://youtu.be/ztspvPYybIY  \n",
    "https://youtu.be/jo_B4LTHi3I"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f06ca023-f840-4488-b9b2-cfd302193858",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## Level 0: working inside async framework\n",
    "If you've ever worked with [`aiohttp`](https://docs.aiohttp.org/) or [`discord.py`](https://discordpy.readthedocs.io/)/[`disnake`](https://docs.disnake.dev/), you've probably encountered [`async`/`await` syntax](https://peps.python.org/pep-0492/).  \n",
    "It may seems like these frameworks just make you put this magic words here and there.  \n",
    "But there are reasons for both of these magic words."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d46018f9-8609-4408-ab97-48dbea0bfd7c",
   "metadata": {
    "tags": []
   },
   "source": [
    "### `async def` -- define an asynchronous function ([coroutine](https://docs.python.org/3/library/asyncio-task.html))\n",
    "`async` here signals to python that the function might use `await`s inside it.  \n",
    "Statements *inside* coroutines are guaranteed to happen in sequence with each other"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5205f839-7b22-4144-9e7c-29093b05e2ca",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "### `await` -- virtually block on a future or on another coroutine and return result\n",
    "While coroutine `await`s, other coroutines can be (and, probably, are) doing their own stuff.  \n",
    "Any code between `await`s happens sequentially with all the other code, i.e. unlike [`threading`](https://docs.python.org/3/library/threading.html), `async` does not mix statements unpredictably.  \n",
    "You always have the exclusive and direct control of data in code fragments where you don't `await`.  \n",
    "Expression `(await f(...))` where `f` is defined as `async def f(...): ...` with `return x` evaluates to that `x`.  \n",
    "Expression `(await future)` where `f` is `asyncio.Future` that has someone call `.set_result(x)` evaluates to that `x`.  "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9cf426c-94fa-4907-b182-a759d0934080",
   "metadata": {
    "tags": []
   },
   "source": [
    "### [`async with` -- asynchronous context management](https://peps.python.org/pep-0492/#asynchronous-context-managers-and-async-with)\n",
    "Same as `with`, but `async def __aenter__`/`async def __aexit__` instead of `def __enter__`/`def __exit__`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3883d33f-730f-4ccb-b4be-3f905bafc607",
   "metadata": {},
   "source": [
    "### [`async for` -- asynchronous iteration](https://peps.python.org/pep-0492/#asynchronous-iterators-and-async-for)\n",
    "Same as `for`, but `async def` instead of `def` for `yield`-based generators and `__aiter__`/`__anext__` instead of `__iter__`/`__next__` for iterators/iterables."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21f08324-0b14-4b35-bc6e-7a7329520ed9",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## Level 1: using [high-level APIs](https://docs.python.org/3/library/asyncio-api-index.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f4e5b5e-d851-4a9b-a17d-c9a387f277fb",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## Level 2: using [low-level APIs](https://docs.python.org/3/library/asyncio-llapi-index.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe6dcf16-522a-4b20-99b6-54b92d59e19e",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# Last section, for the empty cell(s) to not get stuck with previous sections"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8274518c-661b-4907-b249-3da832753646",
   "metadata": {},
   "outputs": [],
   "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.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}