0
# IPython
1
2
IPython is an advanced interactive computing environment and command shell that extends the standard Python REPL with powerful features including comprehensive object introspection, persistent input history with session caching, extensible tab completion, a rich system of magic commands, configurable environments with profile switching, session logging and reloading capabilities, extensible syntax processing, integrated system shell access, easy embedding in other Python programs, and integrated access to debugging and profiling tools.
3
4
## Package Information
5
6
- **Package Name**: ipython
7
- **Language**: Python
8
- **Installation**: `pip install ipython`
9
- **Python Version**: >=3.11
10
11
## Core Imports
12
13
```python
14
import IPython
15
```
16
17
Common usage patterns:
18
19
```python
20
from IPython import start_ipython, embed, get_ipython
21
from IPython.display import display, HTML, Markdown, Image, Video, Audio, Javascript
22
from IPython.lib.display import FileLink, YouTubeVideo
23
from IPython.core.magic import line_magic, cell_magic, magics_class
24
```
25
26
## Basic Usage
27
28
```python
29
import IPython
30
31
# Start a full IPython session
32
IPython.start_ipython()
33
34
# Embed IPython in current scope for debugging
35
def my_function():
36
data = {"key": "value"}
37
IPython.embed() # Drops into IPython shell with access to local variables
38
return data
39
40
# Get current IPython instance
41
ipython = IPython.get_ipython()
42
if ipython is not None:
43
ipython.run_cell("print('Hello from IPython!')")
44
```
45
46
## Architecture
47
48
IPython follows a modular architecture with several key components:
49
50
- **InteractiveShell**: Core interactive environment managing execution, history, and state
51
- **Magic System**: Extensible command system for special functionality (% and %% commands)
52
- **Display System**: Rich output formatting and media display capabilities
53
- **Extension System**: Plugin architecture for adding custom functionality
54
- **Configuration System**: Traitlets-based configuration with profiles and persistent settings
55
- **Terminal Interface**: Advanced terminal integration with syntax highlighting and completion
56
57
This design enables IPython to serve as both a standalone interactive environment and an embeddable component for building custom interactive applications.
58
59
## Capabilities
60
61
### Core Shell Functions
62
63
Primary entry points for starting IPython sessions, embedding interactive shells, and managing the current IPython instance.
64
65
```python { .api }
66
def start_ipython(argv=None, **kwargs):
67
"""Launch a normal IPython instance (as opposed to embedded)"""
68
69
def embed(header='', compile_flags=None, **kwargs):
70
"""Embed and start IPython in a given scope"""
71
72
def get_ipython():
73
"""Get the currently running InteractiveShell instance, or None if not in IPython"""
74
```
75
76
[Core Shell](./core-shell.md)
77
78
### Magic System
79
80
Extensible command system providing special functionality through % (line) and %% (cell) magic commands, plus framework for creating custom magics.
81
82
```python { .api }
83
@magics_class
84
class MyMagics(Magics):
85
pass
86
87
@line_magic
88
def my_magic(self, line):
89
"""A simple line magic"""
90
91
@cell_magic
92
def my_cell_magic(self, line, cell):
93
"""A simple cell magic"""
94
```
95
96
[Magic System](./magic-system.md)
97
98
### Display System
99
100
Rich output formatting and media display capabilities for presenting HTML, images, videos, interactive widgets, and custom representations.
101
102
```python { .api }
103
def display(*objs, include=None, exclude=None, metadata=None, **kwargs):
104
"""Display objects with rich formatting"""
105
106
class HTML(DisplayObject):
107
"""HTML display object"""
108
109
class Image(DisplayObject):
110
"""Image display object"""
111
```
112
113
[Display System](./display-system.md)
114
115
### Extension System
116
117
Plugin architecture for loading and managing IPython extensions that add custom functionality, magic commands, and hooks.
118
119
```python { .api }
120
def load_ipython_extension(ipython):
121
"""Extension loading entry point"""
122
123
def unload_ipython_extension(ipython):
124
"""Extension unloading entry point"""
125
126
class ExtensionManager:
127
"""Manages loading and unloading of extensions"""
128
```
129
130
[Extension System](./extension-system.md)
131
132
### Terminal Interface and Embedding
133
134
Advanced terminal integration with syntax highlighting, tab completion, keyboard shortcuts, and embedding capabilities for interactive debugging.
135
136
```python { .api }
137
class TerminalInteractiveShell(InteractiveShell):
138
"""Terminal-based interactive shell"""
139
140
def embed(header='', compile_flags=None, **kwargs):
141
"""Embed IPython in current scope"""
142
```
143
144
[Terminal Interface](./terminal-interface.md)
145
146
### Configuration and Utilities
147
148
Configuration management through profiles, path utilities for IPython directories, and system information functions.
149
150
```python { .api }
151
def get_ipython_dir():
152
"""Get the IPython directory path"""
153
154
def locate_profile(profile='default'):
155
"""Find a profile directory"""
156
157
def sys_info():
158
"""Get system information"""
159
```
160
161
[Configuration and Utilities](./configuration-utilities.md)
162
163
## Types
164
165
```python { .api }
166
class InteractiveShell:
167
"""Core interactive shell implementation"""
168
169
def run_cell(self, raw_cell, store_history=True, silent=False, shell_futures=True):
170
"""Execute a code cell"""
171
172
def complete(self, text, line=None, cursor_pos=None):
173
"""Perform tab completion"""
174
175
def object_inspect(self, oname, detail_level=0):
176
"""Inspect an object"""
177
178
class DisplayObject:
179
"""Base class for rich display objects"""
180
181
def __init__(self, data=None, url=None, filename=None, metadata=None):
182
pass
183
184
class Magics:
185
"""Base class for magic command collections"""
186
187
def __init__(self, shell=None):
188
pass
189
```