tessl/pypi-watermark

IPython magic extension for printing date/time stamps, version numbers, and hardware information.

Overview

Eval results

Files

Core Watermark Function

Name: tessl/pypi-watermark
Author: tessl

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.

Capabilities

Main Function

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

def watermark(
    author=None,
    email=None,
    github_username=None,
    website=None,
    current_date=False,
    datename=False,
    current_time=False,
    iso8601=False,
    timezone=False,
    updated=False,
    custom_time=None,
    python=False,
    packages=None,
    conda=False,
    hostname=False,
    machine=False,
    githash=False,
    gitrepo=False,
    gitbranch=False,
    watermark=False,
    iversions=False,
    gpu=False,
    watermark_self=None,
    globals_=None
):
    """
    Generate formatted watermark with system information.
    
    Parameters:
    - author (str, optional): Author name
    - email (str, optional): Author email address
    - github_username (str, optional): GitHub username
    - website (str, optional): Website or project URL
    - current_date (bool): Print current date as YYYY-mm-dd
    - datename (bool): Print date with abbreviated day/month names
    - current_time (bool): Print current time as HH-MM-SS
    - iso8601 (bool): Print ISO 8601 datetime with timezone
    - timezone (bool): Append local timezone to time
    - updated (bool): Add "Last updated:" prefix
    - custom_time (str, optional): Custom strftime format string
    - python (bool): Print Python implementation and version, IPython version
    - packages (str, optional): Comma-separated package names for version info
    - conda (bool): Print conda environment name
    - hostname (bool): Print system hostname
    - machine (bool): Print detailed system and machine information
    - githash (bool): Print current Git commit hash
    - gitrepo (bool): Print Git remote origin URL
    - gitbranch (bool): Print current Git branch name
    - watermark (bool): Print watermark package version
    - iversions (bool): Print versions of all imported modules
    - gpu (bool): Print GPU information (NVIDIA only, requires gpu extra)
    - watermark_self (WaterMark instance, optional): Required for iversions when used as magic
    - globals_ (dict, optional): Global namespace for iversions when used programmatically
    
    Returns:
    str: Formatted watermark text with requested information
    """

Usage Examples

Default Output

from watermark import watermark

# Default behavior: timestamp + Python info + system info
print(watermark())

Author and Contact Information

# Basic author information
print(watermark(
    author="John Doe",
    email="john@example.com",
    github_username="johndoe"
))

# With website
print(watermark(
    author="Research Team",
    website="https://example.com/project"
))

Date and Time Formatting

# Current date and time
print(watermark(current_date=True, current_time=True))

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

# ISO 8601 format
print(watermark(iso8601=True))

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

# With "Last updated" prefix
print(watermark(updated=True, current_date=True, current_time=True))

Version Information

# Python and IPython versions
print(watermark(python=True))

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

# Watermark package version
print(watermark(watermark=True))

# All imported package versions (requires globals)
import numpy as np
import pandas as pd
print(watermark(iversions=True, globals_=globals()))

System Information

# System and machine details
print(watermark(machine=True))

# Hostname
print(watermark(hostname=True))

# Conda environment
print(watermark(conda=True))

# Combined system info
print(watermark(python=True, machine=True, hostname=True))

Git Information

# Git commit hash
print(watermark(githash=True))

# Git repository URL
print(watermark(gitrepo=True))

# Git branch name
print(watermark(gitbranch=True))

# Complete Git info
print(watermark(githash=True, gitrepo=True, gitbranch=True))

GPU Information

# Requires: pip install "watermark[gpu]"
print(watermark(gpu=True))

Complete Example

from watermark import watermark
import numpy as np
import pandas as pd

# Comprehensive watermark for research reproducibility
result = watermark(
    author="Dr. Jane Smith",
    email="jane.smith@university.edu",
    updated=True,
    current_date=True,
    current_time=True,
    timezone=True,
    python=True,
    packages="numpy,pandas,scikit-learn,matplotlib",
    machine=True,
    hostname=True,
    githash=True,
    gitrepo=True,
    conda=True,
    iversions=True,
    globals_=globals()
)
print(result)

Parameter Combinations

Research/Scientific Use

# For reproducible research papers/notebooks
print(watermark(
    author="Research Team",
    updated=True,
    iso8601=True,
    python=True,
    packages="numpy,scipy,pandas,matplotlib,seaborn",
    machine=True,
    iversions=True,
    globals_=globals()
))

Development/Project Use

# For development project documentation
print(watermark(
    author="Development Team",
    github_username="devteam",
    updated=True,
    current_date=True,
    python=True,
    githash=True,
    gitrepo=True,
    gitbranch=True,
    hostname=True
))

Error Handling

The function handles various error conditions:

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

Return Format

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:

Author             : John Doe
Last updated       : 2023-09-06 12:30:45

Python implementation: CPython
Python version       : 3.9.13
IPython version      : 8.4.0

Compiler    : GCC 9.4.0
OS          : Linux
Release     : 5.15.0
Machine     : x86_64
Processor   : x86_64
CPU cores   : 8
Architecture: 64bit

Install with Tessl CLI

npx tessl i tessl/pypi-watermark

docs