0
# Watermark
1

2
An IPython magic extension that provides comprehensive system information, timestamps, and version tracking capabilities for reproducible research and development workflows. Watermark enables developers to generate detailed watermarks containing date/time stamps, version numbers, and hardware information through both magic commands and programmatic function calls.
3

4
## Package Information
5

6
- **Package Name**: watermark
7
- **Language**: Python
8
- **Installation**: `pip install watermark`
9
- **GPU Support**: `pip install "watermark[gpu]"`
10

11
## Core Imports
12

13
```python
14
import watermark
15
from watermark import watermark
16
```
17

18
For IPython magic functionality:
19

20
```python
21
%load_ext watermark
22
```
23

24
## Basic Usage
25

26
### IPython Magic Command
27

28
Load the extension and use the magic command:
29

30
```python
31
%load_ext watermark
32

33
# Default output with timestamp, Python version, and system info
34
%watermark
35

36
# Show specific information
37
%watermark -v -m -p numpy,pandas
38
%watermark -a "Author Name" -d -t
39
%watermark -iv  # Show all imported package versions
40
```
41

42
### Programmatic Function Usage
43

44
Use watermark as a regular Python function:
45

46
```python
47
from watermark import watermark
48

49
# Default output
50
print(watermark())
51

52
# Specific information
53
print(watermark(python=True, machine=True, packages="numpy,pandas"))
54
print(watermark(author="Author Name", current_date=True, current_time=True))
55

56
# Get imported package versions (requires globals)
57
print(watermark(iversions=True, globals_=globals()))
58
```
59

60
## Architecture
61

62
Watermark provides two primary interfaces:
63

64
- **Magic Interface**: IPython magic command (`%watermark`) for interactive notebook and IPython session usage
65
- **Function Interface**: Direct function calls (`watermark()`) for programmatic access and script integration
66

67
Both interfaces share the same underlying functionality but use different parameter formats (CLI-style flags vs keyword arguments).
68

69
## Capabilities
70

71
### Core Watermark Function
72

73
The main watermark functionality that generates formatted output containing system information, timestamps, and version data based on specified parameters.
74

75
```python { .api }
76
def watermark(
77
    author=None,
78
    email=None, 
79
    github_username=None,
80
    website=None,
81
    current_date=False,
82
    datename=False,
83
    current_time=False,
84
    iso8601=False,
85
    timezone=False,
86
    updated=False,
87
    custom_time=None,
88
    python=False,
89
    packages=None,
90
    conda=False,
91
    hostname=False,
92
    machine=False,
93
    githash=False,
94
    gitrepo=False,
95
    gitbranch=False,
96
    watermark=False,
97
    iversions=False,
98
    gpu=False,
99
    watermark_self=None,
100
    globals_=None
101
): ...
102
```
103

104
[Core Function](./core-function.md)
105

106
### IPython Magic Extension
107

108
IPython magic command interface providing the same functionality through command-line style arguments for interactive usage in notebooks and IPython sessions.
109

110
```python { .api }
111
class WaterMark(Magics):
112
    def watermark(self, line): ...
113

114
def load_ipython_extension(ipython): ...
115
```
116

117
[IPython Magic](./magic-extension.md)
118

119
## Types
120

121
```python { .api }
122
class PackageNotFoundError(Exception):
123
    """Custom exception for package not found scenarios."""
124
    pass
125
```