Skip to content


Subversion checkout URL

You can clone with
Download ZIP


Command line args in docs #564

merged 4 commits into from

2 participants


@minrk: A quick pull request so you can check I've not changed anything which obviously shouldn't have been changed.

Should fix #562.


I believe all your changes are correct. Thanks for taking this one.

@takluyver takluyver merged commit 2952bd3 into ipython:master

No worries. Merged.

@ellisonbg ellisonbg referenced this pull request from a commit
Commit has since been removed from the repository and is no longer available.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
2  docs/source/config/extensions.txt
@@ -50,7 +50,7 @@ to your configuration file::
-To load that same extension at runtime, use the ``%load_ext`` magic::
+To load that same extension at runtime, use the ``%load_ext`` magic:
.. sourcecode:: ipython
18 docs/source/config/overview.txt
@@ -336,7 +336,7 @@ Let's start by showing how a profile is used:
.. code-block:: bash
- $ ipython profile=sympy
+ $ ipython --profile=sympy
This tells the :command:`ipython` command line program to get its configuration
from the "sympy" profile. The file names for various profiles do not change. The
@@ -350,7 +350,7 @@ The general pattern is this: simply create a new profile with:
ipython profile create <name>
which adds a directory called ``profile_<name>`` to your IPython directory. Then
-you can load this profile by adding ``profile=<name>`` to your command line
+you can load this profile by adding ``--profile=<name>`` to your command line
options. Profiles are supported by all IPython applications.
IPython ships with some sample profiles in :file:`IPython/config/profile`. If
@@ -374,7 +374,7 @@ object. Values are assigned in much the same way as in a config file:
.. code-block:: bash
- $> ipython InteractiveShell.use_readline=False BaseIPythonApplication.profile='myprofile'
+ $> ipython --InteractiveShell.use_readline=False --BaseIPythonApplication.profile='myprofile'
Is the same as adding:
@@ -394,9 +394,9 @@ used traits, so you don't have to specify the whole class name. For these **alia
.. code-block:: bash
- $> ipython profile='myprofile'
+ $> ipython --profile='myprofile'
# is equivalent to
- $> ipython BaseIPythonApplication.profile='myprofile'
+ $> ipython --BaseIPythonApplication.profile='myprofile'
@@ -411,11 +411,11 @@ For instance:
$> ipcontroller --debug
# is equivalent to
- $> ipcontroller Application.log_level=DEBUG
+ $> ipcontroller --Application.log_level=DEBUG
# and
$> ipython --pylab
# is equivalent to
- $> ipython pylab=auto
+ $> ipython --pylab=auto
@@ -427,14 +427,14 @@ Some IPython applications have **subcommands**. Subcommands are modeled after
.. code-block:: bash
- $> ipython qtconsole profile=myprofile
+ $> ipython qtconsole --profile=myprofile
and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
stop, engines).
.. code-block:: bash
- $> ipcluster start profile=myprofile n=4
+ $> ipcluster start --profile=myprofile --n=4
To see a list of the available aliases, flags, and subcommands for an IPython application, simply pass ``-h`` or ``--help``. And to see the full list of configurable options (*very* long), pass ``--help-all``.
4 docs/source/development/testing.txt
@@ -349,7 +349,8 @@ We basically need to be able to test the following types of code:
Nose will pick them up as long as they conform to the (flexible) conventions
used by nose to recognize tests.
-2. Python files containing doctests. Here, we have two possibilities:
+2. Python files containing doctests. Here, we have two possibilities:
- The prompts are the usual ``>>>`` and the input is pure Python.
- The prompts are of the form ``In [1]:`` and the input can contain extended
IPython expressions.
@@ -361,6 +362,7 @@ We basically need to be able to test the following types of code:
3. ReStructuredText files that contain code blocks. For this type of file, we
have three distinct possibilities for the code blocks:
- They use ``>>>`` prompts.
- They use ``In [1]:`` prompts.
- They are standalone blocks of pure Python code without any prompts.
20 docs/source/interactive/qtconsole.txt
@@ -20,7 +20,7 @@ configurable.
-The ``%loadpy`` magic has been added, just for the GUI frontend. It takes any python
+The new ``%loadpy`` magic takes any python
script (must end in '.py'), and pastes its contents as your next input, so you can edit it
before executing. The script may be on your machine, but you can also specify a url, and
it will download the script from the web. This is particularly useful for playing with
@@ -28,8 +28,7 @@ examples from documentation, such as matplotlib.
.. sourcecode:: ipython
- In [6]: %loadpy
+ In [6]: %loadpy
In [7]: from mpl_toolkits.mplot3d import axes3d
...: import matplotlib.pyplot as plt
@@ -64,12 +63,13 @@ them in your document. This is especially useful for saving_ your work.
.. _inline:
If you want to have all of your figures embedded in your session, instead of calling
-:func:`pastefig`, you can specify ``pylab=inline``, and each time you make a plot, it
-will show up in your document, as if you had called :func:`pastefig`.
+:func:`pastefig`, you can specify ``--pylab=inline`` when you start the console,
+and each time you make a plot, it will show up in your document, as if you had
+called :func:`pastefig`.
.. _saving:
@@ -116,7 +116,7 @@ if unspecified, will be guessed based on the chosen style. Similarly, there are
styles associated with each ``colors`` option.
-Screenshot of ``ipython qtconsole colors=linux``, which uses the 'monokai' theme by
+Screenshot of ``ipython qtconsole --colors=linux``, which uses the 'monokai' theme by
.. image:: figs/colors_dark.png
@@ -147,7 +147,7 @@ Fonts
The QtConsole has configurable via the ConsoleWidget. To change these, set the ``font_family``
or ``font_size`` traits of the ConsoleWidget. For instance, to use 9pt Anonymous Pro::
- $> ipython qtconsole ConsoleWidget.font_family="Anonymous Pro" ConsoleWidget.font_size=9
+ $> ipython qtconsole --ConsoleWidget.font_family="Anonymous Pro" --ConsoleWidget.font_size=9
Process Management
@@ -167,7 +167,7 @@ do not have to all be qt frontends - any IPython frontend can connect and run co
When you start ipython qtconsole, there will be an output line, like::
To connect another client to this kernel, use:
- --external shell=62109 iopub=62110 stdin=62111 hb=62112
+ --external --shell=62109 --iopub=62110 --stdin=62111 --hb=62112
Other frontends can connect to your kernel, and share in the execution. This is great for
collaboration. The `-e` flag is for 'external'. Starting other consoles with that flag
@@ -178,7 +178,7 @@ By default (for security reasons), the kernel only listens on localhost, so you
connect multiple frontends to the kernel from your local machine. You can specify to
listen on an external interface by specifying the ``ip`` argument::
- $> ipython qtconsole ip=
+ $> ipython qtconsole --ip=
If you specify the ip as, that refers to all interfaces, so any computer that can
see yours can connect to the kernel.
30 docs/source/interactive/reference.txt
@@ -35,7 +35,7 @@ version 0.11, these have been removed. Please see the new ``%gui``
magic command or :ref:`this section <gui_support>` for details on the new
interface, or specify the gui at the commandline::
- $ ipython gui=qt
+ $ ipython --gui=qt
Regular Options
@@ -59,7 +59,7 @@ All options with a [no] prepended can be specified in negated form
See :ref:`Matplotlib support <matplotlib_support>`
for more details.
- ``autocall=<val>``
+ ``--autocall=<val>``
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,
@@ -83,11 +83,11 @@ All options with a [no] prepended can be specified in negated form
Print the initial information banner (default on).
- ``c=<command>``
+ ``--c=<command>``
execute the given command string. This is similar to the -c
option in the normal Python interpreter.
- ``cache_size=<n>``
+ ``--cache_size=<n>``
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,
@@ -100,7 +100,7 @@ All options with a [no] prepended can be specified in negated form
Gives IPython a similar feel to the classic Python
- ``colors=<scheme>``
+ ``--colors=<scheme>``
Color scheme for prompts and exception reporting. Currently
implemented: NoColor, Linux and LightBG.
@@ -135,7 +135,7 @@ All options with a [no] prepended can be specified in negated form
feature is off by default [which means that you have both
normal reload() and dreload()].
- ``editor=<name>``
+ ``--editor=<name>``
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).
@@ -144,12 +144,12 @@ All options with a [no] prepended can be specified in negated form
small, lightweight editor here (in case your default EDITOR is
something like Emacs).
- ``ipython_dir=<name>``
+ ``--ipython_dir=<name>``
name of your IPython configuration directory IPYTHON_DIR. This
can also be specified through the environment variable
- ``logfile=<name>``
+ ``--logfile=<name>``
specify the name of your logfile.
This implies ``%logstart`` at the beginning of your session
@@ -160,7 +160,7 @@ All options with a [no] prepended can be specified in negated form
can use this to later restore a session by loading your
logfile with ``ipython --i``
- ``logplay=<name>``
+ ``--logplay=<name>``
@@ -201,7 +201,7 @@ All options with a [no] prepended can be specified in negated form
of nested data structures. If you like it, you can turn it on
permanently in your config file (default off).
- ``profile=<name>``
+ ``--profile=<name>``
Select the IPython profile by name.
@@ -263,7 +263,7 @@ All options with a [no] prepended can be specified in negated form
IPython's readline and syntax coloring fine, only 'emacs' (M-x
shell and C-c !) buffers do not.
- ``TerminalInteractiveShell.screen_length=<n>``
+ ``--TerminalInteractiveShell.screen_length=<n>``
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
@@ -276,16 +276,16 @@ All options with a [no] prepended can be specified in negated form
reason this isn't working well (it needs curses support), specify
it yourself. Otherwise don't change the default.
- ``TerminalInteractiveShell.separate_in=<string>``
+ ``--TerminalInteractiveShell.separate_in=<string>``
separator before input prompts.
Default: '\n'
- ``TerminalInteractiveShell.separate_out=<string>``
+ ``--TerminalInteractiveShell.separate_out=<string>``
separator before output prompts.
Default: nothing.
- ``TerminalInteractiveShell.separate_out2=<string>``
+ ``--TerminalInteractiveShell.separate_out2=<string>``
separator after output prompts.
Default: nothing.
For these three options, use the value 0 to specify no separator.
@@ -304,7 +304,7 @@ All options with a [no] prepended can be specified in negated form
``--version`` print version information and exit.
- ``xmode=<modename>``
+ ``--xmode=<modename>``
Mode for exception reporting.
2  docs/source/parallel/parallel_demos.txt
@@ -103,7 +103,7 @@ calculation, we will need two top-level functions from :file:``:
.. literalinclude:: ../../examples/newparallel/
:language: python
- :lines: 41-56
+ :lines: 47-62
We will also use the :func:`plot_two_digit_freqs` function to plot the
results. The code to run this calculation in parallel is contained in
2  docs/source/parallel/parallel_intro.txt
@@ -195,7 +195,7 @@ simply start a controller and engines on a single host using the
:command:`ipcluster` command. To start a controller and 4 engines on your
localhost, just do::
- $ ipcluster start n=4
+ $ ipcluster start --n=4
More details about starting the IPython controller and engines can be found
:ref:`here <parallel_process>`
13 docs/source/parallel/parallel_mpi.txt
@@ -4,11 +4,6 @@
Using MPI with IPython
-.. note::
- Not adapted to zmq yet
- This is out of date wrt ipcluster in general as well
Often, a parallel algorithm will require moving data between the engines. One
way of accomplishing this is by doing a pull and then a push using the
multiengine client. However, this will be slow as all the data has to go
@@ -57,7 +52,7 @@ The easiest approach is to use the `MPIExec` Launchers in :command:`ipcluster`,
which will first start a controller and then a set of engines using
- $ ipcluster start n=4 elauncher=MPIExecEngineSetLauncher
+ $ ipcluster start --n=4 --elauncher=MPIExecEngineSetLauncher
This approach is best as interrupting :command:`ipcluster` will automatically
stop and clean up the controller and engines.
@@ -68,14 +63,14 @@ Manual starting using :command:`mpiexec`
If you want to start the IPython engines using the :command:`mpiexec`, just
- $ mpiexec n=4 ipengine mpi=mpi4py
+ $ mpiexec n=4 ipengine --mpi=mpi4py
This requires that you already have a controller running and that the FURL
files for the engines are in place. We also have built in support for
PyTrilinos [PyTrilinos]_, which can be used (assuming is installed) by
starting the engines with::
- $ mpiexec n=4 ipengine mpi=pytrilinos
+ $ mpiexec n=4 ipengine --mpi=pytrilinos
Automatic starting using PBS and :command:`ipcluster`
@@ -110,7 +105,7 @@ distributed array. Save the following text in a file called :file:``:
Now, start an IPython cluster::
- $ ipcluster start profile=mpi n=4
+ $ ipcluster start --profile=mpi --n=4
.. note::
2  docs/source/parallel/parallel_multiengine.txt
@@ -19,7 +19,7 @@ To follow along with this tutorial, you will need to start the IPython
controller and four IPython engines. The simplest way of doing this is to use
the :command:`ipcluster` command::
- $ ipcluster start n=4
+ $ ipcluster start --n=4
For more detailed information about starting the controller and engines, see
our :ref:`introduction <ip1par>` to using IPython for parallel computing.
30 docs/source/parallel/parallel_process.txt
@@ -35,7 +35,7 @@ the ``ip`` argument on the command-line, or the ``HubFactory.ip`` configurable i
If your machines are on a trusted network, you can safely instruct the controller to listen
on all public interfaces with::
- $> ipcontroller ip=*
+ $> ipcontroller --ip=*
Or you can set the same behavior as the default by adding the following line to your :file:``:
@@ -109,7 +109,7 @@ The simplest way to use ipcluster requires no configuration, and will
launch a controller and a number of engines on the local machine. For instance,
to start one controller and 4 engines on localhost, just do::
- $ ipcluster start n=4
+ $ ipcluster start --n=4
To see other command line options, do::
@@ -121,7 +121,7 @@ Configuring an IPython cluster
Cluster configurations are stored as `profiles`. You can create a new profile with::
- $ ipython profile create --parallel profile=myprofile
+ $ ipython profile create --parallel --profile=myprofile
This will create the directory :file:`IPYTHONDIR/profile_myprofile`, and populate it
with the default configuration files for the three IPython cluster commands. Once
@@ -162,7 +162,7 @@ The mpiexec/mpirun mode is useful if you:
If these are satisfied, you can create a new profile::
- $ ipython profile create --parallel profile=mpi
+ $ ipython profile create --parallel --profile=mpi
and edit the file :file:`IPYTHONDIR/profile_mpi/`.
@@ -174,7 +174,7 @@ There, instruct ipcluster to use the MPIExec launchers by adding the lines:
If the default MPI configuration is correct, then you can now start your cluster, with::
- $ ipcluster start n=4 profile=mpi
+ $ ipcluster start --n=4 --profile=mpi
This does the following:
@@ -219,7 +219,7 @@ The PBS mode uses the Portable Batch System (PBS) to start the engines.
As usual, we will start by creating a fresh profile::
- $ ipython profile create --parallel profile=pbs
+ $ ipython profile create --parallel --profile=pbs
And in :file:``, we will select the PBS launchers for the controller
and engines:
@@ -253,7 +253,7 @@ to specify your own. Here is a sample PBS script template:
export PATH=$HOME/usr/local/bin
export PYTHONPATH=$HOME/usr/local/lib/python2.7/site-packages
- /usr/local/bin/mpiexec -n {n} ipengine profile_dir={profile_dir}
+ /usr/local/bin/mpiexec -n {n} ipengine --profile_dir={profile_dir}
There are a few important points about this template:
@@ -288,7 +288,7 @@ The controller template should be similar, but simpler:
export PATH=$HOME/usr/local/bin
export PYTHONPATH=$HOME/usr/local/lib/python2.7/site-packages
- ipcontroller profile_dir={profile_dir}
+ ipcontroller --profile_dir={profile_dir}
Once you have created these scripts, save them with names like
@@ -324,7 +324,7 @@ connections on all its interfaces, by adding in :file:`ipcontroller_config`:
You can now run the cluster with::
- $ ipcluster start profile=pbs n=128
+ $ ipcluster start --profile=pbs --n=128
Additional configuration options can be found in the PBS section of :file:`ipcluster_config`.
@@ -349,7 +349,7 @@ nodes and :command:`ipcontroller` can be run remotely as well, or on localhost.
As usual, we start by creating a clean profile::
- $ ipython profile create --parallel profile=ssh
+ $ ipython profile create --parallel --profile=ssh
To use this mode, select the SSH launchers in :file:``:
@@ -374,7 +374,7 @@ The controller's remote location and configuration can be specified:
# note that remotely launched ipcontroller will not get the contents of
# the local unless it resides on the *remote host*
# in the location specified by the `profile_dir` argument.
- # c.SSHControllerLauncher.program_args = ['--reuse', 'ip=*', 'profile_dir=/path/to/cd']
+ # c.SSHControllerLauncher.program_args = ['--reuse', '--ip=*', '--profile_dir=/path/to/cd']
.. note::
@@ -390,7 +390,7 @@ on that host.
c.SSHEngineSetLauncher.engines = { '' : 2,
'' : 5,
- '' : (1, ['profile_dir=/home/different/location']),
+ '' : (1, ['--profile_dir=/home/different/location']),
'' : 8 }
* The `engines` dict, where the keys are the host we want to run engines on and
@@ -403,7 +403,7 @@ a single location:
.. sourcecode:: python
- c.SSHEngineSetLauncher.engine_args = ['profile_dir=/path/to/profile_ssh']
+ c.SSHEngineSetLauncher.engine_args = ['--profile_dir=/path/to/profile_ssh']
Current limitations of the SSH mode of :command:`ipcluster` are:
@@ -471,12 +471,12 @@ can do this:
* Put :file:`ipcontroller-engine.json` in the :file:`~/.ipython/profile_<name>/security`
directory on the engine's host, where it will be found automatically.
-* Call :command:`ipengine` with the ``file=full_path_to_the_file``
+* Call :command:`ipengine` with the ``--file=full_path_to_the_file``
The ``file`` flag works like this::
- $ ipengine file=/path/to/my/ipcontroller-engine.json
+ $ ipengine --file=/path/to/my/ipcontroller-engine.json
.. note::
69 docs/source/parallel/parallel_security.txt
@@ -248,75 +248,6 @@ capabilities based authentication model, in conjunction with SSH tunneled
TCP/IP channels, address the core potential vulnerabilities in the system,
while still enabling user's to use the system in open networks.
-Other questions
-.. note::
- this does not apply to ZMQ, but I am sure there will be questions.
-About keys
-Can you clarify the roles of the certificate and its keys versus the FURL,
-which is also called a key?
-The certificate created by IPython processes is a standard public key x509
-certificate, that is used by the SSL handshake protocol to setup encrypted
-channel between the controller and the IPython engine or client. This public
-and private key associated with this certificate are used only by the SSL
-handshake protocol in setting up this encrypted channel.
-The FURL serves a completely different and independent purpose from the
-key pair associated with the certificate. When we refer to a FURL as a
-key, we are using the word "key" in the capabilities based security model
-sense. This has nothing to do with "key" in the public/private key sense used
-in the SSL protocol.
-With that said the FURL is used as an cryptographic key, to grant
-IPython engines and clients access to particular capabilities that the
-controller offers.
-Self signed certificates
-Is the controller creating a self-signed certificate? Is this created for per
-instance/session, one-time-setup or each-time the controller is started?
-The Foolscap network protocol, which handles the SSL protocol details, creates
-a self-signed x509 certificate using OpenSSL for each IPython process. The
-lifetime of the certificate is handled differently for the IPython controller
-and the engines/client.
-For the IPython engines and client, the certificate is only held in memory for
-the lifetime of its process. It is never written to disk.
-For the controller, the certificate can be created anew each time the
-controller starts or it can be created once and reused each time the
-controller starts. If at any point, the certificate is deleted, a new one is
-created the next time the controller starts.
-SSL private key
-How the private key (associated with the certificate) is distributed?
-In the usual implementation of the SSL protocol, the private key is never
-distributed. We follow this standard always.
-SSL versus Foolscap authentication
-Many SSL connections only perform one sided authentication (the server to the
-client). How is the client authentication in IPython's system related to SSL
-We perform a two way SSL handshake in which both parties request and verify
-the certificate of their peer. This mutual authentication is handled by the
-SSL handshake and is separate and independent from the additional
-authentication steps that the CLIENT and SERVER perform after an encrypted
-channel is established.
.. [RFC5246] <>
.. [OpenSSH] <>
6 docs/source/parallel/parallel_task.txt
@@ -24,7 +24,7 @@ To follow along with this tutorial, you will need to start the IPython
controller and four IPython engines. The simplest way of doing this is to use
the :command:`ipcluster` command::
- $ ipcluster start n=4
+ $ ipcluster start --n=4
For more detailed information about starting the controller and engines, see
our :ref:`introduction <ip1par>` to using IPython for parallel computing.
@@ -350,9 +350,9 @@ The built-in routing schemes:
To select one of these schemes, simply do::
- $ ipcontroller scheme=<schemename>
+ $ ipcontroller --scheme=<schemename>
for instance:
- $ ipcontroller scheme=lru
+ $ ipcontroller --scheme=lru
lru: Least Recently Used
4 docs/source/parallel/parallel_winhpc.txt
@@ -204,7 +204,7 @@ security keys. The naming convention for cluster directories is:
To create a new cluster profile (named "mycluster") and the associated cluster
directory, type the following command at the Windows Command Prompt::
- ipython profile create --parallel profile=mycluster
+ ipython profile create --parallel --profile=mycluster
The output of this command is shown in the screenshot below. Notice how
:command:`ipcluster` prints out the location of the newly created cluster
@@ -257,7 +257,7 @@ Starting the cluster profile
Once a cluster profile has been configured, starting an IPython cluster using
the profile is simple::
- ipcluster start profile=mycluster n=32
+ ipcluster start --profile=mycluster --n=32
The ``-n`` option tells :command:`ipcluster` how many engines to start (in
this case 32). Stopping the cluster is as simple as typing Control-C.
2  docs/source/whatsnew/version0.11.txt
@@ -300,7 +300,7 @@ Backwards incompatible changes
from the command-line with the same syntax as in a configuration file.
* The command line options ``-wthread``, ``-qthread`` and
- ``-gthread`` have been removed. Use ``gui=wx``, ``gui=qt``, ``gui=gtk``
+ ``-gthread`` have been removed. Use ``--gui=wx``, ``--gui=qt``, ``--gui=gtk``
* The extension loading functions have been renamed to
Something went wrong with that request. Please try again.