0
# Application Framework
1

2
Base application classes and infrastructure for building Jupyter applications. Provides standardized configuration management, logging, path handling, and lifecycle management that ensures consistency across the Jupyter ecosystem.
3

4
## Capabilities
5

6
### Base Application Class
7

8
The foundational application class that all Jupyter applications should inherit from. Provides configuration loading, directory management, and standardized initialization patterns.
9

10
```python { .api }
11
class JupyterApp(Application):
12
    """Base class for Jupyter applications"""
13
    
14
    # Class attributes
15
    name: str  # Application name (override in subclasses)
16
    description: str  # Application description  
17
    aliases: dict[str, Any]  # Command-line aliases
18
    flags: dict[str, Any]  # Command-line flags
19
    
20
    # Directory properties
21
    config_dir: str  # Jupyter config directory
22
    data_dir: str  # Jupyter data directory
23
    runtime_dir: str  # Jupyter runtime directory
24
    jupyter_path: list[str]  # Jupyter data search paths
25
    
26
    # Configuration properties
27
    config_file_paths: list[str]  # Config file search paths
28
    config_file_name: str  # Config file name pattern
29
    config_file: str  # Specific config file path
30
    generate_config: bool  # Whether to generate default config
31
    answer_yes: bool  # Auto-answer yes to prompts
32
    
33
    def initialize(self, argv=None) -> None:
34
        """Initialize the application."""
35
    
36
    def start(self) -> None:
37
        """Start the application."""
38
    
39
    def load_config_file(self, suppress_errors: bool = True) -> None:
40
        """Load configuration files."""
41
    
42
    def write_default_config(self) -> None:
43
        """Write default config to file."""
44
    
45
    def migrate_config(self) -> None:
46
        """Migrate config/data from IPython 3."""
47
    
48
    @classmethod
49
    def launch_instance(cls, argv=None, **kwargs) -> None:
50
        """Launch an instance of a Jupyter Application."""
51
    
52
    @property
53
    def config_file_paths(self) -> list[str]:
54
        """Return the search path for config files."""
55
```
56

57
**Usage Example:**
58

59
```python
60
from jupyter_core.application import JupyterApp
61

62
class MyApp(JupyterApp):
63
    name = "my-app"
64
    description = "My custom Jupyter application"
65
    
66
    def start(self):
67
        self.log.info("Application starting")
68
        print(f"Config dir: {self.config_dir}")
69
        print(f"Data dir: {self.data_dir}")
70
        # Application logic here
71

72
# Launch the application
73
if __name__ == "__main__":
74
    MyApp.launch_instance()
75
```
76

77
### Async Application Class
78

79
An async-aware version of JupyterApp for applications that need to run on asyncio event loops, such as web servers or real-time applications.
80

81
```python { .api }
82
class JupyterAsyncApp(JupyterApp):
83
    """A Jupyter application that runs on an asyncio loop."""
84
    
85
    # Class attributes
86
    name: str  # Application name (override in subclasses)
87
    description: str  # Application description
88
    _prefer_selector_loop: bool  # Prefer selector loop for tornado apps
89
    
90
    async def initialize_async(self, argv=None) -> None:
91
        """Initialize the application asynchronously."""
92
    
93
    async def start_async(self) -> None:
94
        """Run the application in an event loop."""
95
    
96
    @classmethod
97
    def launch_instance(cls, argv=None, **kwargs) -> None:
98
        """Launch an instance of an async Jupyter Application."""
99
```
100

101
**Usage Example:**
102

103
```python
104
from jupyter_core.application import JupyterAsyncApp
105
import asyncio
106

107
class MyAsyncApp(JupyterAsyncApp):
108
    name = "my-async-app"
109
    description = "My async Jupyter application"
110
    
111
    async def initialize_async(self, argv=None):
112
        await super().initialize_async(argv)
113
        self.log.info("Async initialization complete")
114
    
115
    async def start_async(self):
116
        self.log.info("Starting async application")
117
        # Async application logic here
118
        await asyncio.sleep(1)  # Example async operation
119

120
# Launch the async application  
121
if __name__ == "__main__":
122
    MyAsyncApp.launch_instance()
123
```
124

125
### Exception Classes
126

127
Exception types used by the application framework for controlling application flow and handling errors.
128

129
```python { .api }
130
class NoStart(Exception):
131
    """Exception to raise when an application shouldn't start"""
132
```
133

134
This exception is used internally to signal that an application should exit without error, such as when generating config files or displaying help information.
135

136
### Configuration Aliases and Flags
137

138
Pre-defined command-line aliases and flags that applications can inherit for consistent CLI behavior across the Jupyter ecosystem.
139

140
```python { .api }
141
# Base aliases inherited from traitlets + Jupyter-specific aliases
142
base_aliases: dict[str, Any] = {
143
    "log-level": "Application.log_level",
144
    "config": "JupyterApp.config_file",
145
    # ... additional aliases
146
}
147

148
# Base flags inherited from traitlets + Jupyter-specific flags
149
base_flags: dict[str, Any] = {
150
    "debug": (
151
        {"Application": {"log_level": logging.DEBUG}},
152
        "set log level to logging.DEBUG (maximize logging output)"
153
    ),
154
    "generate-config": (
155
        {"JupyterApp": {"generate_config": True}}, 
156
        "generate default config file"
157
    ),
158
    "y": (
159
        {"JupyterApp": {"answer_yes": True}},
160
        "Answer yes to any questions instead of prompting."
161
    ),
162
    # ... additional flags
163
}
164
```
165

166
These provide standard command-line options like `--debug`, `--generate-config`, and `--config` that users expect across all Jupyter applications.
167

168
## Configuration System Integration
169

170
The application framework integrates deeply with the traitlets configuration system to provide:
171

172
- **Hierarchical config loading**: System → Environment → User → CLI overrides
173
- **Multiple config formats**: Python (.py) and JSON (.json) config files  
174
- **Config file discovery**: Automatic searching in standard locations
175
- **CLI integration**: Automatic CLI argument parsing and validation
176
- **Type safety**: Automatic type conversion and validation
177
- **Documentation**: Self-documenting configuration with help text
178

179
## Directory Management
180

181
Applications automatically get access to standard Jupyter directories:
182

183
- **config_dir**: User configuration directory (`~/.jupyter` or platform equivalent)
184
- **data_dir**: User data directory (`~/.local/share/jupyter` or platform equivalent)  
185
- **runtime_dir**: Runtime directory for temporary files (typically `{data_dir}/runtime`)
186
- **jupyter_path**: Search path for data files (user → environment → system)
187

188
All directories are created automatically with appropriate permissions when accessed.
189

190
## Migration Support
191

192
Built-in support for migrating from IPython < 4.0 configurations, including:
193

194
- Configuration file migration with automatic class name updates
195
- Directory structure migration (kernels, extensions, custom files)
196
- Security file migration (secrets, signatures)
197
- Marker file creation to prevent duplicate migrations
198

199
This ensures smooth transitions for users upgrading from older IPython installations.