0
# Default Global Hooks and Auto-activation
1

2
Pre-configured global exception hooks and auto-activation modules that provide zero-configuration enhanced tracebacks with sensible defaults. These functions combine hook installation with environment-appropriate variable filtering and formatting.
3

4
## Capabilities
5

6
### Default Python Global Hook
7

8
Install enhanced exception handling for standard Python with pre-configured defaults including global variable hiding.
9

10
```python { .api }
11
def default_global_print_exc() -> None:
12
    """
13
    Install global exception hook with default settings for standard Python.
14
    
15
    Automatically configures the global default_format with:
16
    - Hides all global variables to reduce noise
17
    - Retains security-focused variable filtering (passwords, secrets, etc.)
18
    - Uses auto-detected color scheme
19
    - Installs sys.excepthook for unhandled exceptions
20
    
21
    Modifies the global default_format instance by adding global variable filtering.
22
    """
23
```
24

25
### Default IPython Global Hook
26

27
Install enhanced exception handling for IPython/Jupyter with IPython-specific filtering and formatting.
28

29
```python { .api }
30
def default_global_print_exc_in_ipython() -> None:
31
    """
32
    Install global exception hook with default settings for IPython/Jupyter.
33
    
34
    Automatically configures the global default_format with:
35
    - Hides IPython-specific global variables (In, Out, get_ipython, _* variables)
36
    - Forces 'common' color scheme suitable for notebooks
37
    - Retains security-focused variable filtering
38
    - Installs IPython.core.interactiveshell.InteractiveShell.showtraceback hook
39
    
40
    Modifies the global default_format instance by adding IPython-specific filtering.
41
    """
42
```
43

44
### Universal Auto-Detection Hook
45

46
Automatically detect the current environment and install the appropriate global hook.
47

48
```python { .api }
49
def default_global_print_exc_in_all() -> None:
50
    """
51
    Install appropriate global hook based on current environment detection.
52
    
53
    Automatically detects environment and calls either:
54
    - default_global_print_exc_in_ipython() if running in IPython/Jupyter
55
    - default_global_print_exc() if running in standard Python
56
    
57
    This is the most convenient function for universal enhanced traceback activation.
58
    """
59
```
60

61
### Auto-activation Modules
62

63
Import-based auto-activation modules that enable enhanced tracebacks with zero configuration.
64

65
```python { .api }
66
# Auto-activate in any environment (most convenient)
67
import traceback_with_variables.activate_by_import
68

69
# Auto-activate only in standard Python (not Jupyter/IPython)
70
import traceback_with_variables.activate_in_python_by_import
71

72
# Auto-activate only in Jupyter/IPython environments
73
import traceback_with_variables.activate_in_ipython_by_import
74

75
# Ultra-short alias for interactive use (same as activate_by_import)
76
import traceback_with_variables.a
77
```
78

79
## Usage Examples
80

81
### Universal Auto-activation (Recommended)
82

83
```python
84
# Single import enables enhanced tracebacks in any environment
85
import traceback_with_variables.activate_by_import
86

87
# All exceptions now show variables automatically
88
def example_function():
89
    user_data = {"id": 123, "name": "Alice", "settings": {"theme": "dark"}}
90
    return user_data["preferences"]["language"]  # KeyError with variables shown
91

92
example_function()  # Enhanced traceback displayed automatically
93
```
94

95
### Environment-Specific Auto-activation
96

97
```python
98
# For standard Python only (excludes Jupyter/IPython)
99
import traceback_with_variables.activate_in_python_by_import
100

101
# For Jupyter/IPython only (excludes standard Python)
102
import traceback_with_variables.activate_in_ipython_by_import
103

104
# Ultra-short for interactive debugging
105
import traceback_with_variables.a  # Same as activate_by_import
106
```
107

108
### Manual Default Hook Installation
109

110
```python
111
from traceback_with_variables.default_global_hooks import (
112
    default_global_print_exc_in_all,
113
    default_global_print_exc,
114
    default_global_print_exc_in_ipython
115
)
116

117
# Universal installation (recommended)
118
default_global_print_exc_in_all()
119

120
# Environment-specific installation
121
if in_jupyter_environment:
122
    default_global_print_exc_in_ipython()
123
else:
124
    default_global_print_exc()
125
```
126

127
### Comparing Default vs Custom Hooks
128

129
```python
130
from traceback_with_variables import (
131
    global_print_exc,           # Basic hook
132
    default_format,             # Global format instance
133
    Format                      # Custom format class
134
)
135
from traceback_with_variables.default_global_hooks import default_global_print_exc
136

137
# Basic hook with no special filtering
138
global_print_exc()
139

140
# vs.
141

142
# Default hook with automatic global variable hiding
143
default_global_print_exc()
144

145
# The default hook is equivalent to:
146
custom_format = default_format.replace(
147
    custom_var_printers=default_format.custom_var_printers + [
148
        (lambda name, type_, filename, is_global: is_global, lambda obj: None)
149
    ]
150
)
151
global_print_exc(fmt=custom_format)
152
```
153

154
### Production-Safe Default Configuration
155

156
```python
157
import os
158
from traceback_with_variables.default_global_hooks import default_global_print_exc_in_all
159

160
# Only enable in development/debug mode
161
if os.getenv('DEBUG', '').lower() in ('1', 'true', 'yes'):
162
    default_global_print_exc_in_all()
163
    print("Enhanced tracebacks enabled with default filtering")
164
else:
165
    print("Production mode - using standard tracebacks")
166

167
# Test the configuration
168
def test_function():
169
    config = {"database": {"host": "localhost", "port": 5432}}
170
    password = "secret123"  # Will be hidden by default security filtering
171
    connection_port = config["database"]["ssl_port"]  # Missing key
172

173
test_function()
174
```
175

176
### Interactive Development Setup
177

178
```python
179
# Perfect for interactive Python sessions or Jupyter notebooks
180
import traceback_with_variables.activate_by_import
181

182
# Or using the ultra-short alias
183
import traceback_with_variables.a
184

185
# Now all exceptions show variables with appropriate environment formatting
186
data = {"users": [{"id": 1, "name": "Alice"}]}
187
user = data["users"][0]["email"]  # Missing key, shows variables
188
```
189

190
### Temporary Auto-activation
191

192
```python
193
# Auto-activate for a specific code block
194
import traceback_with_variables.activate_by_import
195

196
try:
197
    # Code that might have exceptions
198
    debug_data = {"session": "active", "user_id": 12345}
199
    result = debug_data["nonexistent_key"]
200
    
201
except Exception as e:
202
    # Exception already displayed with variables due to auto-activation
203
    print("Exception was automatically enhanced")
204

205
# To disable, you would need to restore original hooks manually
206
# (not commonly needed since auto-activation is usually desired globally)
207
```
208

209
### Environment Detection Example
210

211
```python
212
from traceback_with_variables.global_hooks import in_ipython
213
from traceback_with_variables.default_global_hooks import (
214
    default_global_print_exc,
215
    default_global_print_exc_in_ipython
216
)
217

218
# Manual environment-specific configuration
219
if in_ipython():
220
    print("Detected IPython/Jupyter environment")
221
    default_global_print_exc_in_ipython()
222
else:
223
    print("Detected standard Python environment")
224
    default_global_print_exc()
225

226
# Test data
227
notebook_variables = {"cell_output": [1, 2, 3], "execution_count": 5}
228
missing_data = notebook_variables["undefined_variable"]  # Appropriate formatting applied
229
```