code/19-context-managers.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "📝 **Author:** Amirhossein Heydari - 📧 **Email:** <amirhosseinheydari78@gmail.com> - 📍 **Origin:** [mr-pylin/python-workshop](https://github.com/mr-pylin/python-workshop)\n",
    "\n",
    "---\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Table of contents**<a id='toc0_'></a>    \n",
    "- [Context Manager](#toc1_)    \n",
    "  - [`with` Statement](#toc1_1_)    \n",
    "  - [Custom Context Manager](#toc1_2_)    \n",
    "  - [`__exit__` method arguments](#toc1_3_)    \n",
    "  - [Implementing a Context Manager Using `contextlib` Module](#toc1_4_)    \n",
    "\n",
    "<!-- vscode-jupyter-toc-config\n",
    "\tnumbering=false\n",
    "\tanchor=true\n",
    "\tflat=false\n",
    "\tminLevel=1\n",
    "\tmaxLevel=6\n",
    "\t/vscode-jupyter-toc-config -->\n",
    "<!-- THIS CELL WILL BE REPLACED ON TOC UPDATE. DO NOT WRITE YOUR TEXT IN THIS CELL -->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc1_'></a>[Context Manager](#toc0_)\n",
    "\n",
    "- A context manager allows you to allocate and release resources efficiently.\n",
    "- It is typically used when you need to set up and tear down resources, ensuring that these processes happen reliably.\n",
    "- e.g. opening and closing files or handling database connections\n",
    "\n",
    "✍️ **Common Use Cases**:\n",
    "\n",
    "- Managing file operations (opening and closing files).\n",
    "- Connecting to and disconnecting from a database.\n",
    "- Locking and releasing resources (for threading or multiprocessing).\n",
    "- Acquiring and releasing locks in concurrency scenarios.\n",
    "\n",
    "✍️ **Key Components**:\n",
    "\n",
    "- `__enter__` method: Defines what needs to be done when the context is entered.\n",
    "- `__exit__` method: Defines what needs to be done when the context is exited, including cleaning up the resources.\n",
    "\n",
    "📝 **Docs**:\n",
    "\n",
    "- Context Manager Types: [docs.python.org/3/library/stdtypes.html#context-manager-types](https://docs.python.org/3/library/stdtypes.html#context-manager-types)\n",
    "- The with statement: [docs.python.org/3/reference/compound_stmts.html#the-with-statement](https://docs.python.org/3/reference/compound_stmts.html#the-with-statement)\n",
    "- function `open`: [docs.python.org/3/library/functions.html#open](https://docs.python.org/3/library/functions.html#open)\n",
    "- file object: [docs.python.org/3/glossary.html#term-file-object](https://docs.python.org/3/glossary.html#term-file-object)\n",
    "- `contextlib` — Utilities for with-statement contexts: [docs.python.org/3/library/contextlib.html](https://docs.python.org/3/library/contextlib.html)\n",
    "\n",
    "🐍 **PEP**:\n",
    "\n",
    "- The \"`with`\" Statement [[PEP 343](https://peps.python.org/pep-0343/)]\n",
    "- Allow **enter**() methods to skip the statement body [[PEP 377](https://peps.python.org/pep-0377/)]\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='toc1_1_'></a>[`with` Statement](#toc0_)\n",
    "\n",
    "- The `with` statement simplifies exception handling and ensures proper acquisition and release of resources.\n",
    "- The `with` statement works with context managers, which define `__enter__()` and `__exit__()` methods.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# traditional approach (without <with> statement)\n",
    "file = open(\"../assets/texts/file1.txt\", \"r\")\n",
    "\n",
    "try:\n",
    "    data = file.read()\n",
    "finally:\n",
    "    file.close()  # ensures the file is closed after reading\n",
    "\n",
    "# log\n",
    "print(data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# using the with statement\n",
    "# no need to explicitly close the file, it is automatically handled\n",
    "with open(\"../assets/texts/file1.txt\", \"r\") as file:\n",
    "    data = file.read()\n",
    "\n",
    "# log\n",
    "print(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='toc1_2_'></a>[Custom Context Manager](#toc0_)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyContext:\n",
    "    def __enter__(self):\n",
    "        print(\"entering context\")\n",
    "        return self\n",
    "\n",
    "    def __exit__(self, exc_type, exc_val, exc_tb):\n",
    "        print(\"exiting context\")\n",
    "\n",
    "\n",
    "# log\n",
    "with MyContext() as ctx:\n",
    "    print(\"inside with block\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class FileManager:\n",
    "    def __init__(self, filename: str, mode: str):\n",
    "        self.filename = filename\n",
    "        self.mode = mode\n",
    "\n",
    "    def __enter__(self):\n",
    "        print(\"entering context\")\n",
    "        self.file = open(self.filename, self.mode)\n",
    "        return self.file\n",
    "\n",
    "    def __exit__(self, exc_type, exc_val, exc_tb):\n",
    "        print(\"exiting context\")\n",
    "        self.file.close()\n",
    "\n",
    "\n",
    "# log\n",
    "print(\"writing to a file:\")\n",
    "with FileManager(\"../assets/texts/file3.txt\", \"w\") as f:\n",
    "    f.write(\"Hello, Context Manager!\")\n",
    "\n",
    "print(\"\\nreading from a file:\")\n",
    "with FileManager(\"../assets/texts/file3.txt\", \"r\") as f:\n",
    "    print(f.read())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='toc1_3_'></a>[`__exit__` method arguments](#toc0_)\n",
    "\n",
    "- **exc_type**\n",
    "  - If an exception is raised inside the `with` block, `exc_type` will hold the type of that exception.\n",
    "  - If no exception occurs, this argument will be `None`.\n",
    "  - The class of the exception (e.g., `ValueError`, `TypeError`, etc.).\n",
    "- **exc_val**\n",
    "  - This is the actual exception object (i.e., the instance of the exception class).\n",
    "  - It contains the error message or any additional data associated with the exception.\n",
    "  - The instance of the exception raised, or `None` if no exception occurred.\n",
    "- **exc_tb**\n",
    "  - This is the traceback information, which helps trace the point in the code where the exception occurred.\n",
    "  - It shows the call stack at the moment the exception was raised, making it useful for debugging.\n",
    "  - A traceback object or `None` if no exception occurred.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import traceback"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class TestContextManager:\n",
    "    def __enter__(self):\n",
    "        print(\"entering the context\")\n",
    "        return self\n",
    "\n",
    "    def __exit__(self, exc_type, exc_val, exc_tb):\n",
    "        if exc_type is not None:\n",
    "            print(f\"Exception Type  : {exc_type}\")\n",
    "            print(f\"Exception Value : {exc_val}\")\n",
    "            print(f\"Traceback       : {exc_tb}\")\n",
    "            traceback.print_tb(exc_tb)  # prints a detailed traceback\n",
    "\n",
    "        print(\"exiting the context\")\n",
    "\n",
    "        return True  # suppresses the exception if True\n",
    "\n",
    "\n",
    "# log\n",
    "with TestContextManager():\n",
    "    raise ValueError(\"An error occurred\")  # intentionally raise an Error"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='toc1_4_'></a>[Implementing a Context Manager Using `contextlib` Module](#toc0_)\n",
    "\n",
    "- Python’s `contextlib` module provides a decorator-based approach for writing context managers, making it simpler for cases where you don't need a `class`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from contextlib import contextmanager"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@contextmanager\n",
    "def open_file(name: str, mode: str):\n",
    "    file = open(name, mode)\n",
    "    try:\n",
    "        yield file\n",
    "    finally:\n",
    "        file.close()\n",
    "\n",
    "\n",
    "# log\n",
    "with open_file(\"../assets/texts/file3.txt\", \"r\") as f:\n",
    "    print(f.read())"
   ]
  }
 ],
 "metadata": {
  "author_email": "AmirhosseinHeydari78@gmail.com",
  "author_github": "https://github.com/mr-pylin",
  "author_name": "Amirhossein Heydari",
  "kernelspec": {
   "display_name": "Python 3",
   "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.12.3"
  },
  "origin_repo": "https://github.com/mr-pylin/python-workshop"
 },
 "nbformat": 4,
 "nbformat_minor": 2
}