0
# Jupyter Core
1

2
A foundational Python package that provides core functionality for the Jupyter ecosystem. It contains base application classes, configuration management systems, path utilities, and command-line tools that serve as the foundation for notebooks, kernels, and other Jupyter components. Designed for maximum reusability across the Jupyter ecosystem with built-in cross-platform compatibility.
3

4
## Package Information
5

6
- **Package Name**: jupyter_core
7
- **Language**: Python
8
- **Installation**: `pip install jupyter_core`
9
- **Minimum Python Version**: 3.8+
10

11
## Core Imports
12

13
```python
14
import jupyter_core
15
```
16

17
For version information:
18

19
```python
20
from jupyter_core import __version__, version_info
21
```
22

23
For application development:
24

25
```python
26
from jupyter_core.application import JupyterApp, JupyterAsyncApp
27
```
28

29
For path utilities:
30

31
```python
32
from jupyter_core.paths import (
33
    jupyter_config_dir, jupyter_data_dir, jupyter_runtime_dir,
34
    jupyter_path, jupyter_config_path
35
)
36
```
37

38
## Basic Usage
39

40
```python
41
from jupyter_core.paths import jupyter_config_dir, jupyter_data_dir
42
from jupyter_core.application import JupyterApp
43

44
# Get standard Jupyter directories
45
config_dir = jupyter_config_dir()
46
data_dir = jupyter_data_dir()
47
print(f"Config directory: {config_dir}")
48
print(f"Data directory: {data_dir}")
49

50
# Create a simple Jupyter application
51
class MyJupyterApp(JupyterApp):
52
    name = "my-jupyter-app"
53
    description = "My custom Jupyter application"
54
    
55
    def start(self):
56
        self.log.info("Starting my Jupyter application")
57
        print(f"Using config directory: {self.config_dir}")
58
        print(f"Using data directory: {self.data_dir}")
59

60
# Launch the application
61
if __name__ == "__main__":
62
    MyJupyterApp.launch_instance()
63
```
64

65
## Architecture
66

67
Jupyter Core follows a layered architecture designed for extensibility:
68

69
- **Application Layer**: Base application classes (JupyterApp, JupyterAsyncApp) that provide common functionality for Jupyter applications including configuration loading, logging, and directory management
70
- **Path Management Layer**: Cross-platform utilities for discovering and managing Jupyter directories with support for user, environment, and system-wide installations
71
- **Configuration Layer**: Integration with traitlets for declarative configuration with support for config files, command-line arguments, and environment variables
72
- **Utility Layer**: Core utilities for directory creation, async event loop management, deprecation warnings, and platform-specific operations
73
- **Command-Line Layer**: Tools for subcommand discovery and execution, migration from IPython, and system troubleshooting
74

75
This design enables consistent behavior across all Jupyter components while supporting the diverse needs of notebooks, kernels, extensions, and custom applications.
76

77
## Capabilities
78

79
### Application Framework
80

81
Base application classes and infrastructure for building Jupyter applications with built-in configuration management, logging, path handling, and lifecycle management.
82

83
```python { .api }
84
class JupyterApp:
85
    def __init__(self): ...
86
    def initialize(self, argv=None): ...
87
    def start(self): ...
88
    @classmethod
89
    def launch_instance(cls, argv=None, **kwargs): ...
90

91
class JupyterAsyncApp(JupyterApp):
92
    async def initialize_async(self, argv=None): ...
93
    async def start_async(self): ...
94
```
95

96
[Application Framework](./application-framework.md)
97

98
### Path Management
99

100
Cross-platform directory discovery and path utilities for managing Jupyter configuration, data, and runtime directories with support for user-level, environment-level, and system-wide installations.
101

102
```python { .api }
103
def jupyter_config_dir() -> str: ...
104
def jupyter_data_dir() -> str: ...
105
def jupyter_runtime_dir() -> str: ...
106
def jupyter_path(*subdirs: str) -> list[str]: ...
107
def jupyter_config_path() -> list[str]: ...
108
```
109

110
[Path Management](./path-management.md)
111

112
### Command-Line Tools
113

114
Command-line utilities for Jupyter ecosystem management including the main jupyter command dispatcher, migration tools, and troubleshooting utilities.
115

116
```python { .api }
117
def main() -> None: ...
118
def list_subcommands() -> list[str]: ...
119
def migrate() -> bool: ...
120
def get_data() -> dict[str, Any]: ...
121
```
122

123
[Command-Line Tools](./command-line-tools.md)
124

125
### Utility Functions
126

127
Core utility functions for directory management, deprecation warnings, async support, and platform-specific operations used throughout the Jupyter ecosystem.
128

129
```python { .api }
130
def ensure_dir_exists(path: str | Path, mode: int = 0o777) -> None: ...
131
def deprecation(message: str, internal: str | list[str] = "jupyter_core/") -> None: ...
132
def run_sync(coro: Callable[..., Awaitable[T]]) -> Callable[..., T]: ...
133
def ensure_event_loop(prefer_selector_loop: bool = False) -> AbstractEventLoop: ...
134
```
135

136
[Utility Functions](./utility-functions.md)
137

138
## Types
139

140
```python { .api }
141
from typing import Any, Awaitable, Callable, TypeVar
142
from pathlib import Path
143
from traitlets.config.application import Application
144

145
# Version information
146
__version__: str
147
version_info: tuple[int, int, int, ...]
148

149
# Exception types  
150
class NoStart(Exception): ...
151

152
# Type variables
153
T = TypeVar("T")
154
```