Summary

Let's create a magic function to easily find help of python stdlib modules.

First, some logic to see what we want to do

Let's import some stuff

In [ ]:
import requests
import re
from IPython.display import IFrame

We extract the list of modules from the python docs. Yes, there are other ways but... ☻

In [ ]:
mods = requests.get("https://docs.python.org/3/py-modindex.html")
mods = mods.content

modules = re.findall(r'library/([^\'" >]+).html', str(mods))

A way to say what we want to search

In [ ]:
module = '__future__'

And, finally, we show the help inside an iframe

In [ ]:
url = "https://docs.python.org/3/library/{0}.html#module-{0}"
IFrame(url.format(module), width = "100%", height = "400px")

Let's modify this to have it as an IPython magic function

Structure of a magic function

From the IPython official docs: defining-your-own-magics

Two main ways to create a magic function:

  • from standalone functions
  • inheriting from a base class provided by IPython: IPython.core.magic.Magics.

Magic functions can work as:

  • line magic (from IPython.core.magic import register_line_magic)
  • cell magic (from IPython.core.magic import register_cell_magic)
  • both of the above cases (from IPython.core.magic import register_line_cell_magic)

1) - The simplest case, using functions and registering them

Our python stdlib help functionality as a line magic

In [ ]:
from IPython.core.magic import register_line_magic

# imports
import requests
import re
from IPython.display import IFrame, HTML

@register_line_magic
def stdlib_help(module):
    # list of modules
    mods = requests.get("https://docs.python.org/3/py-modindex.html")
    mods = mods.content
    modules = re.findall(r'library/([^\'" >]+).html', str(mods))
    
    # Check if argument is a stdlib module
    if module in modules:
        url = "https://docs.python.org/3/library/{0}.html#module-{0}"
        return IFrame(url.format(module), width = "100%", height = "400px")
    else:
        return HTML("<p><strong>"+module+"</strong> is not part of the CPython3.4 stdlib</p>")
In [ ]:
%stdlib_help re
In [ ]:
%stdlib_help regex

2) - Inheriting from IPython.core.magic.Magics

It is pretty similar to the previous example with some steps more that add some extra functionality: magics can potentially hold state in between calls, and magics can have full access to the main IPython object. In the present case it wouldn't be necessary so the simplest way (the first one) would be enough.

In [ ]:
from IPython.core.magic import Magics, magics_class, line_magic

# imports
import requests
import re
from IPython.display import IFrame, HTML

@magics_class
class ItIsMagic(Magics):
    
    @register_line_magic
    def stdlib_help2(module):
        # list of modules
        mods = requests.get("https://docs.python.org/3/py-modindex.html")
        mods = mods.content
        modules = re.findall(r'library/([^\'" >]+).html', str(mods))

        # Check if argument is a stdlib module
        if module in modules:
            url = "https://docs.python.org/3/library/{0}.html#module-{0}"
            return IFrame(url.format(module), width = "100%", height = "400px")
        else:
            return HTML("<p><strong>"+module+"</strong> is not part of the CPython3.4 stdlib</p>")

# In order to actually use these magics, you must register them with a
# running IPython.  This code must be placed in a file that is loaded once
# IPython is up and running:
ip = get_ipython()
# You can register the class itself without instantiating it.  IPython will
# call the default constructor on it.
ip.register_magics(ItIsMagic)
In [ ]:
%stdlib_help2 __future__
In [ ]:
%stdlib_help2 make_the_web_I_have_in_mind

Another tiny/dumb example

This is something I had in mind but Jake Vanderplas was faster than me (not a surprise!!!).

...

Complete twitter conversation here

In [ ]:
from IPython.display import IFrame
from IPython.core.magic import register_line_magic

@register_line_magic
def ddg(arg):
    phrase = arg.replace(' ', '+')
    url = "https://duckduckgo.com/?&q={0}".format(phrase)
    print(url)
    return IFrame(url, "100%", 400)
In [ ]:
%ddg ipython

It is so easy to find new possibilities

But there are pages that are not embeddable like google.com, stackoverflow.com,...

To check if a page is not able to be seen on an `iframe` you can use the following code:

In [ ]:
import requests

g = requests.get("http://www.google.com")

g.headers['X-Frame-Options']

If the result is SAMEORIGIN or DENY or ..., then you cannot embed that url in an iframe.

Other explained examples

http://pybonacci.org/2014/01/24/157-cosas-de-ipython-que-no-sabias-y-nunca-preguntaste-i/ (in Spanish)

http://nbviewer.ipython.org/urls/gist.github.com/bj0/5343292/raw/23a0845ee874827e3635edb0bf5701710a537bfc/jinja2.ipynb (in English)

http://nbviewer.ipython.org/github/ipython-books/cookbook-code/blob/master/notebooks/chapter01_basic/04_magic.ipynb (in English, BTW, it is part of an excellent book "IPython Interactive Computing and Visualization Cookbook" written by Cyrille Rossant)