Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/IPython/core/usage.py: 100%
9 statements
« prev ^ index » next coverage.py v7.4.4, created at 2024-04-20 06:09 +0000
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#-----------------------------------------------------------------------------
12import sys
13from IPython.core import release
15cl_usage = """\
16=========
17 IPython
18=========
20Tools for Interactive Computing in Python
21=========================================
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.
28Usage
30 ipython [subcommand] [options] [-c cmd | -m mod | file] [--] [arg] ...
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.).
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.
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.
52 To initialize a profile with the default configuration file, do::
54 $> ipython profile create
56 and start editing `IPYTHONDIR/profile_default/ipython_config.py`
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.
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"""
66interactive_usage = """
67IPython -- An enhanced Interactive Python
68=========================================
70IPython offers a fully compatible replacement for the standard Python
71interpreter, with convenient shell features, special commands, command
72history mechanism and output results caching.
74At your system command line, type 'ipython -h' to see the command line
75options available. This document only describes interactive features.
77GETTING HELP
78------------
80Within IPython you have various way to access help:
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.
88If you are in terminal IPython you can quit this screen by pressing `q`.
91MAIN FEATURES
92-------------
94* Access to the standard Python help with object docstrings and the Python
95 manuals. Simply type 'help' (no quotes) to invoke it.
97* Magic commands: type %magic for information on the magic subsystem.
99* System command aliases, via the %alias command or the configuration file(s).
101* Dynamic object information:
103 Typing ?word or word? prints detailed information about an object. Certain
104 long strings (code, etc.) get snipped in the center for brevity.
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.
110 The ?/?? system gives access to the full source code for any object (if
111 available), shows function prototypes and other useful information.
113 If you just want to see an object's docstring, type '%pdoc object' (without
114 quotes, and without % if you have automagic on).
116* Tab completion in the local namespace:
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.
122* Search previous command history in multiple ways:
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.
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.
131 - %hist: search history by index.
133* Persistent command history across sessions.
135* Logging of input with the ability to save and restore a working session.
137* System shell with !. Typing !ls will run 'ls' in the current directory.
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.
142* Verbose and colored exception traceback printouts. See the magic xmode and
143 xcolor functions for details (just type %magic).
145* Input caching system:
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).
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.
157 Additionally, global variables named _i<n> are dynamically created (<n>
158 being the prompt counter), such that _i<n> == _ih[<n>]
160 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
162 You can create macros which contain multiple input lines from this history,
163 for later re-execution, with the %macro function.
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.
170* Output caching system:
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.
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.
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>.
186 Finally, a global dictionary named _oh exists with entries for all lines
187 which generated output.
189* Directory history:
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.
194* Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
196 1. Auto-parentheses
198 Callable objects (i.e. functions, methods, etc) can be invoked like
199 this (notice the commas between the arguments)::
201 In [1]: callable_ob arg1, arg2, arg3
203 and the input will be translated to this::
205 callable_ob(arg1, arg2, arg3)
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`.
212 You can force auto-parentheses by using '/' as the first character
213 of a line. For example::
215 In [1]: /globals # becomes 'globals()'
217 Note that the '/' MUST be the first character on the line! This
218 won't work::
220 In [2]: print /globals # syntax error
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)::
227 In [1]: zip (1,2,3),(4,5,6) # won't work
229 but this will work::
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)]
235 IPython tells you that it has altered your command line by
236 displaying the new command line preceded by -->. e.g.::
238 In [18]: callable list
239 -------> callable (list)
241 2. Auto-Quoting
243 You can force auto-quoting of a function's arguments by using ',' as
244 the first character of a line. For example::
246 In [1]: ,my_function /home/me # becomes my_function("/home/me")
248 If you use ';' instead, the whole argument is quoted as a single
249 string (while ',' splits on whitespace)::
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")
254 Note that the ',' MUST be the first character on the line! This
255 won't work::
257 In [4]: x = ,my_function /home/me # syntax error
258"""
260interactive_usage_min = """\
261An enhanced console for Python.
262Some 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"""
271quick_reference = r"""
272IPython -- An enhanced Interactive Python - Quick Reference Card
273================================================================
275obj?, 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.
280Magic functions are prefixed by % or %%, and typically take their arguments
281without parentheses, quotes or even commas for convenience. Line magics take a
282single % and cell magics are prefixed with two %%.
284Example magic function calls:
286%alias d ls -F : 'd' is now an alias for 'ls -F'
287alias d ls -F : Works if 'alias' not a python name
288alist = %alias : Get list of aliases to 'alist'
289cd /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
293x**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.
296System commands:
298!cp a.txt b/ : System command escape, calls os.system()
299cp a.txt b/ : after %rehashx, most system commands work without !
300cp ${f}.txt $bar : Variable expansion in magics and system commands
301files = !ls /usr : Capture system command output
302files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
304History:
306_i, _ii, _iii : Previous, next previous, next next previous input
307_i4, _ih[2:5] : Input history line 4, lines 2-4
308exec(_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.
322Autocall:
324f 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")
329Remember: TAB completion works in many contexts, not just file names
330or python names.
332The following magic functions are currently available:
334"""
336default_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]
341default_banner = ''.join(default_banner_parts)