04_ipython_magics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# IPython Magics\n",
    "\n",
    "[IPython magics](https://ipython.readthedocs.io/en/stable/interactive/magics.html) can be extremely useful in a development environment. They can do all kinds of things, like run shell commands, and run code from other languages. Let's try it out."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'/Users/nicolebrewer/Repos/nicole-brewer-github/literate-python'"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "%pwd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tells us the current working directory of the ZMQInteractiveShell running this notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Line magics\n",
    "\n",
    "These types of magics that begin with a single `%` are called line magics. You can have several of them in a single cell, and they will print to stdout that gets displayed at the end of the cell (more on that later). \n",
    "\n",
    "Okay, now lets see what we have in this directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "01_literate_programming.ipynb\t   img/\r\n",
      "02_literate_python_packages.ipynb  jupyter_notebooks.ipynb\r\n",
      "03_ipython.ipynb\t\t   notebook_importer.ipynb\r\n",
      "05_ipython_magics.ipynb\t\t   notebook_writer_extension.ipynb\r\n",
      "example_script.py\r\n"
     ]
    }
   ],
   "source": [
    "%ls"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wow okay cool. We can see the `ipython_magics.ipynb` we are viewing, and a file called `example_script.py`. Let's say we are using our notebook and we want run some code from an external python file. We can easily use the run command to do this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "awesome\n"
     ]
    }
   ],
   "source": [
    "%run example_script.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Apparently there was some sort of `print('awesome')` statement in that code somewhere. Don't believe me? Let's pull in the code to find out!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# %load example_script.py\n",
    "# hello! I came from example_script.py\n",
    "\n",
    "print('awesome')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The comment in the first line is a optional nicety provided by the `%load` command. \n",
    "\n",
    "### Cell magics\n",
    "The other kind of IPython magic starts with a `%%`. These are called 'cell magics' because all the lines that follow it are included as a single agrument to the function. One of the most common reasons for using cell magic is to run the code in that cell in a particular language. Lets say we want to run the alert command from javascript."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "alert('Hello from JS!');\n"
      ],
      "text/plain": [
       "<IPython.core.display.Javascript object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%js\n",
    "alert('Hello from JS!');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It works like a charm. You may notice that line magic can be used anywhere in code cell, including inside logical statements, but code magics must occur at the very beginning of the first line of the cell, and the rest of their contents is sent to the function you called in the first line.\n",
    "\n",
    "## How magics work\n",
    "\n",
    "Magics aren't really magic at all! They are code just like anything else. IPython just parses them for us to make the syntax more easy and clean. So we can use the same commands as before by calling the IPython magic function from an InteractiveShell like we created before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "awesome\n"
     ]
    }
   ],
   "source": [
    "from IPython import get_ipython\n",
    "ipython = get_ipython()\n",
    "\n",
    "ipython.run_line_magic('run', line='example_script.py')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "alert('Hello from JS!');"
      ],
      "text/plain": [
       "<IPython.core.display.Javascript object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "ipython.run_cell_magic('js', line='', cell=\"alert('Hello from JS!');\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that you know that magics are just methods like anything else, you might be wondering, \"can I write my own magic functions\"? Of course you can. This is where we are going to start active learning by building a small project that will help us write clean literate programs."
   ]
  }
 ],
 "metadata": {
  "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.9.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}