The traitlets package (https://traitlets.readthedocs.io/en/stable/), originated from IPython, implements a powerful configuration system. This system is used throughout the project, but it can also be used by IPython extensions. It could even be used in entirely new applications.
In this recipe, we show how to use this system to write a configurable IPython extension. We will create a simple magic command that displays random numbers. This magic command comes with configurable parameters that can be set by the user in their IPython configuration file.
We create an IPython extension in a
random_magics.pyfile. Let's start by importing a few objects:>>> %%writefile random_magics.py from traitlets import Int, Float, Unicode, Bool from IPython.core.magic import (Magics, magics_class, line_magic) import numpy as np Writing random_magics.pyWe create a
RandomMagicsclass deriving fromMagics. This class contains a few configurable parameters:>>> %%writefile random_magics.py -a @magics_class class RandomMagics(Magics): text = Unicode(u'{n}', config=True) max = Int(1000, config=True) seed = Int(0, config=True) Appending to random_magics.pyWe need to call the parent's constructor. Then, we initialize a random number generator with a seed:
>>> %%writefile random_magics.py -a def __init__(self, shell): super(RandomMagics, self).__init__(shell) self._rng = np.random.RandomState( self.seed or None) Appending to random_magics.pyWe create a
%randomline magic that displays a random number:>>> %%writefile random_magics.py -a @line_magic def random(self, line): return self.text.format( n=self._rng.randint(self.max)) Appending to random_magics.pyFinally, we register that magic when the extension is loaded:
>>> %%writefile random_magics.py -a def load_ipython_extension(ipython): ipython.register_magics(RandomMagics) Appending to random_magics.pyLet's test our extension in the Notebook:
>>> %load_ext random_magics >>> %random '430' >>> %random '305'
Our magic command has a few configurable parameters. These variables are meant to be configured by the user in the IPython configuration file or in the console when starting IPython. To configure these variables in the Terminal, we can type the following command in a system shell:
ipython --RandomMagics.text='Your number is {n}.' \ --RandomMagics.max=10 \ --RandomMagics.seed=1In that session,
%randomdisplays a string like'Your number is 5.'.To configure the variables in the IPython configuration file, we open the
~/.ipython/profile_default/ipython_config.pyfile and add the following line:c.RandomMagics.text = 'random {n}'After launching IPython,
%randomprints a string like random652.
IPython's configuration system defines several concepts:
An user profile is a set of parameters, logs, and command history, which are specific to a user. A user can have different profiles when working on different projects. An
xxxprofile is stored in~/.ipython/profile_xxx, where~is the user's home directory.On Linux, the path should be
/home/yourname/.ipython/profile_xxxOn macOS, the path should be
/Users/yourname/.ipython/profile_xxxOn Windows, the path should be
C:\Users\YourName\.ipython\profile_xxx
A configuration object, or
Config, is a special Python dictionary that contains key-value pairs. TheConfigclass derives from Python's dict.The
HasTraitsclass is a class that can have special trait attributes. Traits are sophisticated Python attributes that have a specific type and a default value. Additionally, when a trait's value changes, a callback function is automatically and transparently called. This mechanism allows a class to be notified whenever a trait attribute is changed.A
Configurableclass is the base class of all classes that want to benefit from the configuration system. AConfigurableclass can have configurable attributes. These attributes have default values specified directly in the class definition. The main feature ofConfigurableclasses is that the default values of the traits can be overridden by configuration files on a class-by-class basis. Then, instances of theConfigurableclasses can change these values at leisure.A configuration file is a Python or JSON file that contains the parameters of the
Configurableclasses.
The Configurable classes and configuration files support an inheritance model. A Configurable class can derive from another Configurable class and override its parameters. Similarly, a configuration file can be included in another file.
Here is a simple example of a Configurable class:
from traitlets.config import Configurable
from traitlets import Float
class MyConfigurable(Configurable):
myvariable = Float(100.0, config=True)By default, an instance of the MyConfigurable class will have its myvariable attribute equal to 100.0. Now, let's assume that our IPython configuration file contains the following lines:
c = get_config() c.MyConfigurable.myvariable = 123.
Then, the myvariable attribute will default to 123. Instances are free to change this default value after they are instantiated.
The get_config() function is a special function that is available in any configuration file.
Additionally, Configurable parameters can be specified in the command-line interface, as we saw in this recipe.
This configuration system is used by all IPython applications (notably console, Qt console, and notebook). These applications have many configurable attributes. You will find the list of these attributes in your profile's configuration files.
The Magics class derives from Configurable and can contain configurable attributes. Moreover, magic commands can be defined by methods decorated by @line_magic or @cell_magic. The advantage of defining class magics instead of function magics (as in the preceding recipe) is that we can keep a state between multiple magic calls (because we are using a class instead of a function).
Configuring and customizing IPython, at http://ipython.readthedocs.io/en/stable/config/
Defining custom magics, available at http://ipython.readthedocs.io/en/stable/config/custommagics.html
Detailed overview of the configuration system, at https://traitlets.readthedocs.io/en/st