.. include:: <s5defs.txt>

============================================
 Python and the Interactive Shell 'IPython'
============================================

:Author: Jeff Rush
:Copyright: 2007 Tau Productions Inc.
:License: Creative Commons Attribution-ShareAlike 3.0
:Date: June 26, 2007
:Version: 1
:Series: 5-Minutes with Python

A 5-minute introduction to the enhanced interactive shell 'IPython'.  Superior
to the default Python shell, IPython provides power object introspection
features, easy access to operating system commands and text editor integration.

.. footer:: 5-Minutes with Python: Series

.. |CLICK| image:: /home/caster/themes/screencast-800x600/NextSlide.png

.. container:: handout

   Hello, my name is Jeff Rush and this talk is part of the "5-Minutes with
   Python" series.  In this brief talk I'll provide a comprehensive survey of
   the capabilities of the enhanced interactive shell known as "IPython".

   If it looks like something you might want to investigate further, there is
   a follow-up talk entitled "A Demonstration of the 'IPython' Interactive
   Shell" that gets more into the details using an interactive demonstration.


Roadmap to Talk
===============

.. container:: slide-display

   + `What is it and why use it?`
   + `How does it behave at the prompt?`
   + `Looking Up Information`
   + `Issuing System Commands`
   + `Manipulating Multiline Source`
   + `Instrumenting Your Source`
   + `For Further Investigation`

.. contents:: Table of Contents
   :class: handout

.. container:: handout

   |CLICK| In this talk I'll define what IPython is, why you might want to use
   it, and generally |CLICK| what mechanisms it adds to the interactive
   prompt.

   |CLICK| I'll cover the introspection capabilities it gives you,

   |CLICK| how it provides seamless access to the commands of your system
   shell, and |CLICK| integrates with your choice of text editors, allowing
   you to work in an iterative fashion.

   |CLICK| And I'll talk about how IPython can be hooked into your own
   programs, the execution profiling it offers and how you can add extra
   information to your tracebacks.

   |CLICK| I'll conclude with where to get IPython and what resources are
   available in that community.


What Is It?
===========

 + `an alternative to the default shell`
 + `non-GUI in nature`
 + `cross-platform and free`
 + `invocable from within programs`
    + `explicitly for code examination`
    + `implicitly upon uncaught exceptions`

.. container:: handout

   |CLICK| IPython is an alternative to the default Python shell,
   increasing your effectiveness at the interactive prompt while retaining its
   familiarity and keyboard friendliness.

   |CLICK| Like the default shell, it is a text-based, non-GUI method of
   interaction.  However it does have good support to run side-by-side with
   various 2-d and 3-d data plotting libraries and GUI toolkits.

   |CLICK| IPython runs on all the popular operating systems and it is free
   software so you can use it everywhere.

   |CLICK| It can be easily invoked from within your programs, either

   |CLICK| implicitly upon occurrence of an uncaught exception, or

   |CLICK| explicitly to put you into an interactive environment with the
   variable namespace current at that point.

   This makes IPython useful for both debugging and for those blended types of
   programs with heavy computation intermixed with exploration of the results,
   as in scientific data visualization.


Why Use It?
===========

 + `object introspection on steroids`
 + `access to the system command-shell`
 + `extensible into a domain-specific command language`
 + `can use your own text editor`

.. container:: handout

   |CLICK| IPython gives you the ability to powerfully introspect an object,
   showing its docstring, call signature, online help pages or source code.

   |CLICK| You can enter system commands, change directories and edit source
   files, while remaining within IPython.  This is especially nice for those
   platforms that lack a good command-line shell.

   |CLICK| IPython has what are called "magic" commands, which provide
   high-level functions that control the behavior of IPython itself.  You can
   define your own such commands and in combination with an input-filtering
   capability of IPython, construct a command language specific to the problem
   domain at hand.

   |CLICK| IPython is friendly to those of us who are particular to our text
   editors, moving source seamlessly back and forth between the editor and
   IPython while not forcing the use of a specific IDE text editor.


At the Prompt
=============

 + `caches the last N commands and their output`
 + `view, log, save, replay and edit this history`
 + `has a concept of namespaces`
 + `interprets names, by precedence`
    + `variables`
    + `magic commands`
    + `shell command aliases`

.. container:: handout

   |CLICK| At the prompt, IPython caches your most recent inputs, along with
   the output they generated.

   |CLICK| This command history is easily viewed, logged to a file and
   selectively saved into source files.  You can bring portions into your
   editor and have changes reevaluated into your session.  And you can quickly
   convert groups of frequently used commands into named macros.

   |CLICK| IPython, like the default Python shell, gives you access to the
   interactive namespace, for manipulating variables.  However it also
   provides easy ways to filter and display groups of variables, and to reset
   the namespace to its startup state.

   |CLICK| Because IPython accepts magic and system commands as well as source
   code, IPython uses rules to decide how to interpret a name when entered.

   |CLICK| If there is a variable with that name, it displays its value.

   |CLICK| Otherwise it consults a registry of "magic commands", essentially
   special names that invoke functions that manipulate your IPython session,
   navigate directories and manage files.

   |CLICK| And last it looks up the name in a list of aliases that map to
   commands issued to the underlying system shell.


Looking Things Up
=================

 + `input history and namespaces are searchable`
 + `tab completion`
    + `keywords, methods, variables, files`
 + `get brief and full info on any object`

.. container:: handout

   IPython gives you a number of ways to quickly look up information,
   almost eliminating the need to keep reference manuals at hand.

   |CLICK| The input history and variable namespaces are fully searchable by
   wildcard and type of object.

   |CLICK| IPython provides extensive tab-completion features, |CLICK|
   expanding names into variables, directories and filenames.  It understands
   nested namespaces in that you can type partial expressions like "classname
   dot <TAB>" and have it display the methods and attributes available to you.

   |CLICK| And you can query an object for information about its type, the
   namespace in which it is located, the source file from which it was loaded,
   and its docstring.  You can also display the source fragment that defined
   it, and its call signature if the object is callable.


Issuing System Commands
=======================

 + `! escape mechanism`
 + `aliases relate text to commands`
 + `command output into vars`
 + `var substitution into commands`
 + `directory navigation`
 + `background threading`

.. container:: handout

   |CLICK| Arbitrary system commands can be entered by prefixing them with the
   exclamation or *bang* symbol, as a common shell escape mechanism.

   |CLICK| Commands, perhaps with default arguments, can be aliased to a
   simple name, for easier use.

   |CLICK| Command output, optionally split on linebreaks or spaces, can be
   collected into Python variables,

   |CLICK| and in turn, variables can be substituted into commands.

   |CLICK| The system shell mechanism for IPython comes with a rich set of
   directory navigation commands, with bookmarking, history and a pushdown
   stack of visited places.  This makes working with complex frameworks across
   directory trees much easier.

   |CLICK| And you can cause arbitrary Python expressions to be executed in
   background threads and, with the extended version of IPython called
   IPython1, distributed across multiple CPU cores or host machines.


Manipulating Multiline Source
=============================

 + `line-oriented, not multiline`
 + `magic command: %edit`
    + `of files,` `objects,` `lines of input`
 + `automatic rentry of editor upon syntax error`
 + `simple source versioning`

.. container:: handout

   IPython is |CLICK| line-oriented -- while you can scroll back, change and
   rerun previous inputs, that would be awkward for definitions of functions
   or classes.

   |CLICK| IPython provides a magic "edit" command, that invokes your
   text editor on various kinds of targets.  Upon saving and exiting from your
   editor, the source is reevaluated into the current interactive namespace.

   |CLICK| You can pass to "edit" the name of a file you wish to change.

   |CLICK| But you can also pass an object reference.  IPython will look up
   the source file from which it came, invoke your editor on that file,
   and position you at the the definition.  Very cool.

   |CLICK| And you can pass the line numbers of previous inputs, as a range or
   list, and their text will loaded together into your editor.  Upon exit, each
   line will be re-evaluated into the current namespace.

   |CLICK| We've all made a quick change in our editor, only to find out at
   runtime that we've made a trivial syntax error.  IPython, upon reloading
   your source after an edit, can detect that syntax error and automatically
   take you back into the editor at the point it occurred.

   |CLICK| IPython provides a lightweight form of version control over edits.
   By retaining an historical copy of the result of each command, including
   edits, you can pass in a input line number representing a previous state,
   letting you revise and reload from that point.  Quite useful when teaching
   or demonstrating.


Instrumenting Your Source
=========================

 + `can be invoked from within your programs`
 + `uncaught exceptions enter the debugger`
 + `measure execution time of code fragments`
 + `integration with Python profiler`
 + `extended tracebacks with color`

.. container:: handout

   IPython provides ways to instrument your source with useful diagnostics.

   |CLICK| You can put calls in your program to start up an interactive
   session, giving you access to the variable namespace at that point.

   |CLICK| You can set IPython to enter the Python debugger upon the
   occurrence of an uncaught exception, letting you walk the stack frame and
   query variables.

   |CLICK| You can measure the CPU or wallclock execution time of code
   fragments, or |CLICK| run your code under the Python profiler for more
   detailed measurements.

   |CLICK| And you can set your preferred display of Python tracebacks,
   colorized for readability and with an extended mode that shows more
   information.


For Further Investigation
=========================

 + `http://ipython.scipy.org/moin/`
    + `users and developers mailing lists`
    + `online documentation`
    + `bug and feature request tracking system`
    + `articles, videos and presentations`
 + `Contact:`
    `Jeff Rush <jeff@taupro.com>`

.. container:: handout

   |CLICK| IPython is a mature, exciting project with a strong community.

   |CLICK| It has active mailing lists, separate for users and maintainers.

   |CLICK| A complete manual is available for browsing online or as a PDF
   document.

   |CLICK| And it has a tracking system for bug reports and feature requests.

   |CLICK| The project website provides magazine articles, video tutorials and
   slide presentations.

   I recommend you check it out.  There are other aspects of IPython I have
   not covered such as usage tips and techniques along with contributed
   extensions and profiles.

   |CLICK| |CLICK| Thanks for listening and look for the longer talk that
   demonstrates the actual use of IPython.

   These slides and script are available under the Creative Commons
   Attribute-ShareAlike license, for use in your own presentations.

..
   Local Variables:
   mode: rst
   mode: outline-minor
   End: