Welcome to Dynamic IPython’s documentation!

date

September 14, 2020

Startup Scripts

This repository hosts startup scripts that can be used during IPython’s startup.

The scripts add well over 1000 aliases to the namespace, import commonly used modules, instantiate exception hooks from cgitb, format a traceback, import readline to add additional keybindings as well as checking for pyreadline for Windows users, lex documents with the pygments library and stylize the REPL as a result, add multiple application specific loggers, and more.

Heavy use of prompt_toolkit and Jedi’s respective APIs are utilized here.

As both libraries as well as pygments are explicit dependencies of IPython, no additional installation is required for those features.

Specifically, new completers are added to the shell to handle fuzzy completion as well as autocompletion of paths and executables.

Portability

Portability was a major factor while writing these scripts.

Therefore, any script should work on:

  • Ubuntu

  • Android

  • Windows 10

On Windows 10, the scripts have been primarily tested in powershell windows or in a shell with either ConEmu or Cmder.

As a result, there may be unexpected behavior that arises when running the following scripts while within in an unmodified cmd shell.

Motivation

The intent was to create a system that worked on any relatively modern platform.

I regularly use IPython as a system shell in comparison to the typical Bash shell that Unix OSes provide. While a terminal provides a huge number of powerful commands and the ability to pipe them together, Bash still has a number of inconsistencies and oddities in its behavior.

Installation

This repository can be installed in the following manner.:

python setup.py build
pip install -U -e .

However, that unfortunately assumes one has admin access to wherever pip installs files globally, and that the python command points to python3.7. In most cases it does not.

If one has pipenv installed, an easier installation could be pipenv install -e .

If a non-pipenv installation is desired for some reason, a fully specified installation could look like.

python3 setup.py build
python3 -m pip install -U --user pip -e .

As one can see this gets complicated very quickly, and as a result, installation via pipenv is the recommended method.

See Also

For commands that are more related to the interactive aspect of the shell, see the following.

In [1]: from IPython import get_ipython

In [2]: _ip = get_ipython()

In [3]: help(_ip)  # doctest: +SKIP

In [4]: dir(_ip):  # doctest: +SKIP

Which features descriptions of functions relevant to startup such as IPython.core.interactiveshell.register_magic_function() and literally every option available through the %config magic.

In addition, there’s an abundance of documentation online in the form of rst docs and ipynb notebooks.

Table of Contents

Startup

The first script to run invokes %rehashx which initializes IPython with all of the commands that the system shell knows.

By invoking %rehashx at the beginning of startup, all system commands are added as well, which regularly adds well over 1000 commands to the shell.

The IPython team cleverly remembers to also check the environment variable PATHEXT on Windows devices as it indicates to the system which files are executable without requiring the typical Unix file permissions system.

Before delving into the startup files, the API for the main IPython config file will be discussed.

This is simply a heavily configured version of the file that’s generated when ipython --generate-config is run on the command line.

As a result, it heavily utilizes the traitlets module.

IPython Config API

get_home()[source][source]

Define the user’s HOME.

exception ApplicationError[source][source]

Bases: Exception

Base exception class.

exception UsageError(err=None, *args, **kwargs)[source][source]

Bases: default_profile.ipython_config.ApplicationError

__init__(err=None, *args, **kwargs)[source][source]
exception NotInIPythonError(*args, **kwargs)[source][source]

Bases: default_profile.ipython_config.UsageError

Error raised when a magic is invoked outside of IPython.

__init__(*args, **kwargs)[source][source]
exception AliasError[source][source]

Bases: Exception

exception InvalidAliasError[source][source]

Bases: default_profile.ipython_config.AliasError

conditional_editing_mode()[source][source]

Execute this function to enable the emacs editing mode on Windows and vi only in tmux.

get_env()[source][source]

Would it make sense to combine functools.lru_cache with this?

class TimedFormatter(*args, **kwargs)[source][source]

Bases: object

I’d imagine this would benefit from a dataclass.

Rewrite the init so that it takes advantage of the dataclass module. If that doesn’t seem to be working namedtuples are similar.

loops: int[source]
precision: int[source]
repeat: int[source]
all_runs: set[source]
__init__(*args, **kwargs)[source][source]
summary()[source][source]
timings()[source][source]

IPython-specific Sphinx extensions.

The default_profile.sphinxext package. Imports the modules found in the current directory and utilizes pkgutil and pkgutil.extend_path() to extend the packages __path__ parameter.

It only imports the modules below if this repository has been installed.

If this weren’t true, then starting IPython without this package installed would emit ImportError on startup, which would be frustrating for users.

sphinx

Extensions

In addition this repository handles a growing number of IPython extensions.

Some of the bundled extensions provide a more usable PAGER for users on Window than the one provided by pydoc.

Here are the varying %magic extensions that are bundled with this portion of the repository.

Extensions

Continue reading with the pandas extension at Pandas CSV.

Utilities

The modules contained in this package are, generally speaking, a collection of scripts that I’ve found useful while working with IPython, but that unfortunately haven’t been fleshed out enough.

They’re still all useful in their current state and when the user is running IPython interactively, but none of the scripts haven’t been fleshed out to the extent that they could be easily changed to IPython extensions.

Goals

Currently the module aims to:

  1. Create consistent logging.Logger objects

  2. Make a better pager on Windows

  3. Create a collection of classes that can more easily remove platform-specific issues that continue to arise.

In addition, configure a module-wide logger by equating logging.BASIC_FORMAT with a pre-determined template string like so:

>>> logging.BASIC_FORMAT = '%(asctime)s : %(levelname)s : %(message)s'
>>> UTIL_LOGGER = logging.getLogger('default_profile.util')
>>> UTIL_LOGGER.setLevel(logging.WARNING)

The submodules contained in this package are as follows: