0
# IPython Magic Extension
1

2
The IPython magic extension provides command-line style interface to watermark functionality, designed for interactive use in Jupyter notebooks and IPython sessions. It offers the same capabilities as the core function but with CLI-style argument parsing.
3

4
## Capabilities
5

6
### Loading the Extension
7

8
Load the watermark magic extension in IPython or Jupyter:
9

10
```python { .api }
11
def load_ipython_extension(ipython):
12
    """
13
    Register the WaterMark magic class with IPython.
14
    
15
    Parameters:
16
    - ipython: IPython instance
17
    """
18
```
19

20
### Magic Command Class
21

22
The main magic command implementation providing watermark functionality through line magic.
23

24
```python { .api }
25
class WaterMark(Magics):
26
    """
27
    IPython magic function to print date/time stamps and various system information.
28
    """
29
    
30
    def watermark(self, line):
31
        """
32
        IPython magic command for generating watermarks.
33
        
34
        Parameters:
35
        - line (str): Command line arguments in CLI format
36
        """
37
```
38

39
### Magic Command Arguments
40

41
The `%watermark` magic command accepts the following arguments:
42

43
```python { .api }
44
# Author and Contact Information
45
-a AUTHOR, --author AUTHOR                    # Author name
46
-gu GITHUB_USERNAME, --github_username        # GitHub username  
47
-e EMAIL, --email EMAIL                       # Email address
48
-ws WEBSITE, --website WEBSITE                # Website URL
49

50
# Date and Time Options
51
-d, --date                                    # Current date (YYYY-mm-dd)
52
-n, --datename                               # Date with day/month names
53
-t, --time                                   # Current time (HH-MM-SS)
54
-i, --iso8601                                # ISO 8601 datetime with timezone
55
-z, --timezone                               # Append timezone to time
56
-u, --updated                                # Add "Last updated:" prefix
57
-c CUSTOM_TIME, --custom_time CUSTOM_TIME    # Custom strftime format
58

59
# Version Information
60
-v, --python                                 # Python and IPython versions
61
-p PACKAGES, --packages PACKAGES             # Package versions (comma-separated)
62
-w, --watermark                              # Watermark package version
63
-iv, --iversions                             # All imported module versions
64

65
# System Information  
66
-m, --machine                                # System and machine info
67
-h, --hostname                               # Hostname
68
-co, --conda                                 # Conda environment name
69
--gpu                                        # GPU information (NVIDIA)
70

71
# Git Information
72
-g, --githash                                # Git commit hash
73
-r, --gitrepo                                # Git remote origin URL
74
-b, --gitbranch                              # Git branch name
75
```
76

77
### Usage Examples
78

79
#### Basic Usage
80

81
```python
82
# Load the extension
83
%load_ext watermark
84

85
# Default output (timestamp + Python info + system info)
86
%watermark
87

88
# Get help
89
%watermark?
90
```
91

92
#### Author Information
93

94
```python
95
# Author details
96
%watermark -a "Dr. Jane Smith" -e "jane@university.edu"
97

98
# With GitHub username
99
%watermark -a "John Doe" -gu "johndoe"
100

101
# With website
102
%watermark -a "Research Team" -ws "https://example.com/project"
103
```
104

105
#### Date and Time
106

107
```python
108
# Current date and time
109
%watermark -d -t
110

111
# Date with names and timezone
112
%watermark -n -t -z
113

114
# ISO 8601 format
115
%watermark -i
116

117
# Custom time format
118
%watermark -c "%A, %B %d, %Y at %I:%M %p"
119

120
# With update prefix
121
%watermark -u -d -t
122
```
123

124
#### Version Information
125

126
```python
127
# Python versions
128
%watermark -v
129

130
# Specific packages
131
%watermark -p numpy,pandas,matplotlib
132

133
# Watermark version
134
%watermark -w
135

136
# All imported packages
137
import numpy as np
138
import pandas as pd
139
%watermark -iv
140
```
141

142
#### System Information
143

144
```python
145
# System details
146
%watermark -m
147

148
# Hostname
149
%watermark -h
150

151
# Conda environment
152
%watermark -co
153

154
# Combined system info
155
%watermark -v -m -h
156
```
157

158
#### Git Information
159

160
```python
161
# Git commit hash
162
%watermark -g
163

164
# Git repository
165
%watermark -r
166

167
# Git branch
168
%watermark -b
169

170
# Complete Git info
171
%watermark -g -r -b
172
```
173

174
#### GPU Information
175

176
```python
177
# Requires: pip install "watermark[gpu]"
178
%watermark --gpu
179
```
180

181
#### Combined Examples
182

183
```python
184
# Research reproducibility
185
%watermark -a "Dr. Jane Smith" -u -i -v -p numpy,scipy,pandas -m -iv
186

187
# Development workflow
188
%watermark -a "Dev Team" -gu "devteam" -u -d -v -g -r -b -h
189

190
# Publication ready
191
%watermark -a "Research Lab" -e "contact@lab.edu" -u -n -t -z -v -p "numpy,scipy,matplotlib,seaborn" -m -co
192

193
# Quick version check
194
%watermark -v -p numpy,pandas
195
```
196

197
### Magic vs Function Interface
198

199
The magic command arguments map to function parameters as follows:
200

201
| Magic Argument | Function Parameter | Type |
202
|----------------|-------------------|------|
203
| `-a/--author` | `author` | str |
204
| `-gu/--github_username` | `github_username` | str |
205
| `-e/--email` | `email` | str |
206
| `-ws/--website` | `website` | str |
207
| `-d/--date` | `current_date` | bool |
208
| `-n/--datename` | `datename` | bool |
209
| `-t/--time` | `current_time` | bool |
210
| `-i/--iso8601` | `iso8601` | bool |
211
| `-z/--timezone` | `timezone` | bool |
212
| `-u/--updated` | `updated` | bool |
213
| `-c/--custom_time` | `custom_time` | str |
214
| `-v/--python` | `python` | bool |
215
| `-p/--packages` | `packages` | str |
216
| `-co/--conda` | `conda` | bool |
217
| `-h/--hostname` | `hostname` | bool |
218
| `-m/--machine` | `machine` | bool |
219
| `-g/--githash` | `githash` | bool |
220
| `-r/--gitrepo` | `gitrepo` | bool |
221
| `-b/--gitbranch` | `gitbranch` | bool |
222
| `-w/--watermark` | `watermark` | bool |
223
| `-iv/--iversions` | `iversions` | bool |
224
| `--gpu` | `gpu` | bool |
225
226
### Extension Registration
227

228
The extension is automatically registered when loaded:
229

230
```python
231
%load_ext watermark
232
```
233

234
This is equivalent to:
235

236
```python
237
from watermark.magic import load_ipython_extension
238
load_ipython_extension(get_ipython())
239
```
240

241
### Exception Handling
242

243
```python { .api }
244
class PackageNotFoundError(Exception):
245
    """
246
    Custom exception for package not found scenarios.
247
    Raised when specified packages cannot be located.
248
    """
249
    pass
250
```
251

252
### Magic Command Workflow
253

254
1. **Argument Parsing**: CLI-style arguments parsed using IPython's magic argument system
255
2. **Parameter Mapping**: Magic arguments converted to function parameters
256
3. **Context Injection**: Magic instance (`self`) passed as `watermark_self` for `iversions` functionality  
257
4. **Function Call**: Core `watermark()` function called with converted parameters
258
5. **Output Display**: Formatted result printed directly to the console
259

260
### Interactive Features
261

262
The magic command is designed for interactive workflows:
263

264
- **Tab completion**: Available for argument names
265
- **Help system**: `%watermark?` shows complete argument documentation
266
- **Error feedback**: Clear error messages for invalid arguments
267
- **Jupyter integration**: Works seamlessly in Jupyter notebooks and JupyterLab
268
- **IPython session**: Full functionality in IPython command-line sessions