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