1# -*- coding: utf-8 -*- 2"""Usage information for the main IPython applications. 3""" 4#----------------------------------------------------------------------------- 5# Copyright (C) 2008-2011 The IPython Development Team 6# Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu> 7# 8# Distributed under the terms of the BSD License. The full license is in 9# the file COPYING, distributed as part of this software. 10#----------------------------------------------------------------------------- 11 12import sys 13from IPython.core import release 14 15cl_usage = """\ 16========= 17 IPython 18========= 19 20Tools for Interactive Computing in Python 21========================================= 22 23 A Python shell with automatic history (input and output), dynamic object 24 introspection, easier configuration, command completion, access to the 25 system shell and more. IPython can also be embedded in running programs. 26 27 28Usage 29 30 ipython [subcommand] [options] [-c cmd | -m mod | file] [--] [arg] ... 31 32 If invoked with no options, it executes the file and exits, passing the 33 remaining arguments to the script, just as if you had specified the same 34 command with python. You may need to specify `--` before args to be passed 35 to the script, to prevent IPython from attempting to parse them. If you 36 specify the option `-i` before the filename, it will enter an interactive 37 IPython session after running the script, rather than exiting. Files ending 38 in .py will be treated as normal Python, but files ending in .ipy can 39 contain special IPython syntax (magic commands, shell expansions, etc.). 40 41 Almost all configuration in IPython is available via the command-line. Do 42 `ipython --help-all` to see all available options. For persistent 43 configuration, look into your `ipython_config.py` configuration file for 44 details. 45 46 This file is typically installed in the `IPYTHONDIR` directory, and there 47 is a separate configuration directory for each profile. The default profile 48 directory will be located in $IPYTHONDIR/profile_default. IPYTHONDIR 49 defaults to to `$HOME/.ipython`. For Windows users, $HOME resolves to 50 C:\\Users\\YourUserName in most instances. 51 52 To initialize a profile with the default configuration file, do:: 53 54 $> ipython profile create 55 56 and start editing `IPYTHONDIR/profile_default/ipython_config.py` 57 58 In IPython's documentation, we will refer to this directory as 59 `IPYTHONDIR`, you can change its default location by creating an 60 environment variable with this name and setting it to the desired path. 61 62 For more information, see the manual available in HTML and PDF in your 63 installation, or online at http://ipython.org/documentation.html. 64""" 65 66interactive_usage = """ 67IPython -- An enhanced Interactive Python 68========================================= 69 70IPython offers a fully compatible replacement for the standard Python 71interpreter, with convenient shell features, special commands, command 72history mechanism and output results caching. 73 74At your system command line, type 'ipython -h' to see the command line 75options available. This document only describes interactive features. 76 77MAIN FEATURES 78------------- 79 80* Access to the standard Python help with object docstrings and the Python 81 manuals. Simply type 'help' (no quotes) to invoke it. 82 83* Magic commands: type %magic for information on the magic subsystem. 84 85* System command aliases, via the %alias command or the configuration file(s). 86 87* Dynamic object information: 88 89 Typing ?word or word? prints detailed information about an object. Certain 90 long strings (code, etc.) get snipped in the center for brevity. 91 92 Typing ??word or word?? gives access to the full information without 93 snipping long strings. Strings that are longer than the screen are printed 94 through the less pager. 95 96 The ?/?? system gives access to the full source code for any object (if 97 available), shows function prototypes and other useful information. 98 99 If you just want to see an object's docstring, type '%pdoc object' (without 100 quotes, and without % if you have automagic on). 101 102* Tab completion in the local namespace: 103 104 At any time, hitting tab will complete any available python commands or 105 variable names, and show you a list of the possible completions if there's 106 no unambiguous one. It will also complete filenames in the current directory. 107 108* Search previous command history in multiple ways: 109 110 - Start typing, and then use arrow keys up/down or (Ctrl-p/Ctrl-n) to search 111 through the history items that match what you've typed so far. 112 113 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches 114 your history for lines that match what you've typed so far, completing as 115 much as it can. 116 117 - %hist: search history by index. 118 119* Persistent command history across sessions. 120 121* Logging of input with the ability to save and restore a working session. 122 123* System shell with !. Typing !ls will run 'ls' in the current directory. 124 125* The reload command does a 'deep' reload of a module: changes made to the 126 module since you imported will actually be available without having to exit. 127 128* Verbose and colored exception traceback printouts. See the magic xmode and 129 xcolor functions for details (just type %magic). 130 131* Input caching system: 132 133 IPython offers numbered prompts (In/Out) with input and output caching. All 134 input is saved and can be retrieved as variables (besides the usual arrow 135 key recall). 136 137 The following GLOBAL variables always exist (so don't overwrite them!): 138 _i: stores previous input. 139 _ii: next previous. 140 _iii: next-next previous. 141 _ih : a list of all input _ih[n] is the input from line n. 142 143 Additionally, global variables named _i<n> are dynamically created (<n> 144 being the prompt counter), such that _i<n> == _ih[<n>] 145 146 For example, what you typed at prompt 14 is available as _i14 and _ih[14]. 147 148 You can create macros which contain multiple input lines from this history, 149 for later re-execution, with the %macro function. 150 151 The history function %hist allows you to see any part of your input history 152 by printing a range of the _i variables. Note that inputs which contain 153 magic functions (%) appear in the history with a prepended comment. This is 154 because they aren't really valid Python code, so you can't exec them. 155 156* Output caching system: 157 158 For output that is returned from actions, a system similar to the input 159 cache exists but using _ instead of _i. Only actions that produce a result 160 (NOT assignments, for example) are cached. If you are familiar with 161 Mathematica, IPython's _ variables behave exactly like Mathematica's % 162 variables. 163 164 The following GLOBAL variables always exist (so don't overwrite them!): 165 _ (one underscore): previous output. 166 __ (two underscores): next previous. 167 ___ (three underscores): next-next previous. 168 169 Global variables named _<n> are dynamically created (<n> being the prompt 170 counter), such that the result of output <n> is always available as _<n>. 171 172 Finally, a global dictionary named _oh exists with entries for all lines 173 which generated output. 174 175* Directory history: 176 177 Your history of visited directories is kept in the global list _dh, and the 178 magic %cd command can be used to go to any entry in that list. 179 180* Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython) 181 182 1. Auto-parentheses 183 184 Callable objects (i.e. functions, methods, etc) can be invoked like 185 this (notice the commas between the arguments):: 186 187 In [1]: callable_ob arg1, arg2, arg3 188 189 and the input will be translated to this:: 190 191 callable_ob(arg1, arg2, arg3) 192 193 This feature is off by default (in rare cases it can produce 194 undesirable side-effects), but you can activate it at the command-line 195 by starting IPython with `--autocall 1`, set it permanently in your 196 configuration file, or turn on at runtime with `%autocall 1`. 197 198 You can force auto-parentheses by using '/' as the first character 199 of a line. For example:: 200 201 In [1]: /globals # becomes 'globals()' 202 203 Note that the '/' MUST be the first character on the line! This 204 won't work:: 205 206 In [2]: print /globals # syntax error 207 208 In most cases the automatic algorithm should work, so you should 209 rarely need to explicitly invoke /. One notable exception is if you 210 are trying to call a function with a list of tuples as arguments (the 211 parenthesis will confuse IPython):: 212 213 In [1]: zip (1,2,3),(4,5,6) # won't work 214 215 but this will work:: 216 217 In [2]: /zip (1,2,3),(4,5,6) 218 ------> zip ((1,2,3),(4,5,6)) 219 Out[2]= [(1, 4), (2, 5), (3, 6)] 220 221 IPython tells you that it has altered your command line by 222 displaying the new command line preceded by -->. e.g.:: 223 224 In [18]: callable list 225 -------> callable (list) 226 227 2. Auto-Quoting 228 229 You can force auto-quoting of a function's arguments by using ',' as 230 the first character of a line. For example:: 231 232 In [1]: ,my_function /home/me # becomes my_function("/home/me") 233 234 If you use ';' instead, the whole argument is quoted as a single 235 string (while ',' splits on whitespace):: 236 237 In [2]: ,my_function a b c # becomes my_function("a","b","c") 238 In [3]: ;my_function a b c # becomes my_function("a b c") 239 240 Note that the ',' MUST be the first character on the line! This 241 won't work:: 242 243 In [4]: x = ,my_function /home/me # syntax error 244""" 245 246interactive_usage_min = """\ 247An enhanced console for Python. 248Some of its features are: 249- Tab completion in the local namespace. 250- Logging of input, see command-line options. 251- System shell escape via ! , eg !ls. 252- Magic commands, starting with a % (like %ls, %pwd, %cd, etc.) 253- Keeps track of locally defined variables via %who, %whos. 254- Show object information with a ? eg ?x or x? (use ?? for more info). 255""" 256 257quick_reference = r""" 258IPython -- An enhanced Interactive Python - Quick Reference Card 259================================================================ 260 261obj?, obj?? : Get help, or more help for object (also works as 262 ?obj, ??obj). 263?foo.*abc* : List names in 'foo' containing 'abc' in them. 264%magic : Information about IPython's 'magic' % functions. 265 266Magic functions are prefixed by % or %%, and typically take their arguments 267without parentheses, quotes or even commas for convenience. Line magics take a 268single % and cell magics are prefixed with two %%. 269 270Example magic function calls: 271 272%alias d ls -F : 'd' is now an alias for 'ls -F' 273alias d ls -F : Works if 'alias' not a python name 274alist = %alias : Get list of aliases to 'alist' 275cd /usr/share : Obvious. cd -<tab> to choose from visited dirs. 276%cd?? : See help AND source for magic %cd 277%timeit x=10 : time the 'x=10' statement with high precision. 278%%timeit x=2**100 279x**100 : time 'x**100' with a setup of 'x=2**100'; setup code is not 280 counted. This is an example of a cell magic. 281 282System commands: 283 284!cp a.txt b/ : System command escape, calls os.system() 285cp a.txt b/ : after %rehashx, most system commands work without ! 286cp ${f}.txt $bar : Variable expansion in magics and system commands 287files = !ls /usr : Capture sytem command output 288files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc' 289 290History: 291 292_i, _ii, _iii : Previous, next previous, next next previous input 293_i4, _ih[2:5] : Input history line 4, lines 2-4 294exec _i81 : Execute input history line #81 again 295%rep 81 : Edit input history line #81 296_, __, ___ : previous, next previous, next next previous output 297_dh : Directory history 298_oh : Output history 299%hist : Command history of current session. 300%hist -g foo : Search command history of (almost) all sessions for 'foo'. 301%hist -g : Command history of (almost) all sessions. 302%hist 1/2-8 : Command history containing lines 2-8 of session 1. 303%hist 1/ ~2/ : Command history of session 1 and 2 sessions before current. 304%hist ~8/1-~6/5 : Command history from line 1 of 8 sessions ago to 305 line 5 of 6 sessions ago. 306%edit 0/ : Open editor to execute code with history of current session. 307 308Autocall: 309 310f 1,2 : f(1,2) # Off by default, enable with %autocall magic. 311/f 1,2 : f(1,2) (forced autoparen) 312,f 1 2 : f("1","2") 313;f 1 2 : f("1 2") 314 315Remember: TAB completion works in many contexts, not just file names 316or python names. 317 318The following magic functions are currently available: 319 320""" 321 322quick_guide = """\ 323? -> Introduction and overview of IPython's features. 324%quickref -> Quick reference. 325help -> Python's own help system. 326object? -> Details about 'object', use 'object??' for extra details. 327""" 328 329default_banner_parts = [ 330 'Python %s\n' % (sys.version.split('\n')[0],), 331 'Type "copyright", "credits" or "license" for more information.\n\n', 332 'IPython {version} -- An enhanced Interactive Python.\n'.format( 333 version=release.version, 334 ), 335 quick_guide 336] 337 338default_banner = ''.join(default_banner_parts) 339 340# deprecated GUI banner 341 342default_gui_banner = '\n'.join([ 343 'DEPRECATED: IPython.core.usage.default_gui_banner is deprecated and will be removed', 344 default_banner, 345]) 346