diff --git a/IPython/core/usage.py b/IPython/core/usage.py index 420284f..9ccb9df 100644 --- a/IPython/core/usage.py +++ b/IPython/core/usage.py @@ -195,6 +195,11 @@ MAIN FEATURES In [1]: callable_ob arg1, arg2, arg3 and the input will be translated to this: ------> callable_ob(arg1, arg2, arg3) + This feature is off by default (in rare cases it can produce + undesirable side-effects), but you can activate it at the command-line + by starting IPython with `--autocall 1`, set it permanently in your + configuration file, or turn on at runtime with `%autocall 1`. + You can force auto-parentheses by using '/' as the first character of a line. For example: In [1]: /globals # becomes 'globals()' @@ -285,7 +290,7 @@ _oh : Output history Autocall: -f 1,2 : f(1,2) +f 1,2 : f(1,2) # Off by default, enable with %autocall magic. /f 1,2 : f(1,2) (forced autoparen) ,f 1 2 : f("1","2") ;f 1 2 : f("1 2") diff --git a/docs/source/interactive/reference.txt b/docs/source/interactive/reference.txt index 4719370..8fc7660 100644 --- a/docs/source/interactive/reference.txt +++ b/docs/source/interactive/reference.txt @@ -44,289 +44,29 @@ interface, or specify the gui at the commandline:: $ ipython --gui=qt -Regular Options ---------------- +Command-line Options +-------------------- + +To see the options IPython accepts, use ``ipython --help`` (and you probably +should run the output through a pager such as ``ipython --help | less`` for +more convenient reading). This shows all the options that have a single-word +alias to control them, but IPython lets you configure all of its objects from +the command-line by passing the full class name and a corresponding value; type +``ipython --help-all`` to see this full list. For example:: + + ipython --pylab qt + +is equivalent to:: + + ipython --TerminalIPythonApp.pylab='qt' + +Note that in the second form, you *must* use the equal sign, as the expression +is evaluated as an actual Python assignment. While in the above example the +short form is more convenient, only the most common options have a short form, +while any configurable variable in IPython can be set at the command-line by +using the long form. This long form is the same syntax used in the +configuration files, if you want to set these options permanently. -After the above threading options have been given, regular options can -follow in any order. All options can be abbreviated to their shortest -non-ambiguous form and are case-sensitive. - -Most options can also be set from your configuration file. See the provided -example for more details on what the options do. Options given at the command -line override the values set in the configuration file. - -All options with a [no] prepended can be specified in negated form -(--no-option instead of --option) to turn the feature off. - - ``-h, --help`` print a help message and exit. - - ``--pylab, pylab=`` - See :ref:`Matplotlib support ` - for more details. - - ``--autocall=`` - Make IPython automatically call any callable object even if you - didn't type explicit parentheses. For example, 'str 43' becomes - 'str(43)' automatically. The value can be '0' to disable the feature, - '1' for smart autocall, where it is not applied if there are no more - arguments on the line, and '2' for full autocall, where all callable - objects are automatically called (even if no arguments are - present). The default is '1'. - - ``--[no-]autoindent`` - Turn automatic indentation on/off. - - ``--[no-]automagic`` - make magic commands automatic (without needing their first character - to be %). Type %magic at the IPython prompt for more information. - - ``--[no-]autoedit_syntax`` - When a syntax error occurs after editing a file, automatically - open the file to the trouble causing line for convenient - fixing. - - ``--[no-]banner`` - Print the initial information banner (default on). - - ``-c `` - execute the given command string. This is similar to the -c - option in the normal Python interpreter. - - ``--cache-size=`` - size of the output cache (maximum number of entries to hold in - memory). The default is 1000, you can change it permanently in your - config file. Setting it to 0 completely disables the caching system, - and the minimum value accepted is 20 (if you provide a value less than - 20, it is reset to 0 and a warning is issued) This limit is defined - because otherwise you'll spend more time re-flushing a too small cache - than working. - - ``--classic`` - Gives IPython a similar feel to the classic Python - prompt. - - ``--colors=`` - Color scheme for prompts and exception reporting. Currently - implemented: NoColor, Linux and LightBG. - - ``--[no-]color_info`` - IPython can display information about objects via a set of functions, - and optionally can use colors for this, syntax highlighting source - code and various other elements. However, because this information is - passed through a pager (like 'less') and many pagers get confused with - color codes, this option is off by default. You can test it and turn - it on permanently in your configuration file if it works for you. As a - reference, the 'less' pager supplied with Mandrake 8.2 works ok, but - that in RedHat 7.2 doesn't. - - Test it and turn it on permanently if it works with your - system. The magic function %color_info allows you to toggle this - interactively for testing. - - ``--[no-]debug`` - Show information about the loading process. Very useful to pin down - problems with your configuration files or to get details about - session restores. - - ``--[no-]deep_reload`` - IPython can use the deep_reload module which reloads changes in - modules recursively (it replaces the reload() function, so you don't - need to change anything to use it). deep_reload() forces a full - reload of modules whose code may have changed, which the default - reload() function does not. - - When deep_reload is off, IPython will use the normal reload(), - but deep_reload will still be available as dreload(). This - feature is off by default [which means that you have both - normal reload() and dreload()]. - -.. this isn't currently working -.. ``--editor=`` - Which editor to use with the %edit command. By default, - IPython will honor your EDITOR environment variable (if not - set, vi is the Unix default and notepad the Windows one). - Since this editor is invoked on the fly by IPython and is - meant for editing small code snippets, you may want to use a - small, lightweight editor here (in case your default EDITOR is - something like Emacs). - - ``--ipython_dir=`` - name of your IPython configuration directory IPYTHON_DIR. This - can also be specified through the environment variable - IPYTHON_DIR. - - ``--logfile=`` - specify the name of your logfile. - - This implies ``%logstart`` at the beginning of your session - - generate a log file of all input. The file is named - ipython_log.py in your current directory (which prevents logs - from multiple IPython sessions from trampling each other). You - can use this to later restore a session by loading your - logfile with ``ipython -i ipython_log.py`` - - ``--logplay=`` - - NOT AVAILABLE in 0.11 - - you can replay a previous log. For restoring a session as close as - possible to the state you left it in, use this option (don't just run - the logfile). With -logplay, IPython will try to reconstruct the - previous working environment in full, not just execute the commands in - the logfile. - - When a session is restored, logging is automatically turned on - again with the name of the logfile it was invoked with (it is - read from the log header). So once you've turned logging on for - a session, you can quit IPython and reload it as many times as - you want and it will continue to log its history and restore - from the beginning every time. - - Caveats: there are limitations in this option. The history - variables _i*,_* and _dh don't get restored properly. In the - future we will try to implement full session saving by writing - and retrieving a 'snapshot' of the memory state of IPython. But - our first attempts failed because of inherent limitations of - Python's Pickle module, so this may have to wait. - - ``--[no-]messages`` - Print messages which IPython collects about its startup - process (default on). - - ``--[no-]pdb`` - Automatically call the pdb debugger after every uncaught - exception. If you are used to debugging using pdb, this puts - you automatically inside of it after any call (either in - IPython or in code called by it) which triggers an exception - which goes uncaught. - - ``--[no-]pprint`` - ipython can optionally use the pprint (pretty printer) module - for displaying results. pprint tends to give a nicer display - of nested data structures. If you like it, you can turn it on - permanently in your config file (default off). - - ``--profile=`` - - Select the IPython profile by name. - - This is a quick way to keep and load multiple - config files for different tasks, especially if you use the - include option of config files. You can keep a basic - :file:`IPYTHON_DIR/profile_default/ipython_config.py` file - and then have other 'profiles' which - include this one and load extra things for particular - tasks. For example: - - 1. $IPYTHON_DIR/profile_default : load basic things you always want. - 2. $IPYTHON_DIR/profile_math : load (1) and basic math-related modules. - 3. $IPYTHON_DIR/profile_numeric : load (1) and Numeric and plotting modules. - - Since it is possible to create an endless loop by having - circular file inclusions, IPython will stop if it reaches 15 - recursive inclusions. - - ``PromptManager.in_template=`` - - Specify the string used for input prompts. Note that if you are using - numbered prompts, the number is represented with a '\#' in the - string. Don't forget to quote strings with spaces embedded in - them. Default: 'In [\#]:'. The :ref:`prompts section ` - discusses in detail all the available escapes to customize your - prompts. - - ``PromptManager.in2_template=`` - Similar to the previous option, but used for the continuation - prompts. The special sequence '\D' is similar to '\#', but - with all digits replaced dots (so you can have your - continuation prompt aligned with your input prompt). Default: - ' .\D.:' (note three spaces at the start for alignment with - 'In [\#]'). - - ``PromptManager.out_template=`` - String used for output prompts, also uses numbers like - in_template. Default: 'Out[\#]:' - - ``--quick`` - start in bare bones mode (no config file loaded). - - ``config_file=`` - name of your IPython resource configuration file. Normally - IPython loads ipython_config.py (from current directory) or - IPYTHON_DIR/profile_default. - - If the loading of your config file fails, IPython starts with - a bare bones configuration (no modules loaded at all). - - ``--[no-]readline`` - use the readline library, which is needed to support name - completion and command history, among other things. It is - enabled by default, but may cause problems for users of - X/Emacs in Python comint or shell buffers. - - Note that X/Emacs 'eterm' buffers (opened with M-x term) support - IPython's readline and syntax coloring fine, only 'emacs' (M-x - shell and C-c !) buffers do not. - - ``--TerminalInteractiveShell.screen_length=`` - number of lines of your screen. This is used to control - printing of very long strings. Strings longer than this number - of lines will be sent through a pager instead of directly - printed. - - The default value for this is 0, which means IPython will - auto-detect your screen size every time it needs to print certain - potentially long strings (this doesn't change the behavior of the - 'print' keyword, it's only triggered internally). If for some - reason this isn't working well (it needs curses support), specify - it yourself. Otherwise don't change the default. - - ``--TerminalInteractiveShell.separate_in=`` - - separator before input prompts. - Default: '\n' - - ``--TerminalInteractiveShell.separate_out=`` - separator before output prompts. - Default: nothing. - - ``--TerminalInteractiveShell.separate_out2=`` - separator after output prompts. - Default: nothing. - For these three options, use the value 0 to specify no separator. - - ``--nosep`` - shorthand for setting the above separators to empty strings. - - Simply removes all input/output separators. - - ``--init`` - allows you to initialize a profile dir for configuration when you - install a new version of IPython or want to use a new profile. - Since new versions may include new command line options or example - files, this copies updated config files. Note that you should probably - use %upgrade instead,it's a safer alternative. - - ``--version`` print version information and exit. - - ``--xmode=`` - - Mode for exception reporting. - - Valid modes: Plain, Context and Verbose. - - * Plain: similar to python's normal traceback printing. - * Context: prints 5 lines of context source code around each - line in the traceback. - * Verbose: similar to Context, but additionally prints the - variables currently visible where the exception happened - (shortening their strings if too long). This can potentially be - very slow, if you happen to have a huge data structure whose - string representation is complex to compute. Your computer may - appear to freeze for a while with cpu usage at 100%. If this - occurs, you can cancel the traceback with Ctrl-C (maybe hitting it - more than once). Interactive use ===============