{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<small><small><i>\n",
    "All the IPython Notebooks in **Python Date Time Module** lecture series by Dr. Milaan Parmar are available @ **[GitHub](https://github.com/milaan9/08_Python_Date_Time_Module)**\n",
    "</i></small></small>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python time Module\n",
    "\n",
    "In this article, we will explore time module in detail. We will learn to use different time-related functions defined in the time module with the help of examples.\n",
    "\n",
    "Python has a module named **`time`** to handle time-related tasks. To use functions defined in the module, we need to import the module first. Here's how:\n",
    "\n",
    "``` python\n",
    "import time\n",
    "```\n",
    "\n",
    "Here are commonly used time-related functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python `time.time()`\n",
    "\n",
    "The **`time()`** function returns the number of seconds passed since epoch.\n",
    "\n",
    "For Unix system, **`January 1, 1970, 00:00:00`** at **UTC** is epoch (the point where time begins)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:17.598427Z",
     "start_time": "2021-06-22T13:58:17.580850Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Seconds since epoch = 1624370297.5828025\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "seconds = time.time()\n",
    "print(\"Seconds since epoch =\", seconds)\t\n",
    "\n",
    "# When you run the program, the output will be something like below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python **`time.ctime()`**\n",
    "\n",
    "The **`time.ctime()`** function takes seconds passed since epoch as an argument and returns a string representing local time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:19.414818Z",
     "start_time": "2021-06-22T13:58:19.403101Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Local time: Thu Dec 27 21:19:29 2018\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "# seconds passed since epoch\n",
    "seconds = 1545925769.9618232\n",
    "local_time = time.ctime(seconds)\n",
    "print(\"Local time:\", local_time)\n",
    "\n",
    "# When you run the program, the output will be something like below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python `time.sleep()`\n",
    "\n",
    "The **`sleep()`** function suspends (delays) execution of the current thread for the given number of seconds."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:23.418691Z",
     "start_time": "2021-06-22T13:58:20.994884Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is printed immediately.\n",
      "This is printed after 2.4 seconds.\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "print(\"This is printed immediately.\")\n",
    "time.sleep(2.4)\n",
    "print(\"This is printed after 2.4 seconds.\")\n",
    "\n",
    "# When you run the program, the output will be something like below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To learn more, visit: **[Python sleep()](https://github.com/milaan9/08_Python_Date_Time_Module/blob/main/008_Python_sleep%28%29.ipynb)**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we talk about other time-related functions, let's explore **`time.struct_time`** class in brief."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `time.struct_time` Class\n",
    "\n",
    "Several functions in the time module such as **`gmtime()`**, **`asctime()`** etc. either take **`time.struct_time`** object as an argument or return it.\n",
    "\n",
    "Here's an example of **`time.struct_time`** object.\n",
    "\n",
    "```python\n",
    "time.struct_time(tm_year=2018, tm_mon=12, tm_mday=27, \n",
    "                    tm_hour=6, tm_min=35, tm_sec=17, \n",
    "                    tm_wday=3, tm_yday=361, tm_isdst=0)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "| Index | Attribute | Values |\n",
    "|:----: |:---- |:---- |\n",
    "| **0** | **tm_year**  | **0000, ...., 2018, ..., 9999** |  \n",
    "| **1** | **tm_mon**   | **1, 2, ..., 12** | \n",
    "| **2** | **tm_mday**  | **1, 2, ..., 31** | \n",
    "| **3** | **tm_hour**  | **0, 1, ..., 23** | \n",
    "| **4** | **tm_min**   | **0, 1, ..., 59** | \n",
    "| **5** | **tm_sec**   | **0, 1, ..., 61** | \n",
    "| **6** | **tm_wday**  | **0, 1, ..., 6; Monday is 0** | \n",
    "| **7** | **tm_yday**  | **1, 2, ..., 366** | \n",
    "| **8** | **tm_isdst** | **0, 1 or -1** | \n",
    "\n",
    "The values (elements) of the **`time.struct_time`** object are accessible using both indices and attributes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python `time.localtime()`\n",
    "\n",
    "The **`localtime()`** function takes the number of seconds passed since epoch as an argument and returns **`struct_time`** in **local time**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:28.626161Z",
     "start_time": "2021-06-22T13:58:28.603703Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "result: time.struct_time(tm_year=2018, tm_mon=12, tm_mday=27, tm_hour=21, tm_min=19, tm_sec=29, tm_wday=3, tm_yday=361, tm_isdst=0)\n",
      "\n",
      "year: 2018\n",
      "tm_hour: 21\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "result = time.localtime(1545925769)\n",
    "print(\"result:\", result)\n",
    "print(\"\\nyear:\", result.tm_year)\n",
    "print(\"tm_hour:\", result.tm_hour)\n",
    "\n",
    "# When you run the program, the output will be like below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ">**Note:** If no argument or **`None`** is passed to **`localtime()`**, the value returned by **`time()`** is used."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python `time.gmtime()`\n",
    "\n",
    "The **`gmtime()`** function takes the number of seconds passed since epoch as an argument and returns **`struct_time`** in **UTC**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:30.408858Z",
     "start_time": "2021-06-22T13:58:30.388358Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "result: time.struct_time(tm_year=2018, tm_mon=12, tm_mday=27, tm_hour=15, tm_min=49, tm_sec=29, tm_wday=3, tm_yday=361, tm_isdst=0)\n",
      "\n",
      "year: 2018\n",
      "tm_hour: 15\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "result = time.gmtime(1545925769)\n",
    "print(\"result:\", result)\n",
    "print(\"\\nyear:\", result.tm_year)\n",
    "print(\"tm_hour:\", result.tm_hour)\n",
    "\n",
    "# When you run the program, the output will be like below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ">**Note:** If no argument or **`None`** is passed to **`gmtime()`**, the value returned by **`time()`** is used."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python `time.mktime()`\n",
    "\n",
    "The **`mktime()`** function takes **`struct_time`** (or a tuple containing 9 elements corresponding to **`struct_time`**) as an argument and returns the seconds passed since epoch in local time. Basically, it's the inverse function of **`localtime()`**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:33.440572Z",
     "start_time": "2021-06-22T13:58:33.426903Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Local time: 1545966844.0\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "t = (2018, 12, 28, 8, 44, 4, 4, 362, 0)\n",
    "\n",
    "local_time = time.mktime(t)\n",
    "print(\"Local time:\", local_time)\n",
    "\n",
    "# When you run the program, the output will be something like below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The example below shows how **`mktime()`** and **`localtime()`** are related."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:37.309188Z",
     "start_time": "2021-06-22T13:58:37.299428Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "t1:  time.struct_time(tm_year=2018, tm_mon=12, tm_mday=27, tm_hour=21, tm_min=19, tm_sec=29, tm_wday=3, tm_yday=361, tm_isdst=0)\n",
      "\\s: 1545925769\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "seconds = 1545925769\n",
    "\n",
    "# returns struct_time\n",
    "t = time.localtime(seconds)\n",
    "print(\"t1: \", t)\n",
    "\n",
    "# returns seconds from struct_time\n",
    "s = time.mktime(t)\n",
    "print(\"\\s:\", seconds)\n",
    "\n",
    "# When you run the program, the output will be like below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python `time.asctime()`\n",
    "\n",
    "The **`asctime()`** function takes **`struct_time`** (or a tuple containing 9 elements corresponding to **`struct_time`**) as an argument and returns a string representing it. Here's an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:40.107017Z",
     "start_time": "2021-06-22T13:58:40.090416Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Result: Fri Dec 28 08:44:04 2018\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "t = (2018, 12, 28, 8, 44, 4, 4, 362, 0)\n",
    "\n",
    "result = time.asctime(t)\n",
    "print(\"Result:\", result)\n",
    "\n",
    "# When you run the program, the output will be like below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python `time.strftime()`\n",
    "\n",
    "The **`strftime()`** function takes **`struct_time`** (or tuple corresponding to it) as an argument and returns a string representing it based on the format code used. For example,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:41.444892Z",
     "start_time": "2021-06-22T13:58:41.427319Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "06/22/2021, 19:28:41\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "named_tuple = time.localtime() # get struct_time\n",
    "time_string = time.strftime(\"%m/%d/%Y, %H:%M:%S\", named_tuple)\n",
    "\n",
    "print(time_string)\n",
    "\n",
    "# When you run the program, the output will be something like below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ">**Note:** Here, **`%Y,`**, **`%m`**, **`%d`**, **`%H`** etc. are format codes.\n",
    "\n",
    "| Directive | Meaning | Example |\n",
    "|:----: |:---- |:---- |\n",
    "| **`%Y`** | **year**   | **[0001,..., 2018, 2019,..., 9999]** |  \n",
    "| **`%m`** | **month**  | **[01, 02, ..., 11, 12]** |  \n",
    "| **`%d`** | **day**    | **[01, 02, ..., 30, 31]** |  \n",
    "| **`%H`** | **hour**   | **[00, 01, ..., 22, 23]** |  \n",
    "| **`%M`** | **minute** | **[00, 01, ..., 58, 59]** |  \n",
    "| **`%S`** | **second** | **[00, 01, ..., 58, 61]** |\n",
    "\n",
    "To learn more, visit: **[time.strftime()](https://docs.python.org/3/library/time.html#time.strftime)**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python `time.strptime()`\n",
    "\n",
    "The **`strptime()`** function parses a string representing time and returns **`struct_time`**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-22T13:58:45.682652Z",
     "start_time": "2021-06-22T13:58:45.667026Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "time.struct_time(tm_year=2018, tm_mon=6, tm_mday=21, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=172, tm_isdst=-1)\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "time_string = \"21 June, 2018\"\n",
    "result = time.strptime(time_string, \"%d %B, %Y\")\n",
    "\n",
    "print(result)\n",
    "\n",
    "# When you run the program, the output will be like below:"
   ]
  },
  {
   "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
}