docs/watermark.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# IPython magic function documentation - `%watermark`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I wrote this simple `watermark` IPython magic function to conveniently add date- and time-stamps to my IPython notebooks. Also, I often want to document various system information, e.g., for my [Python benchmarks](https://github.com/rasbt/One-Python-benchmark-per-day) series.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The watermark line magic can be installed by executing\n",
    "\n",
    "```bash\n",
    "pip install watermark\n",
    "```\n",
    "\n",
    "Alternatively, you can install the latest development version directly from GitHub via\n",
    "\n",
    "```bash\n",
    "pip install -e git+https://github.com/rasbt/watermark#egg=watermark\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading the `%watermark` magic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To load the `watermark` magic, execute the following line in your IPython notebook or current IPython shell"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext watermark"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The version of `watermark` itself can be retrieved as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Watermark: 2.3.0\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark --watermark"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Usage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to display the optional `watermark` arguments, type"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[0;31mDocstring:\u001b[0m\n",
       "::\n",
       "\n",
       "  %watermark [-a AUTHOR] [-gu GITHUB_USERNAME] [-e EMAIL] [-ws WEBSITE]\n",
       "                 [-d] [-n] [-t] [-i] [-z] [-u] [-c CUSTOM_TIME] [-v]\n",
       "                 [-p PACKAGES] [-co] [-h] [-m] [-g] [-r] [-b] [-w] [-iv]\n",
       "\n",
       "IPython magic function to print date/time stamps\n",
       "and various system information.\n",
       "\n",
       "optional arguments:\n",
       "  -a AUTHOR, --author AUTHOR\n",
       "                        prints author name\n",
       "  -gu GITHUB_USERNAME, --github_username GITHUB_USERNAME\n",
       "                        prints author github username\n",
       "  -e EMAIL, --email EMAIL\n",
       "                        prints author email\n",
       "  -ws WEBSITE, --website WEBSITE\n",
       "                        prints author or project website\n",
       "  -d, --date            prints current date as YYYY-mm-dd\n",
       "  -n, --datename        prints date with abbrv. day and month names\n",
       "  -t, --time            prints current time as HH-MM-SS\n",
       "  -i, --iso8601         prints the combined date and time including the time\n",
       "                        zone in the ISO 8601 standard with UTC offset\n",
       "  -z, --timezone        appends the local time zone\n",
       "  -u, --updated         appends a string \"Last updated: \"\n",
       "  -c CUSTOM_TIME, --custom_time CUSTOM_TIME\n",
       "                        prints a valid strftime() string\n",
       "  -v, --python          prints Python and IPython version\n",
       "  -p PACKAGES, --packages PACKAGES\n",
       "                        prints versions of specified Python modules and\n",
       "                        packages\n",
       "  -co, --conda          prints name of current conda environment\n",
       "  -h, --hostname        prints the host name\n",
       "  -m, --machine         prints system and machine info\n",
       "  -g, --githash         prints current Git commit hash\n",
       "  -r, --gitrepo         prints current Git remote address\n",
       "  -b, --gitbranch       prints current Git branch\n",
       "  -w, --watermark       prints the current version of watermark\n",
       "  -iv, --iversions      prints the name/version of all imported modules\n",
       "\u001b[0;31mFile:\u001b[0m      ~/code/github_rasbt/watermark/watermark/magic.py\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%watermark?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<pre>\n",
    "%watermark [-a AUTHOR] [-gu GITHUB_USERNAME] [-e EMAIL] [-ws WEBSITE]\n",
    "                 [-d] [-n] [-t] [-i] [-z] [-u] [-c CUSTOM_TIME] [-v]\n",
    "                 [-p PACKAGES] [-h] [-m] [-g] [-r] [-b] [-w] [-iv]\n",
    "\n",
    "IPython magic function to print date/time stamps\n",
    "and various system information.\n",
    "\n",
    "options:\n",
    "  -a AUTHOR, --author AUTHOR\n",
    "                        prints author name\n",
    "  -gu GITHUB_USERNAME, --github_username GITHUB_USERNAME\n",
    "                        prints author github username\n",
    "  -e EMAIL, --email EMAIL\n",
    "                        prints author email\n",
    "  -ws WEBSITE, --website WEBSITE\n",
    "                        prints author or project website\n",
    "  -d, --date            prints current date as YYYY-mm-dd\n",
    "  -n, --datename        prints date with abbrv. day and month names\n",
    "  -t, --time            prints current time as HH-MM-SS\n",
    "  -i, --iso8601         prints the combined date and time including the time\n",
    "                        zone in the ISO 8601 standard with UTC offset\n",
    "  -z, --timezone        appends the local time zone\n",
    "  -u, --updated         appends a string \"Last updated: \"\n",
    "  -c CUSTOM_TIME, --custom_time CUSTOM_TIME\n",
    "                        prints a valid strftime() string\n",
    "  -v, --python          prints Python and IPython version\n",
    "  -p PACKAGES, --packages PACKAGES\n",
    "                        prints versions of specified Python modules and\n",
    "                        packages\n",
    "  -h, --hostname        prints the host name\n",
    "  -m, --machine         prints system and machine info\n",
    "  -g, --githash         prints current Git commit hash\n",
    "  -r, --gitrepo         prints current Git remote address\n",
    "  -b, --gitbranch       prints current Git branch\n",
    "  -w, --watermark       prints the current version of watermark\n",
    "  -iv, --iversions      prints the name/version of all imported modules\n",
    "</pre>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Examples"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defaults"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Last updated: 2022-01-03T19:44:42.841436-06:00\n",
      "\n",
      "Python implementation: CPython\n",
      "Python version       : 3.9.6\n",
      "IPython version      : 7.30.1\n",
      "\n",
      "Compiler    : Clang 11.1.0 \n",
      "OS          : Darwin\n",
      "Release     : 21.1.0\n",
      "Machine     : arm64\n",
      "Processor   : arm\n",
      "CPU cores   : 8\n",
      "Architecture: 64bit\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Last updated date and time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Last updated: 2022-01-03 19:44:42\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark -u -t -d"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Last updated: 2022-01-03T19:44:42.855544-06:00\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark -u --iso8601"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Last updated: Mon Jan 03 2022 19:44:42CST\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark -u -n -t -z"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python version information"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Python implementation: CPython\n",
      "Python version       : 3.9.6\n",
      "IPython version      : 7.30.1\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark -v"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Machine information"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Compiler    : Clang 11.1.0 \n",
      "OS          : Darwin\n",
      "Release     : 21.1.0\n",
      "Machine     : arm64\n",
      "Processor   : arm\n",
      "CPU cores   : 8\n",
      "Architecture: 64bit\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark -m"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Combination of information"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Python implementation: CPython\n",
      "Python version       : 3.9.6\n",
      "IPython version      : 7.30.1\n",
      "\n",
      "numpy  : 1.22.0\n",
      "scipy  : 1.7.3\n",
      "sklearn: 1.0.2\n",
      "\n",
      "Compiler    : Clang 11.1.0 \n",
      "OS          : Darwin\n",
      "Release     : 21.1.0\n",
      "Machine     : arm64\n",
      "Processor   : arm\n",
      "CPU cores   : 8\n",
      "Architecture: 64bit\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark -v -m -p numpy,scipy,sklearn "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### With author"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Author: John Doe\n",
      "\n",
      "Last updated: 2022-01-03\n",
      "\n",
      "Python implementation: CPython\n",
      "Python version       : 3.9.6\n",
      "IPython version      : 7.30.1\n",
      "\n",
      "Compiler    : Clang 11.1.0 \n",
      "OS          : Darwin\n",
      "Release     : 21.1.0\n",
      "Machine     : arm64\n",
      "Processor   : arm\n",
      "CPU cores   : 8\n",
      "Architecture: 64bit\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark -a \"John Doe\" -u -d -v -m"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Imported modules information"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "import scipy as sp\n",
    "from sklearn import metrics\n",
    "import numpy.linalg as linalg"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "scipy  : 1.7.3\n",
      "numpy  : 1.22.0\n",
      "sklearn: 1.0.2\n",
      "\n"
     ]
    }
   ],
   "source": [
    "%watermark --iversions"
   ]
  }
 ],
 "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.9.6"
  },
  "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
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}