intro.rst
232 lines
| 7.0 KiB
| text/x-rst
|
RstLexer
Thomas Kluyver
|
r13492 | ===================================== | |
Introduction to IPython configuration | |||
===================================== | |||
Thomas Kluyver
|
r13503 | .. _setting_config: | |
Thomas Kluyver
|
r13492 | ||
Setting configurable options | |||
============================ | |||
Thomas Kluyver
|
r13499 | Many of IPython's classes have configurable attributes (see | |
:doc:`options/index` for the list). These can be | |||
Thomas Kluyver
|
r13492 | configured in several ways. | |
Python config files | |||
------------------- | |||
To create the blank config files, run:: | |||
ipython profile create [profilename] | |||
If you leave out the profile name, the files will be created for the | |||
Matthias Bussonnier
|
r25743 | ``default`` profile (see :ref:`profiles`). These will typically be located in | |
:file:`~/.ipython/profile_default/`, and will be named | |||
:file:`ipython_config.py`, for hitorical reasons you may also find fiels | |||
named with IPytho nprefix instead of Jupyter: | |||
:file:`ipython_notebook_config.py`, etc. The settings in | |||
:file:`ipython_config.py` apply to all IPython commands. | |||
Thomas Kluyver
|
r13492 | ||
Matthias Bussonnier
|
r25743 | by default, configuration files are fully featured Python scripts that can | |
execute arbitrary code, the main usage is to set value on the config object | |||
``c`` which exist in your configuration file. | |||
Thomas Kluyver
|
r13492 | ||
You can then configure class attributes like this:: | |||
c.InteractiveShell.automagic = False | |||
Be careful with spelling--incorrect names will simply be ignored, with | |||
Matthias Bussonnier
|
r25743 | no error. | |
Thomas Kluyver
|
r13492 | ||
Matthias Bussonnier
|
r25743 | To add to a collection which may have already been defined elsewhere or have | |
default values, you can use methods like those found on lists, dicts and | |||
sets: append, extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like | |||
extend, but at the front), add and update (which works both for dicts and | |||
sets):: | |||
Thomas Kluyver
|
r13492 | ||
Matthias Bussonnier
|
r17915 | c.InteractiveShellApp.extensions.append('Cython') | |
Thomas Kluyver
|
r13492 | ||
.. versionadded:: 2.0 | |||
list, dict and set methods for config values | |||
Thomas Kluyver
|
r13493 | Example config file | |
``````````````````` | |||
:: | |||
# sample ipython_config.py | |||
c.TerminalIPythonApp.display_banner = True | |||
c.InteractiveShellApp.log_level = 20 | |||
c.InteractiveShellApp.extensions = [ | |||
'myextension' | |||
] | |||
c.InteractiveShellApp.exec_lines = [ | |||
'import numpy', | |||
'import scipy' | |||
] | |||
c.InteractiveShellApp.exec_files = [ | |||
'mycode.py', | |||
'fancy.ipy' | |||
] | |||
c.InteractiveShell.colors = 'LightBG' | |||
c.InteractiveShell.confirm_exit = False | |||
c.InteractiveShell.editor = 'nano' | |||
c.InteractiveShell.xmode = 'Context' | |||
c.PrefilterManager.multi_line_specials = True | |||
c.AliasManager.user_aliases = [ | |||
('la', 'ls -al') | |||
] | |||
Matthias Bussonnier
|
r25743 | Json Configuration files | |
------------------------ | |||
in case where executability of configuration can be problematic, or | |||
configurations need to be modified programatically, IPython also support a | |||
limited set of functionalities via ``.json`` config files. | |||
You can defined most of the configuration options via a json object which | |||
hierarchy represent the value you woudl normally set on the ``c`` object of | |||
``.py`` configuration files. The following ``ipython_config.json`` file:: | |||
{ | |||
"InteractiveShell": { | |||
"colors": "LightBG", | |||
"editor": "nano" | |||
}, | |||
"InteractiveShellApp": { | |||
"extensions": [ | |||
"myextension" | |||
] | |||
} | |||
} | |||
Is equivalent to the following ``ipython_config.py``:: | |||
c.InteractiveShellApp.extensions = [ | |||
'myextension' | |||
] | |||
c.InteractiveShell.colors = 'LightBG' | |||
c.InteractiveShell.editor = 'nano' | |||
Thomas Kluyver
|
r13493 | ||
Thomas Kluyver
|
r13492 | Command line arguments | |
---------------------- | |||
Every configurable value can be set from the command line, using this | |||
syntax:: | |||
ipython --ClassName.attribute=value | |||
Many frequently used options have short aliases and flags, such as | |||
``--matplotlib`` (to integrate with a matplotlib GUI event loop) or | |||
``--pdb`` (automatic post-mortem debugging of exceptions). | |||
To see all of these abbreviated options, run:: | |||
ipython --help | |||
Matthias Bussonnier
|
r25743 | jupyter notebook --help | |
Thomas Kluyver
|
r13492 | # etc. | |
Thomas Kluyver
|
r13506 | Options specified at the command line, in either format, override | |
options set in a configuration file. | |||
Thomas Kluyver
|
r13492 | The config magic | |
---------------- | |||
You can also modify config from inside IPython, using a magic command:: | |||
%config IPCompleter.greedy = True | |||
At present, this only affects the current session - changes you make to | |||
Thomas Kluyver
|
r13507 | config are not saved anywhere. Also, some options are only read when | |
IPython starts, so they can't be changed like this. | |||
Thomas Kluyver
|
r13492 | ||
Erich Spaker
|
r23829 | .. _configure_start_ipython: | |
Erich Spaker
|
r23828 | ||
Erich Spaker
|
r23829 | Running IPython from Python | |
Erich Spaker
|
r23828 | ---------------------------- | |
Erich Spaker
|
r23829 | If you are using :ref:`embedding` to start IPython from a normal | |
python file, you can set configuration options the same way as in a | |||
config file by creating a traitlets config object and passing it to | |||
start_ipython like in the example below. | |||
Erich Spaker
|
r23828 | ||
Erich Spaker
|
r23829 | .. literalinclude:: ../../../examples/Embedding/start_ipython_config.py | |
Erich Spaker
|
r23828 | :language: python | |
Thomas Kluyver
|
r13492 | .. _profiles: | |
Profiles | |||
======== | |||
IPython can use multiple profiles, with separate configuration and | |||
history. By default, if you don't specify a profile, IPython always runs | |||
in the ``default`` profile. To use a new profile:: | |||
ipython profile create foo # create the profile foo | |||
ipython --profile=foo # start IPython using the new profile | |||
Profiles are typically stored in :ref:`ipythondir`, but you can also keep | |||
a profile in the current working directory, for example to distribute it | |||
with a project. To find a profile directory on the filesystem:: | |||
ipython locate profile foo | |||
.. _ipythondir: | |||
The IPython directory | |||
===================== | |||
IPython stores its files---config, command history and extensions---in | |||
the directory :file:`~/.ipython/` by default. | |||
.. envvar:: IPYTHONDIR | |||
If set, this environment variable should be the path to a directory, | |||
which IPython will use for user data. IPython will create it if it | |||
does not exist. | |||
.. option:: --ipython-dir=<path> | |||
This command line option can also be used to override the default | |||
IPython directory. | |||
Thomas Kluyver
|
r21388 | ||
To see where IPython is looking for the IPython directory, use the command | |||
``ipython locate``, or the Python function :func:`IPython.paths.get_ipython_dir`. | |||
Matthias Bussonnier
|
r25743 | ||
Systemwide configuration | |||
======================== | |||
It can be usefull to deploy systemwide ipython or ipykernel configuration | |||
when managing environment for many users. At startup time IPython and | |||
IPykernel will search for configuration file in multiple systemwide | |||
locations, mainly: | |||
- ``/etc/ipython/`` | |||
- ``/usr/local/etc/ipython/`` | |||
When the global install is a standalone python distribution it may also | |||
search in distribution specific location, for example: | |||
- ``$ANACONDA_LOCATION/etc/ipython/`` | |||
In those locations, Terminal IPython will look for a file called | |||
``ipython_config.py`` and ``ipython_config.json``, ipykernel will look for | |||
``ipython_kernel_config.py`` and ``ipython_kernel.json``. | |||
Configuration files are loaded in order and merged with configuration on | |||
later locatoin taking precedence on earlier locations (that is to say a user | |||
can overwrite a systemwide configuration option). | |||
You can see all locations in which IPython is looking for configuration files | |||
by starting ipython in debug mode:: | |||
$ ipython --debug -c 'exit()' | |||
Identically with ipykernel though the command is currently blocking until | |||
this process is killed with ``Ctrl-\``:: | |||
$ python -m ipykernel --debug |