usage.py
480 lines
| 19.4 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 | |||
Fernando Perez
|
r2427 | This file typically installed in the $HOME/.ipython directory. 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 | ||
installation, or online at http://ipython.scipy.org. | ||||
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 = """\ | ||
=============================== | ||||
The IPython graphical console | ||||
=============================== | ||||
This console is designed to emulate in many aspects the look, feel and workflow | ||||
typical of a terminal environment, but it adds support for 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. | ||||
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 | ||||
terminal IPython: single expressions are immediately evaluated *if the cursor | ||||
is at the end of the line*, and indented blocks are evaluated once a single | ||||
blank line is entered:: | ||||
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 have a single expression and you go back to edit something in the | ||||
beginning, hitting ``Enter`` will split the line (like a text editor) instead | ||||
of executing it. To execute, you can either go to the end of the line to hit | ||||
``Enter``, or hit ``Shift-Enter`` anywhere, which is the 'force execution' | ||||
keybinding. | ||||
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 | ||||
cell is executed as if it was a script. A few examples should clarify this:: | ||||
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 | ||||
many intermediate blank lines and they won't cause any problems. You can then | ||||
make it execute by appending a blank line *at the end* or hitting | ||||
``Shift-Enter`` anywhere within the cell. | ||||
With the up arrow key, you can retrieve previous blocks of input that contain | ||||
multiple lines. You can move inside of it 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). | ||||
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 | ||||
============ | ||||
The IPython console supports most of the basic Emacs line-oriented | ||||
keybindings, in addition to some of its own. | ||||
The keybinding prefixes mean: | ||||
C : Control | ||||
S : Shift | ||||
M : Meta (typically the Alt key) | ||||
The keybindings themselves are: | ||||
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-v : paste text from clipboard. | ||||
C-z : undo (retrieves lost text if you move out of a cell with the arrows). | ||||
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-d : delete next word. | ||||
M-Backspace : delete previous word. | ||||
C-. : forced restart of the kernel (a confirmation dialog appears). | ||||
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: | ||||
- default: it is overlaid on top of the main terminal. You must quit the pager | ||||
to get back to the terminal (similar to how a kkk pager such as ``less`` | ||||
works). | ||||
- vertical: the console is made double-tall, and the pager appears on the | ||||
bottom area when needed. You can view its contents while using the terminal. | ||||
- horizontal: the console is made double-wide, and the pager appears on the | ||||
right area when needed. You can view its contents while using the terminal. | ||||
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. | ||||
In all cases, the ``q`` or ``Escape`` keys quit the pager. | ||||
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 | ||||
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`` (aliased to ``%more``), ``%clear`` to | ||||
clear the terminal, and ``%man`` on Linux/OSX to cover the most common commands | ||||
you'd want to call in your subshell, but you need to be aware of this | ||||
limitation. | ||||
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 | ||||
rendered inline automatically. If started with ``--pylab`` or ``--pylab | ||||
<your backend>``, then a GUI backend will be used, but the ``paste()`` function | ||||
is added to the global and ``plt`` namespaces. You can paste any figure that | ||||
is currently open in a window with this function; type ``paste?`` for | ||||
additional details.""" | ||||
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) | ||||