0
# Core Watermark Function
1

2
The main watermark function provides comprehensive system information generation with 26 configurable parameters. It outputs formatted text containing timestamps, version information, system details, and development environment data.
3

4
## Capabilities
5

6
### Main Function
7

8
Generates formatted watermark output based on specified parameters. When called with no parameters, provides default output including timestamp, Python/IPython versions, and system information.
9

10
```python { .api }
11
def watermark(
12
    author=None,
13
    email=None,
14
    github_username=None,
15
    website=None,
16
    current_date=False,
17
    datename=False,
18
    current_time=False,
19
    iso8601=False,
20
    timezone=False,
21
    updated=False,
22
    custom_time=None,
23
    python=False,
24
    packages=None,
25
    conda=False,
26
    hostname=False,
27
    machine=False,
28
    githash=False,
29
    gitrepo=False,
30
    gitbranch=False,
31
    watermark=False,
32
    iversions=False,
33
    gpu=False,
34
    watermark_self=None,
35
    globals_=None
36
):
37
    """
38
    Generate formatted watermark with system information.
39
    
40
    Parameters:
41
    - author (str, optional): Author name
42
    - email (str, optional): Author email address
43
    - github_username (str, optional): GitHub username
44
    - website (str, optional): Website or project URL
45
    - current_date (bool): Print current date as YYYY-mm-dd
46
    - datename (bool): Print date with abbreviated day/month names
47
    - current_time (bool): Print current time as HH-MM-SS
48
    - iso8601 (bool): Print ISO 8601 datetime with timezone
49
    - timezone (bool): Append local timezone to time
50
    - updated (bool): Add "Last updated:" prefix
51
    - custom_time (str, optional): Custom strftime format string
52
    - python (bool): Print Python implementation and version, IPython version
53
    - packages (str, optional): Comma-separated package names for version info
54
    - conda (bool): Print conda environment name
55
    - hostname (bool): Print system hostname
56
    - machine (bool): Print detailed system and machine information
57
    - githash (bool): Print current Git commit hash
58
    - gitrepo (bool): Print Git remote origin URL
59
    - gitbranch (bool): Print current Git branch name
60
    - watermark (bool): Print watermark package version
61
    - iversions (bool): Print versions of all imported modules
62
    - gpu (bool): Print GPU information (NVIDIA only, requires gpu extra)
63
    - watermark_self (WaterMark instance, optional): Required for iversions when used as magic
64
    - globals_ (dict, optional): Global namespace for iversions when used programmatically
65
    
66
    Returns:
67
    str: Formatted watermark text with requested information
68
    """
69
```
70

71
### Usage Examples
72

73
#### Default Output
74

75
```python
76
from watermark import watermark
77

78
# Default behavior: timestamp + Python info + system info
79
print(watermark())
80
```
81

82
#### Author and Contact Information
83

84
```python
85
# Basic author information
86
print(watermark(
87
    author="John Doe",
88
    email="john@example.com",
89
    github_username="johndoe"
90
))
91

92
# With website
93
print(watermark(
94
    author="Research Team",
95
    website="https://example.com/project"
96
))
97
```
98

99
#### Date and Time Formatting
100

101
```python
102
# Current date and time
103
print(watermark(current_date=True, current_time=True))
104

105
# Date with names and timezone
106
print(watermark(datename=True, current_time=True, timezone=True))
107

108
# ISO 8601 format
109
print(watermark(iso8601=True))
110

111
# Custom time format
112
print(watermark(custom_time="%A, %B %d, %Y at %I:%M %p"))
113

114
# With "Last updated" prefix
115
print(watermark(updated=True, current_date=True, current_time=True))
116
```
117

118
#### Version Information
119

120
```python
121
# Python and IPython versions
122
print(watermark(python=True))
123

124
# Specific package versions
125
print(watermark(packages="numpy,pandas,matplotlib"))
126

127
# Watermark package version
128
print(watermark(watermark=True))
129

130
# All imported package versions (requires globals)
131
import numpy as np
132
import pandas as pd
133
print(watermark(iversions=True, globals_=globals()))
134
```
135

136
#### System Information
137

138
```python
139
# System and machine details
140
print(watermark(machine=True))
141

142
# Hostname
143
print(watermark(hostname=True))
144

145
# Conda environment
146
print(watermark(conda=True))
147

148
# Combined system info
149
print(watermark(python=True, machine=True, hostname=True))
150
```
151

152
#### Git Information
153

154
```python
155
# Git commit hash
156
print(watermark(githash=True))
157

158
# Git repository URL
159
print(watermark(gitrepo=True))
160

161
# Git branch name
162
print(watermark(gitbranch=True))
163

164
# Complete Git info
165
print(watermark(githash=True, gitrepo=True, gitbranch=True))
166
```
167

168
#### GPU Information
169

170
```python
171
# Requires: pip install "watermark[gpu]"
172
print(watermark(gpu=True))
173
```
174

175
#### Complete Example
176

177
```python
178
from watermark import watermark
179
import numpy as np
180
import pandas as pd
181

182
# Comprehensive watermark for research reproducibility
183
result = watermark(
184
    author="Dr. Jane Smith",
185
    email="jane.smith@university.edu",
186
    updated=True,
187
    current_date=True,
188
    current_time=True,
189
    timezone=True,
190
    python=True,
191
    packages="numpy,pandas,scikit-learn,matplotlib",
192
    machine=True,
193
    hostname=True,
194
    githash=True,
195
    gitrepo=True,
196
    conda=True,
197
    iversions=True,
198
    globals_=globals()
199
)
200
print(result)
201
```
202

203
### Parameter Combinations
204

205
#### Research/Scientific Use
206

207
```python
208
# For reproducible research papers/notebooks
209
print(watermark(
210
    author="Research Team",
211
    updated=True,
212
    iso8601=True,
213
    python=True,
214
    packages="numpy,scipy,pandas,matplotlib,seaborn",
215
    machine=True,
216
    iversions=True,
217
    globals_=globals()
218
))
219
```
220

221
#### Development/Project Use
222

223
```python
224
# For development project documentation
225
print(watermark(
226
    author="Development Team",
227
    github_username="devteam",
228
    updated=True,
229
    current_date=True,
230
    python=True,
231
    githash=True,
232
    gitrepo=True,
233
    gitbranch=True,
234
    hostname=True
235
))
236
```
237

238
### Error Handling
239

240
The function handles various error conditions:
241

242
- **Missing packages**: Shows "not installed" for packages not found
243
- **Unknown versions**: Shows "unknown" when version cannot be determined
244
- **Git errors**: Gracefully handles non-Git directories
245
- **GPU unavailable**: Provides informative messages when GPU support not available
246
- **iversions requirements**: Raises `RuntimeError` if neither `watermark_self` nor `globals_` provided when `iversions=True`
247

248
### Return Format
249

250
The function returns a formatted string with sections separated by newlines. Each section contains key-value pairs aligned by the longest key name in that section:
251

252
```
253
Author             : John Doe
254
Last updated       : 2023-09-06 12:30:45
255

256
Python implementation: CPython
257
Python version       : 3.9.13
258
IPython version      : 8.4.0
259

260
Compiler    : GCC 9.4.0
261
OS          : Linux
262
Release     : 5.15.0
263
Machine     : x86_64
264
Processor   : x86_64
265
CPU cores   : 8
266
Architecture: 64bit
267
```