tutorial.txt
160 lines
| 6.5 KiB
| text/plain
|
TextLexer
|
r1258 | .. _tutorial: | ||
====================== | ||||
|
r4087 | Introducing IPython | ||
|
r1258 | ====================== | ||
|
r4087 | You don't need to know anything beyond Python to start using IPython – just type | ||
commands as you would at the standard Python prompt. But IPython can do much | ||||
more than the standard prompt. Some key features are described here. For more | ||||
information, check the :ref:`tips page <tips>`, or look at examples in the | ||||
|
r4880 | `IPython cookbook <http://wiki.ipython.org/index.php?title=Cookbook>`_. | ||
|
r2276 | |||
|
r4087 | If you've never used Python before, you might want to look at `the official | ||
tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into | ||||
Python <http://diveintopython.org/toc/index.html>`_. | ||||
|
r2276 | |||
|
r4087 | Tab completion | ||
============== | ||||
|
r1258 | |||
|
r4087 | Tab completion, especially for attributes, is a convenient way to explore the | ||
structure of any object you're dealing with. Simply type ``object_name.<TAB>`` | ||||
to view the object's attributes (see :ref:`the readline section <readline>` for | ||||
more). Besides Python objects and keywords, tab completion also works on file | ||||
and directory names. | ||||
|
r1258 | |||
|
r4087 | Exploring your objects | ||
====================== | ||||
|
r1258 | |||
|
r4087 | Typing ``object_name?`` will print all sorts of details about any object, | ||
including docstrings, function definition lines (for call arguments) and | ||||
constructor details for classes. To get specific information on an object, you | ||||
can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile`` | ||||
|
r1258 | |||
|
r4087 | Magic functions | ||
=============== | ||||
|
r1258 | |||
|
r4087 | IPython has a set of predefined 'magic functions' that you can call with a | ||
command line style syntax. These include: | ||||
|
r1258 | |||
|
r4087 | - Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``, | ||
``%recall``, etc. | ||||
- Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``, etc. | ||||
- Other functions such as ``%reset``, ``%timeit`` or ``%paste``. | ||||
|
r1258 | |||
|
r4087 | You can always call these using the % prefix, and if you're typing one on a line | ||
by itself, you can omit even that:: | ||||
run thescript.py | ||||
For more details on any magic function, call ``%somemagic?`` to read its | ||||
docstring. To see all the available magic functions, call ``%lsmagic``. | ||||
Running and Editing | ||||
------------------- | ||||
|
r1258 | |||
|
r1695 | The %run magic command allows you to run any python script and load all of its | ||
data directly into the interactive namespace. Since the file is re-read from | ||||
|
r4087 | disk each time, changes you make to it are reflected immediately (unlike | ||
imported modules, which have to be specifically reloaded). IPython also includes | ||||
:ref:`dreload <dreload>`, a recursive reload function. | ||||
%run has special flags for timing the execution of your scripts (-t), or for | ||||
running them under the control of either Python's pdb debugger (-d) or | ||||
profiler (-p). | ||||
The %edit command gives a reasonable approximation of multiline editing, | ||||
by invoking your favorite editor on the spot. IPython will execute the | ||||
code you type in there as if it were typed interactively. | ||||
Debugging | ||||
--------- | ||||
After an exception occurs, you can call ``%debug`` to jump into the Python | ||||
debugger (pdb) and examine the problem. Alternatively, if you call ``%pdb``, | ||||
IPython will automatically start the debugger on any uncaught exception. You can | ||||
print variables, see code, execute statements and even walk up and down the | ||||
call stack to track down the true source of the problem. Running programs with | ||||
%run and pdb active can be an efficient way to develop and debug code, in many | ||||
cases eliminating the need for print statements or external debugging tools. | ||||
You can also step through a program from the beginning by calling | ||||
``%run -d theprogram.py``. | ||||
History | ||||
======= | ||||
IPython stores both the commands you enter, and the results it produces. You | ||||
can easily go through previous commands with the up- and down-arrow keys, or | ||||
access your history in more sophisticated ways. | ||||
Input and output history are kept in variables called ``In`` and ``Out``, which | ||||
can both be indexed by the prompt number on which they occurred, e.g. ``In[4]``. | ||||
The last three objects in output history are also kept in variables named ``_``, | ||||
``__`` and ``___``. | ||||
You can use the ``%history`` magic function to examine past input and output. | ||||
Input history from previous sessions is saved in a database, and IPython can be | ||||
configured to save output history. | ||||
Several other magic functions can use your input history, including ``%edit``, | ||||
``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a | ||||
standard format to refer to lines:: | ||||
%pastebin 3 18-20 ~1/1-5 | ||||
This will take line 3 and lines 18 to 20 from the current session, and lines | ||||
1-5 from the previous session. | ||||
System shell commands | ||||
===================== | ||||
To run any command at the system shell, simply prefix it with !, e.g.:: | ||||
!ping www.bbc.co.uk | ||||
You can capture the output into a Python list, e.g.: ``files = !ls``. To pass | ||||
the values of Python variables or expressions to system commands, prefix them | ||||
with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section | ||||
<system_shell_access>` for more details. | ||||
|
r2578 | |||
|
r1258 | Define your own system aliases | ||
------------------------------ | ||||
|
r4087 | It's convenient to have aliases to the system commands you use most often. | ||
|
r1258 | This allows you to work seamlessly from inside IPython with the same commands | ||
you are used to in your system shell. IPython comes with some pre-defined | ||||
aliases and a complete system for changing directories, both via a stack (see | ||||
%pushd, %popd and %dhist) and via direct %cd. The latter keeps a history of | ||||
visited directories and allows you to go to any previously visited one. | ||||
|
r4087 | Configuration | ||
============= | ||||
|
r1258 | |||
|
r4087 | Much of IPython can be tweaked through configuration. To get started, use the | ||
command ``ipython profile create`` to produce the default config files. These | ||||
will be placed in :file:`~/.ipython/profile_default` or | ||||
:file:`~/.config/ipython/profile_default`, and contain comments explaining what | ||||
the various options do. | ||||
|
r1258 | |||
|
r4087 | Profiles allow you to use IPython for different tasks, keeping separate config | ||
files and history for each one. More details in :ref:`the profiles section | ||||
<profiles>`. | ||||
|
r2275 | |||
|
r5248 | Startup Files | ||
------------- | ||||
If you want some code to be run at the beginning of every IPython session, the | ||||
easiest way is to add Python (.py) or IPython (.ipy) scripts to your | ||||
:file:`<profile>/startup` directory. Files in this directory will always be executed | ||||
as soon as the IPython shell is constructed, and before any other code or scripts | ||||
you have specified. If you have multiple files in the startup directory, they will | ||||
be run in lexicographical order, so you can control the ordering by adding a '00-' | ||||
prefix. | ||||
.. note:: | ||||
Automatic startup files are new in IPython 0.12. Use the | ||||
InteractiveShellApp.exec_files configurable for similar behavior in 0.11. | ||||
|
r2275 | |||