usage.py
509 lines
| 20.7 KiB
| text/x-python
|
PythonLexer
fperez
|
r0 | # -*- coding: utf-8 -*- | ||
Fernando Perez
|
r2427 | """Usage information for the main IPython applications. | ||
""" | ||||
#----------------------------------------------------------------------------- | ||||
# Copyright (C) 2008-2010 The IPython Development Team | ||||
# Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu> | ||||
fperez
|
r0 | # | ||
# Distributed under the terms of the BSD License. The full license is in | ||||
# the file COPYING, distributed as part of this software. | ||||
Fernando Perez
|
r2427 | #----------------------------------------------------------------------------- | ||
fperez
|
r0 | |||
Brian Granger
|
r2202 | import sys | ||
from IPython.core import release | ||||
Fernando Perez
|
r2427 | cl_usage = """\ | ||
ipython [options] [files] | ||||
fperez
|
r0 | |||
Fernando Perez
|
r2427 | IPython: an enhanced interactive Python shell. | ||
fperez
|
r0 | |||
Fernando Perez
|
r2427 | A Python shell with automatic history (input and output), dynamic object | ||
introspection, easier configuration, command completion, access to the | ||||
system shell and more. IPython can also be embedded in running programs. | ||||
fperez
|
r0 | |||
Fernando Perez
|
r2427 | If invoked with no options, it executes all the files listed in sequence | ||
and exits, use -i to enter interactive mode after running the files. Files | ||||
ending in .py will be treated as normal Python, but files ending in .ipy | ||||
can contain special IPython syntax (magic commands, shell expansions, etc.) | ||||
fperez
|
r0 | |||
Fernando Perez
|
r2427 | Please note that some of the configuration options are not available at the | ||
command line, simply because they are not practical here. Look into your | ||||
ipython_config.py configuration file for details on those. | ||||
fperez
|
r0 | |||
MinRK
|
r3351 | This file is typically installed in the IPYTHON_DIR directory. For Linux | ||
users, this will be $HOME/.config/ipython, and for other users it will be | ||||
$HOME/.ipython. For Windows users, $HOME resolves to C:\\Documents and | ||||
Settings\\YourUserName in most instances. | ||||
fperez
|
r0 | |||
Fernando Perez
|
r2427 | In IPython's documentation, we will refer to this directory as IPYTHON_DIR, | ||
you can change its default location by setting any path you want in this | ||||
environment variable. | ||||
fperez
|
r0 | |||
Fernando Perez
|
r2427 | For more information, see the manual available in HTML and PDF in your | ||
Thomas Kluyver
|
r4086 | installation, or online at http://ipython.org/documentation.html. | ||
fperez
|
r0 | """ | ||
interactive_usage = """ | ||||
IPython -- An enhanced Interactive Python | ||||
========================================= | ||||
IPython offers a combination of convenient shell features, special commands | ||||
and a history mechanism for both input (command history) and output (results | ||||
caching, similar to Mathematica). It is intended to be a fully compatible | ||||
replacement for the standard Python interpreter, while offering vastly | ||||
improved functionality and flexibility. | ||||
At your system command line, type 'ipython -help' to see the command line | ||||
options available. This document only describes interactive features. | ||||
Warning: IPython relies on the existence of a global variable called __IP which | ||||
controls the shell itself. If you redefine __IP to anything, bizarre behavior | ||||
will quickly occur. | ||||
MAIN FEATURES | ||||
* Access to the standard Python help. As of Python 2.1, a help system is | ||||
available with access to object docstrings and the Python manuals. Simply | ||||
type 'help' (no quotes) to access it. | ||||
* Magic commands: type %magic for information on the magic subsystem. | ||||
* System command aliases, via the %alias command or the ipythonrc config file. | ||||
* Dynamic object information: | ||||
Typing ?word or word? prints detailed information about an object. If | ||||
certain strings in the object are too long (docstrings, code, etc.) they get | ||||
snipped in the center for brevity. | ||||
Typing ??word or word?? gives access to the full information without | ||||
snipping long strings. Long strings are sent to the screen through the less | ||||
pager if longer than the screen, printed otherwise. | ||||
The ?/?? system gives access to the full source code for any object (if | ||||
available), shows function prototypes and other useful information. | ||||
If you just want to see an object's docstring, type '%pdoc object' (without | ||||
quotes, and without % if you have automagic on). | ||||
Both %pdoc and ?/?? give you access to documentation even on things which are | ||||
not explicitely defined. Try for example typing {}.get? or after import os, | ||||
type os.path.abspath??. The magic functions %pdef, %source and %file operate | ||||
similarly. | ||||
* Completion in the local namespace, by typing TAB at the prompt. | ||||
At any time, hitting tab will complete any available python commands or | ||||
variable names, and show you a list of the possible completions if there's | ||||
no unambiguous one. It will also complete filenames in the current directory. | ||||
This feature requires the readline and rlcomplete modules, so it won't work | ||||
if your Python lacks readline support (such as under Windows). | ||||
* Search previous command history in two ways (also requires readline): | ||||
- Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to | ||||
search through only the history items that match what you've typed so | ||||
far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like | ||||
normal arrow keys. | ||||
- Hit Ctrl-r: opens a search prompt. Begin typing and the system searches | ||||
your history for lines that match what you've typed so far, completing as | ||||
much as it can. | ||||
* Persistent command history across sessions (readline required). | ||||
* Logging of input with the ability to save and restore a working session. | ||||
* System escape with !. Typing !ls will run 'ls' in the current directory. | ||||
* The reload command does a 'deep' reload of a module: changes made to the | ||||
module since you imported will actually be available without having to exit. | ||||
* Verbose and colored exception traceback printouts. See the magic xmode and | ||||
xcolor functions for details (just type %magic). | ||||
* Input caching system: | ||||
IPython offers numbered prompts (In/Out) with input and output caching. All | ||||
input is saved and can be retrieved as variables (besides the usual arrow | ||||
key recall). | ||||
The following GLOBAL variables always exist (so don't overwrite them!): | ||||
_i: stores previous input. | ||||
_ii: next previous. | ||||
_iii: next-next previous. | ||||
_ih : a list of all input _ih[n] is the input from line n. | ||||
Additionally, global variables named _i<n> are dynamically created (<n> | ||||
being the prompt counter), such that _i<n> == _ih[<n>] | ||||
For example, what you typed at prompt 14 is available as _i14 and _ih[14]. | ||||
You can create macros which contain multiple input lines from this history, | ||||
for later re-execution, with the %macro function. | ||||
The history function %hist allows you to see any part of your input history | ||||
by printing a range of the _i variables. Note that inputs which contain | ||||
magic functions (%) appear in the history with a prepended comment. This is | ||||
because they aren't really valid Python code, so you can't exec them. | ||||
* Output caching system: | ||||
For output that is returned from actions, a system similar to the input | ||||
cache exists but using _ instead of _i. Only actions that produce a result | ||||
(NOT assignments, for example) are cached. If you are familiar with | ||||
Mathematica, IPython's _ variables behave exactly like Mathematica's % | ||||
variables. | ||||
The following GLOBAL variables always exist (so don't overwrite them!): | ||||
_ (one underscore): previous output. | ||||
__ (two underscores): next previous. | ||||
___ (three underscores): next-next previous. | ||||
Global variables named _<n> are dynamically created (<n> being the prompt | ||||
counter), such that the result of output <n> is always available as _<n>. | ||||
Finally, a global dictionary named _oh exists with entries for all lines | ||||
which generated output. | ||||
* Directory history: | ||||
Your history of visited directories is kept in the global list _dh, and the | ||||
magic %cd command can be used to go to any entry in that list. | ||||
* Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython) | ||||
1. Auto-parentheses | ||||
Callable objects (i.e. functions, methods, etc) can be invoked like | ||||
this (notice the commas between the arguments): | ||||
>>> callable_ob arg1, arg2, arg3 | ||||
and the input will be translated to this: | ||||
--> callable_ob(arg1, arg2, arg3) | ||||
You can force auto-parentheses by using '/' as the first character | ||||
of a line. For example: | ||||
>>> /globals # becomes 'globals()' | ||||
Note that the '/' MUST be the first character on the line! This | ||||
won't work: | ||||
>>> print /globals # syntax error | ||||
In most cases the automatic algorithm should work, so you should | ||||
rarely need to explicitly invoke /. One notable exception is if you | ||||
are trying to call a function with a list of tuples as arguments (the | ||||
parenthesis will confuse IPython): | ||||
In [1]: zip (1,2,3),(4,5,6) # won't work | ||||
but this will work: | ||||
In [2]: /zip (1,2,3),(4,5,6) | ||||
------> zip ((1,2,3),(4,5,6)) | ||||
Out[2]= [(1, 4), (2, 5), (3, 6)] | ||||
IPython tells you that it has altered your command line by | ||||
displaying the new command line preceded by -->. e.g.: | ||||
In [18]: callable list | ||||
-------> callable (list) | ||||
2. Auto-Quoting | ||||
You can force auto-quoting of a function's arguments by using ',' as | ||||
the first character of a line. For example: | ||||
>>> ,my_function /home/me # becomes my_function("/home/me") | ||||
If you use ';' instead, the whole argument is quoted as a single | ||||
string (while ',' splits on whitespace): | ||||
>>> ,my_function a b c # becomes my_function("a","b","c") | ||||
>>> ;my_function a b c # becomes my_function("a b c") | ||||
Note that the ',' MUST be the first character on the line! This | ||||
won't work: | ||||
>>> x = ,my_function /home/me # syntax error | ||||
""" | ||||
vivainio
|
r154 | |||
Brian Granger
|
r2202 | interactive_usage_min = """\ | ||
An enhanced console for Python. | ||||
Some of its features are: | ||||
- Readline support if the readline library is present. | ||||
- Tab completion in the local namespace. | ||||
- Logging of input, see command-line options. | ||||
- System shell escape via ! , eg !ls. | ||||
- Magic commands, starting with a % (like %ls, %pwd, %cd, etc.) | ||||
- Keeps track of locally defined variables via %who, %whos. | ||||
- Show object information with a ? eg ?x or x? (use ?? for more info). | ||||
""" | ||||
vivainio
|
r154 | quick_reference = r""" | ||
IPython -- An enhanced Interactive Python - Quick Reference Card | ||||
================================================================ | ||||
fperez
|
r834 | obj?, obj?? : Get help, or more help for object (also works as | ||
?obj, ??obj). | ||||
?foo.*abc* : List names in 'foo' containing 'abc' in them. | ||||
%magic : Information about IPython's 'magic' % functions. | ||||
vivainio
|
r154 | |||
vivainio
|
r824 | Magic functions are prefixed by %, and typically take their arguments without | ||
parentheses, quotes or even commas for convenience. | ||||
Example magic function calls: | ||||
vivainio
|
r154 | %alias d ls -F : 'd' is now an alias for 'ls -F' | ||
alias d ls -F : Works if 'alias' not a python name | ||||
alist = %alias : Get list of aliases to 'alist' | ||||
vivainio
|
r824 | cd /usr/share : Obvious. cd -<tab> to choose from visited dirs. | ||
%cd?? : See help AND source for magic %cd | ||||
vivainio
|
r154 | |||
System commands: | ||||
!cp a.txt b/ : System command escape, calls os.system() | ||||
vivainio
|
r203 | cp a.txt b/ : after %rehashx, most system commands work without ! | ||
vivainio
|
r154 | cp ${f}.txt $bar : Variable expansion in magics and system commands | ||
vivainio
|
r203 | files = !ls /usr : Capture sytem command output | ||
vivainio
|
r154 | files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc' | ||
History: | ||||
_i, _ii, _iii : Previous, next previous, next next previous input | ||||
vivainio
|
r503 | _i4, _ih[2:5] : Input history line 4, lines 2-4 | ||
exec _i81 : Execute input history line #81 again | ||||
vivainio
|
r811 | %rep 81 : Edit input history line #81 | ||
vivainio
|
r154 | _, __, ___ : previous, next previous, next next previous output | ||
_dh : Directory history | ||||
_oh : Output history | ||||
vivainio
|
r824 | %hist : Command history. '%hist -g foo' search history for 'foo' | ||
vivainio
|
r154 | |||
Autocall: | ||||
vivainio
|
r203 | f 1,2 : f(1,2) | ||
/f 1,2 : f(1,2) (forced autoparen) | ||||
vivainio
|
r154 | ,f 1 2 : f("1","2") | ||
;f 1 2 : f("1 2") | ||||
vivainio
|
r824 | Remember: TAB completion works in many contexts, not just file names | ||
or python names. | ||||
The following magic functions are currently available: | ||||
vivainio
|
r154 | """ | ||
Brian Granger
|
r2202 | |||
Fernando Perez
|
r3008 | gui_reference = """\ | ||
=============================== | ||||
Fernando Perez
|
r3015 | The graphical IPython console | ||
Fernando Perez
|
r3008 | =============================== | ||
Fernando Perez
|
r3015 | This console is designed to emulate the look, feel and workflow of a terminal | ||
environment, while adding a number of enhancements that are simply not possible | ||||
in a real terminal, such as inline syntax highlighting, true multiline editing, | ||||
inline graphics and much more. | ||||
Fernando Perez
|
r3008 | |||
This quick reference document contains the basic information you'll need to | ||||
know to make the most efficient use of it. For the various command line | ||||
options available at startup, type ``--help`` at the command line. | ||||
Multiline editing | ||||
================= | ||||
The graphical console is capable of true multiline editing, but it also tries | ||||
to behave intuitively like a terminal when possible. If you are used to | ||||
IPyhton's old terminal behavior, you should find the transition painless, and | ||||
once you learn a few basic keybindings it will be a much more efficient | ||||
environment. | ||||
For single expressions or indented blocks, the console behaves almost like the | ||||
epatters
|
r3021 | terminal IPython: single expressions are immediately evaluated, and indented | ||
blocks are evaluated once a single blank line is entered:: | ||||
Fernando Perez
|
r3008 | |||
In [1]: print "Hello IPython!" # Enter was pressed at the end of the line | ||||
Hello IPython! | ||||
In [2]: for i in range(10): | ||||
...: print i, | ||||
...: | ||||
0 1 2 3 4 5 6 7 8 9 | ||||
If you want to enter more than one expression in a single input block | ||||
(something not possible in the terminal), you can use ``Control-Enter`` at the | ||||
end of your first line instead of ``Enter``. At that point the console goes | ||||
into 'cell mode' and even if your inputs are not indented, it will continue | ||||
accepting arbitrarily many lines until either you enter an extra blank line or | ||||
you hit ``Shift-Enter`` (the key binding that forces execution). When a | ||||
multiline cell is entered, IPython analyzes it and executes its code producing | ||||
an ``Out[n]`` prompt only for the last expression in it, while the rest of the | ||||
Fernando Perez
|
r3015 | cell is executed as if it was a script. An example should clarify this:: | ||
Fernando Perez
|
r3008 | |||
In [3]: x=1 # Hit C-Enter here | ||||
...: y=2 # from now on, regular Enter is sufficient | ||||
...: z=3 | ||||
...: x**2 # This does *not* produce an Out[] value | ||||
...: x+y+z # Only the last expression does | ||||
...: | ||||
Out[3]: 6 | ||||
The behavior where an extra blank line forces execution is only active if you | ||||
are actually typing at the keyboard each line, and is meant to make it mimic | ||||
the IPython terminal behavior. If you paste a long chunk of input (for example | ||||
a long script copied form an editor or web browser), it can contain arbitrarily | ||||
Fernando Perez
|
r3015 | many intermediate blank lines and they won't cause any problems. As always, | ||
you can then make it execute by appending a blank line *at the end* or hitting | ||||
Fernando Perez
|
r3008 | ``Shift-Enter`` anywhere within the cell. | ||
With the up arrow key, you can retrieve previous blocks of input that contain | ||||
Fernando Perez
|
r3015 | multiple lines. You can move inside of a multiline cell like you would in any | ||
text editor. When you want it executed, the simplest thing to do is to hit the | ||||
force execution key, ``Shift-Enter`` (though you can also navigate to the end | ||||
and append a blank line by using ``Enter`` twice). | ||||
Fernando Perez
|
r3008 | |||
If you've edited a multiline cell and accidentally navigate out of it with the | ||||
up or down arrow keys, IPython will clear the cell and replace it with the | ||||
contents of the one above or below that you navigated to. If this was an | ||||
accident and you want to retrieve the cell you were editing, use the Undo | ||||
keybinding, ``Control-z``. | ||||
Key bindings | ||||
============ | ||||
Fernando Perez
|
r3015 | The IPython console supports most of the basic Emacs line-oriented keybindings, | ||
in addition to some of its own. | ||||
Fernando Perez
|
r3008 | |||
The keybinding prefixes mean: | ||||
Fernando Perez
|
r3015 | - ``C``: Control | ||
- ``S``: Shift | ||||
- ``M``: Meta (typically the Alt key) | ||||
Fernando Perez
|
r3008 | |||
The keybindings themselves are: | ||||
Fernando Perez
|
r3015 | - ``Enter``: insert new line (may cause execution, see above). | ||
- ``C-Enter``: force new line, *never* causes execution. | ||||
- ``S-Enter``: *force* execution regardless of where cursor is, no newline added. | ||||
- ``C-c``: copy highlighted text to clipboard (prompts are automatically stripped). | ||||
- ``C-S-c``: copy highlighted text to clipboard (prompts are not stripped). | ||||
- ``C-v``: paste text from clipboard. | ||||
- ``C-z``: undo (retrieves lost text if you move out of a cell with the arrows). | ||||
- ``C-S-z``: redo. | ||||
- ``C-o``: move to 'other' area, between pager and terminal. | ||||
- ``C-l``: clear terminal. | ||||
- ``C-a``: go to beginning of line. | ||||
- ``C-e``: go to end of line. | ||||
- ``C-k``: kill from cursor to the end of the line. | ||||
- ``C-y``: yank (paste) | ||||
- ``C-p``: previous line (like up arrow) | ||||
- ``C-n``: next line (like down arrow) | ||||
- ``C-f``: forward (like right arrow) | ||||
- ``C-b``: back (like left arrow) | ||||
- ``C-d``: delete next character. | ||||
- ``M-<``: move to the beginning of the input region. | ||||
- ``M->``: move to the end of the input region. | ||||
- ``M-d``: delete next word. | ||||
- ``M-Backspace``: delete previous word. | ||||
- ``C-.``: force a kernel restart (a confirmation dialog appears). | ||||
Fernando Perez
|
r3081 | - ``C-+``: increase font size. | ||
- ``C--``: decrease font size. | ||||
Fernando Perez
|
r3008 | |||
The IPython pager | ||||
================= | ||||
IPython will show long blocks of text from many sources using a builtin pager. | ||||
You can control where this pager appears with the ``--paging`` command-line | ||||
flag: | ||||
epatters
|
r3799 | - ``inside`` [default]: the pager is overlaid on top of the main terminal. You | ||
must quit the pager to get back to the terminal (similar to how a pager such | ||||
as ``less`` or ``more`` works). | ||||
Fernando Perez
|
r3008 | |||
epatters
|
r3799 | - ``vsplit``: the console is made double-tall, and the pager appears on the | ||
Fernando Perez
|
r3008 | bottom area when needed. You can view its contents while using the terminal. | ||
epatters
|
r3799 | - ``hsplit``: the console is made double-wide, and the pager appears on the | ||
Fernando Perez
|
r3008 | right area when needed. You can view its contents while using the terminal. | ||
epatters
|
r3799 | - ``none``: the console never pages output. | ||
Fernando Perez
|
r3008 | If you use the vertical or horizontal paging modes, you can navigate between | ||
terminal and pager as follows: | ||||
- Tab key: goes from pager to terminal (but not the other way around). | ||||
- Control-o: goes from one to another always. | ||||
- Mouse: click on either. | ||||
Fernando Perez
|
r3015 | In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the | ||
focus on the pager area). | ||||
Fernando Perez
|
r3008 | |||
Running subprocesses | ||||
==================== | ||||
The graphical IPython console uses the ``pexpect`` module to run subprocesses | ||||
when you type ``!command``. This has a number of advantages (true asynchronous | ||||
output from subprocesses as well as very robust termination of rogue | ||||
Fernando Perez
|
r3015 | subprocesses with ``Control-C``), as well as some limitations. The main | ||
limitation is that you can *not* interact back with the subprocess, so anything | ||||
that invokes a pager or expects you to type input into it will block and hang | ||||
(you can kill it with ``Control-C``). | ||||
We have provided as magics ``%less`` to page files (aliased to ``%more``), | ||||
``%clear`` to clear the terminal, and ``%man`` on Linux/OSX. These cover the | ||||
most common commands you'd want to call in your subshell and that would cause | ||||
problems if invoked via ``!cmd``, but you need to be aware of this limitation. | ||||
Fernando Perez
|
r3008 | |||
Brian Granger
|
r3288 | Display | ||
======= | ||||
The IPython console can now display objects in a variety of formats, including | ||||
HTML, PNG and SVG. This is accomplished using the display functions in | ||||
``IPython.core.display``:: | ||||
In [4]: from IPython.core.display import display, display_html | ||||
In [5]: from IPython.core.display import display_png, display_svg | ||||
Python objects can simply be passed to these functions and the appropriate | ||||
representations will be displayed in the console as long as the objects know | ||||
how to compute those representations. The easiest way of teaching objects how | ||||
to format themselves in various representations is to define special methods | ||||
Brian Granger
|
r3878 | such as: ``_repr_html_``, ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters | ||
Brian Granger
|
r3288 | can also be given custom formatter functions for various types:: | ||
In [6]: ip = get_ipython() | ||||
In [7]: html_formatter = ip.display_formatter.formatters['text/html'] | ||||
In [8]: html_formatter.for_type(Foo, foo_to_html) | ||||
For further details, see ``IPython.core.formatters``. | ||||
Fernando Perez
|
r3008 | |||
Inline matplotlib graphics | ||||
========================== | ||||
The IPython console is capable of displaying matplotlib figures inline, in SVG | ||||
format. If started with the ``--pylab inline`` flag, then all figures are | ||||
Fernando Perez
|
r3044 | rendered inline automatically. If started with ``--pylab`` or ``--pylab <your | ||
Brian Granger
|
r3288 | backend>``, then a GUI backend will be used, but IPython's ``display()`` and | ||
``getfigs()`` functions can be used to view plots inline:: | ||||
In [9]: display(*getfigs()) # display all figures inline | ||||
In[10]: display(*getfigs(1,2)) # display figures 1 and 2 inline | ||||
""" | ||||
Fernando Perez
|
r3008 | |||
Brian Granger
|
r2202 | quick_guide = """\ | ||
? -> Introduction and overview of IPython's features. | ||||
%quickref -> Quick reference. | ||||
help -> Python's own help system. | ||||
Fernando Perez
|
r3008 | object? -> Details about 'object', use 'object??' for extra details. | ||
""" | ||||
gui_note = """\ | ||||
%guiref -> A brief reference about the graphical user interface. | ||||
""" | ||||
Brian Granger
|
r2202 | |||
Brian Granger
|
r2203 | default_banner_parts = [ | ||
Fernando Perez
|
r3008 | 'Python %s\n' % (sys.version.split('\n')[0],), | ||
'Type "copyright", "credits" or "license" for more information.\n\n', | ||||
'IPython %s -- An enhanced Interactive Python.\n' % (release.version,), | ||||
Brian Granger
|
r2202 | quick_guide | ||
] | ||||
Brian Granger
|
r2203 | |||
Fernando Perez
|
r3008 | default_gui_banner_parts = default_banner_parts + [gui_note] | ||
default_banner = ''.join(default_banner_parts) | ||||
default_gui_banner = ''.join(default_gui_banner_parts) | ||||