Python_Docstrings.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<small><small><i>\n",
    "All the IPython Notebooks in **Python Functions** lecture series by Dr. Milaan Parmar are available @ **[GitHub](https://github.com/milaan9/04_Python_Functions)**\n",
    "</i></small></small>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python Docstrings\n",
    "\n",
    "In this class, we will learn about Python docstrings. More specifically, we will learn how and why docstrings are used with the help of examples.\n",
    "\n",
    "Python docstrings are the string literals that appear right after the definition of a function, method, class, or module. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:06.380353Z",
     "start_time": "2021-06-13T08:11:06.362780Z"
    }
   },
   "outputs": [],
   "source": [
    "# Example 1: Docstrings\n",
    "\n",
    "def square(n):\n",
    "    '''Takes in a number n, returns the square of n'''\n",
    "    return n**2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, the string literal:\n",
    "```python\n",
    " '''Takes in a number n, returns the square of n'''\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "inside the triple quotation marks is the **docstring** of the function **`square()`** as it appears right after its definition.\n",
    "\n",
    ">**Note:** We can also use triple **`'''`** quotations to create docstrings."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python Comments vs Docstrings\n",
    "\n",
    "### Python Comments\n",
    "\n",
    "Comments are descriptions that help programmers better understand the intent and functionality of the program. They are completely ignored by the Python interpreter.\n",
    "\n",
    "In Python, we use the hash symbol **`#`** to write a single-line comment. For example, "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:09.750448Z",
     "start_time": "2021-06-13T08:11:09.730916Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello World\n"
     ]
    }
   ],
   "source": [
    "# Example 1: Program to print \"Hello World\"\n",
    "\n",
    "print(\"Hello World\") "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python Comments Using Strings\n",
    "\n",
    "If we do not assign strings to any variable, they act as comments. For example,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:10.920358Z",
     "start_time": "2021-06-13T08:11:10.906691Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello World\n"
     ]
    }
   ],
   "source": [
    "# Example 1:\n",
    "\n",
    "\"I am a single-line comment\"\n",
    "\n",
    "'''\n",
    "I am a\n",
    "multi-line comment!\n",
    "'''\n",
    "\n",
    "print(\"Hello World\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ">**Note:** We use triple quotation marks for multi-line strings."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python docstrings\n",
    "\n",
    "As mentioned above, Python docstrings are strings used right after the definition of a function, method, class, or module (like in Example \n",
    "\n",
    "**1. They are used to document our code**.\n",
    "\n",
    "We can access these docstrings using the **`__doc__`** attribute."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python `__doc__` attribute\n",
    "\n",
    "Whenever string literals are present just after the definition of a function, module, class or a method, they are associated with the object as their **`__doc__`** attribute. We can later use this attribute to retrieve this docstring."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:13.090263Z",
     "start_time": "2021-06-13T08:11:13.082453Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Takes in a number n, returns the square of n\n"
     ]
    }
   ],
   "source": [
    "# Example 1: Printing docstring\n",
    "\n",
    "def square(n):\n",
    "    '''Takes in a number n, returns the square of n'''\n",
    "    return n**2\n",
    "\n",
    "print(square.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, the documentation of our **`square()`** function can be accessed using the **`__doc__`** attribute."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's look at docstrings for the built-in function **`print()`**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:15.210361Z",
     "start_time": "2021-06-13T08:11:15.202551Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "print(value, ..., sep=' ', end='\\n', file=sys.stdout, flush=False)\n",
      "\n",
      "Prints the values to a stream, or to sys.stdout by default.\n",
      "Optional keyword arguments:\n",
      "file:  a file-like object (stream); defaults to the current sys.stdout.\n",
      "sep:   string inserted between values, default a space.\n",
      "end:   string appended after the last value, default a newline.\n",
      "flush: whether to forcibly flush the stream.\n"
     ]
    }
   ],
   "source": [
    "# Example 2: Docstrings for the built-in `print()` function\n",
    "\n",
    "print(print.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we can see that the documentation of the **`print()`** function is present as the **`__doc__`** attribute of this function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Single-line docstrings in Python\n",
    "\n",
    "Single line docstrings are the documents that fit in one line.\n",
    "\n",
    "**Standard conventions to write single-line docstrings:**\n",
    "\n",
    "* Even though they are single-lined, we still use the triple quotes around these docstrings as they can be expanded easily later.\n",
    "* The closing quotes are on the same line as the opening quotes.\n",
    "* There's no blank line either before or after the docstring.\n",
    "* They should not be descriptive, rather they must follow \"Do this, return that\" structure ending with a period.\n",
    "\n",
    "Let's take an example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:17.116597Z",
     "start_time": "2021-06-13T08:11:17.107811Z"
    }
   },
   "outputs": [],
   "source": [
    "# Example 1: Write single-line docstrings for a function\n",
    "    \n",
    "def multiplier(a, b):\n",
    "    \"\"\"Takes in two numbers, returns their product.\"\"\"\n",
    "    return a*b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:18.790898Z",
     "start_time": "2021-06-13T08:11:18.770883Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This function returns the factorial of a given number.\n"
     ]
    }
   ],
   "source": [
    "# Example 2:\n",
    "\n",
    "def factorial(x):\n",
    "    \"\"\"This function returns the factorial of a given number.\"\"\"\n",
    "    return x\n",
    "\n",
    "# access doc string\n",
    "print(factorial.__doc__)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:43.163257Z",
     "start_time": "2021-06-13T08:11:43.148615Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function factorial in module __main__:\n",
      "\n",
      "factorial(x)\n",
      "    This function returns the factorial of a given number.\n",
      "\n",
      "None\n"
     ]
    }
   ],
   "source": [
    "# Example 3:\n",
    "\n",
    "# pass function name to help() function\n",
    "print(help(factorial))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Multi-line Docstrings in Python\n",
    "\n",
    "Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.\n",
    "\n",
    "The PEP 257 document provides the standard conventions to write multi-line docstrings for various objects.\n",
    "\n",
    "Some have been listed below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Docstrings for Python Modules\n",
    "\n",
    "* The docstrings for Python Modules should list all the available classes, functions, objects and exceptions that are imported when the module is imported.\n",
    "* They should also have a one-line summary for each item.\n",
    "\n",
    "They are written at the beginning of the Python file.\n",
    "\n",
    "Let's look at the docstrings for the builtin module in Python called pickle."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:46.512840Z",
     "start_time": "2021-06-13T08:11:46.499173Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Create portable serialized representations of Python objects.\n",
      "\n",
      "See module copyreg for a mechanism for registering custom picklers.\n",
      "See module pickletools source for extensive comments.\n",
      "\n",
      "Classes:\n",
      "\n",
      "    Pickler\n",
      "    Unpickler\n",
      "\n",
      "Functions:\n",
      "\n",
      "    dump(object, file)\n",
      "    dumps(object) -> string\n",
      "    load(file) -> object\n",
      "    loads(string) -> object\n",
      "\n",
      "Misc variables:\n",
      "\n",
      "    __version__\n",
      "    format_version\n",
      "    compatible_formats\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Example 1: Docstrings of Python module\n",
    "\n",
    "import pickle\n",
    "print(pickle.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we can see that the docstring written at the beginning of the **pickle.py** module file can be accessed as its docstring."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Docstrings for Python Functions\n",
    "\n",
    "* The docstring for a function or method should summarize its behavior and document its arguments and return values.\n",
    "* It should also list all the exceptions that can be raised and other optional arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:50.215445Z",
     "start_time": "2021-06-13T08:11:50.203731Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    Returns the sum of two decimal numbers in binary digits.\n",
      "\n",
      "            Parameters:\n",
      "                    a (int): A decimal integer\n",
      "                    b (int): Another decimal integer\n",
      "\n",
      "            Returns:\n",
      "                    binary_sum (str): Binary string of the sum of a and b\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "# Example 1: Docstrings for Python functions\n",
    "\n",
    "def add_binary(a, b):\n",
    "    '''\n",
    "    Returns the sum of two decimal numbers in binary digits.\n",
    "\n",
    "            Parameters:\n",
    "                    a (int): A decimal integer\n",
    "                    b (int): Another decimal integer\n",
    "\n",
    "            Returns:\n",
    "                    binary_sum (str): Binary string of the sum of a and b\n",
    "    '''\n",
    "    binary_sum = bin(a+b)[2:]\n",
    "    return binary_sum\n",
    "\n",
    "\n",
    "print(add_binary.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, we have included a short description of what the function does, the parameter it takes in and the value it returns. The string literal is embedded to the function **`add_binary`** as its **`__doc__`** attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:55.625557Z",
     "start_time": "2021-06-13T08:11:55.613350Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "             \n",
      "   Description of function\n",
      "                 \n",
      "   Arguments:   \n",
      "   parameter1(int):Description of parameter1\n",
      "                 \n",
      "   Returns:      \n",
      "   int value     \n",
      "    \n"
     ]
    }
   ],
   "source": [
    "# Example 2:\n",
    "\n",
    "def any_fun(parameter1):\n",
    "    \"\"\"             \n",
    "   Description of function\n",
    "                 \n",
    "   Arguments:   \n",
    "   parameter1(int):Description of parameter1\n",
    "                 \n",
    "   Returns:      \n",
    "   int value     \n",
    "    \"\"\" \n",
    "\n",
    "print(any_fun.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. Docstrings for Python Classes\n",
    "\n",
    "The docstrings for classes should summarize its behavior and list the public methods and instance variables.\n",
    "The subclasses, constructors, and methods should each have their own docstrings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:11:58.791059Z",
     "start_time": "2021-06-13T08:11:58.782272Z"
    }
   },
   "outputs": [],
   "source": [
    "# Example 1: Docstrings for Python class\n",
    "\n",
    "# Suppose we have a Person.py file with the following code:\n",
    "\n",
    "class Person:\n",
    "    \"\"\"\n",
    "    A class to represent a person.\n",
    "\n",
    "    ...\n",
    "\n",
    "    Attributes\n",
    "    ----------\n",
    "    name : str\n",
    "        first name of the person\n",
    "    surname : str\n",
    "        family name of the person\n",
    "    age : int\n",
    "        age of the person\n",
    "\n",
    "    Methods\n",
    "    -------\n",
    "    info(additional=\"\"):\n",
    "        Prints the person's name and age.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, name, surname, age):\n",
    "        \"\"\"\n",
    "        Constructs all the necessary attributes for the person object.\n",
    "\n",
    "        Parameters\n",
    "        ----------\n",
    "            name : str\n",
    "                first name of the person\n",
    "            surname : str\n",
    "                family name of the person\n",
    "            age : int\n",
    "                age of the person\n",
    "        \"\"\"\n",
    "\n",
    "        self.name = name\n",
    "        self.surname = surname\n",
    "        self.age = age\n",
    "\n",
    "    def info(self, additional=\"\"):\n",
    "        \"\"\"\n",
    "        Prints the person's name and age.\n",
    "\n",
    "        If the argument 'additional' is passed, then it is appended after the main info.\n",
    "\n",
    "        Parameters\n",
    "        ----------\n",
    "        additional : str, optional\n",
    "            More info to be displayed (default is None)\n",
    "\n",
    "        Returns\n",
    "        -------\n",
    "        None\n",
    "        \"\"\"\n",
    "\n",
    "        print(f'My name is {self.name} {self.surname}. I am {self.age} years old.' + additional)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we can use the following code to access only the docstrings of the **`Person`** class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:12:00.449245Z",
     "start_time": "2021-06-13T08:12:00.436551Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "    A class to represent a person.\n",
      "\n",
      "    ...\n",
      "\n",
      "    Attributes\n",
      "    ----------\n",
      "    name : str\n",
      "        first name of the person\n",
      "    surname : str\n",
      "        family name of the person\n",
      "    age : int\n",
      "        age of the person\n",
      "\n",
      "    Methods\n",
      "    -------\n",
      "    info(additional=\"\"):\n",
      "        Prints the person's name and age.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "print(Person.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using the `help()` Function for Docstrings\n",
    "\n",
    "We can also use the **`help()`** function to read the docstrings associated with various objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-13T08:12:02.355969Z",
     "start_time": "2021-06-13T08:12:02.348159Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on class Person in module __main__:\n",
      "\n",
      "class Person(builtins.object)\n",
      " |  Person(name, surname, age)\n",
      " |  \n",
      " |  A class to represent a person.\n",
      " |  \n",
      " |  ...\n",
      " |  \n",
      " |  Attributes\n",
      " |  ----------\n",
      " |  name : str\n",
      " |      first name of the person\n",
      " |  surname : str\n",
      " |      family name of the person\n",
      " |  age : int\n",
      " |      age of the person\n",
      " |  \n",
      " |  Methods\n",
      " |  -------\n",
      " |  info(additional=\"\"):\n",
      " |      Prints the person's name and age.\n",
      " |  \n",
      " |  Methods defined here:\n",
      " |  \n",
      " |  __init__(self, name, surname, age)\n",
      " |      Constructs all the necessary attributes for the person object.\n",
      " |      \n",
      " |      Parameters\n",
      " |      ----------\n",
      " |          name : str\n",
      " |              first name of the person\n",
      " |          surname : str\n",
      " |              family name of the person\n",
      " |          age : int\n",
      " |              age of the person\n",
      " |  \n",
      " |  info(self, additional='')\n",
      " |      Prints the person's name and age.\n",
      " |      \n",
      " |      If the argument 'additional' is passed, then it is appended after the main info.\n",
      " |      \n",
      " |      Parameters\n",
      " |      ----------\n",
      " |      additional : str, optional\n",
      " |          More info to be displayed (default is None)\n",
      " |      \n",
      " |      Returns\n",
      " |      -------\n",
      " |      None\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Data descriptors defined here:\n",
      " |  \n",
      " |  __dict__\n",
      " |      dictionary for instance variables (if defined)\n",
      " |  \n",
      " |  __weakref__\n",
      " |      list of weak references to the object (if defined)\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Example 1: Read Docstrings with the `help()` function\n",
    "\n",
    "# We can use the help() function on the class Person in Example as:\n",
    "\n",
    "help(Person)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we can see that the **`help()`** function retrieves the docstrings of the **`Person`** class along with the methods associated with that class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4. Docstrings for Python Scripts\n",
    "\n",
    "* The docstrings for Python script should document the script's functions and command-line syntax as a usable message.\n",
    "* It should serve as a quick reference to all the functions and arguments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5. Docstrings for Python Packages\n",
    "\n",
    "The docstrings for a Python package is written in the package's **`__init__.py`** file.\n",
    "\n",
    "* It should contain all the available modules and sub-packages exported by the package."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Docstring Formats\n",
    "\n",
    "We can write docstring in many formats like the reStructured text (reST) format, Google format or the NumPy documentation format. To learn more, visit **[Popular Docstring Formats](https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format)**\n",
    "\n",
    "We can also generate documentation from docstrings using tools like Sphinx. To learn more, visit **[Official Sphinx Documentation](https://www.sphinx-doc.org/en/master/)**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "hide_input": false,
  "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.8.8"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}