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