tessl/pypi-watermark

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

Overview

Eval results

Files

IPython Magic Extension

Name: tessl/pypi-watermark
Author: tessl

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.

Capabilities

Loading the Extension

Load the watermark magic extension in IPython or Jupyter:

def load_ipython_extension(ipython):
    """
    Register the WaterMark magic class with IPython.
    
    Parameters:
    - ipython: IPython instance
    """

Magic Command Class

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

class WaterMark(Magics):
    """
    IPython magic function to print date/time stamps and various system information.
    """
    
    def watermark(self, line):
        """
        IPython magic command for generating watermarks.
        
        Parameters:
        - line (str): Command line arguments in CLI format
        """

Magic Command Arguments

The %watermark magic command accepts the following arguments:

# Author and Contact Information
-a AUTHOR, --author AUTHOR                    # Author name
-gu GITHUB_USERNAME, --github_username        # GitHub username  
-e EMAIL, --email EMAIL                       # Email address
-ws WEBSITE, --website WEBSITE                # Website URL

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

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

# System Information  
-m, --machine                                # System and machine info
-h, --hostname                               # Hostname
-co, --conda                                 # Conda environment name
--gpu                                        # GPU information (NVIDIA)

# Git Information
-g, --githash                                # Git commit hash
-r, --gitrepo                                # Git remote origin URL
-b, --gitbranch                              # Git branch name

Usage Examples

Basic Usage

# Load the extension
%load_ext watermark

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

# Get help
%watermark?

Author Information

# Author details
%watermark -a "Dr. Jane Smith" -e "jane@university.edu"

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

# With website
%watermark -a "Research Team" -ws "https://example.com/project"

Date and Time

# Current date and time
%watermark -d -t

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

# ISO 8601 format
%watermark -i

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

# With update prefix
%watermark -u -d -t

Version Information

# Python versions
%watermark -v

# Specific packages
%watermark -p numpy,pandas,matplotlib

# Watermark version
%watermark -w

# All imported packages
import numpy as np
import pandas as pd
%watermark -iv

System Information

# System details
%watermark -m

# Hostname
%watermark -h

# Conda environment
%watermark -co

# Combined system info
%watermark -v -m -h

Git Information

# Git commit hash
%watermark -g

# Git repository
%watermark -r

# Git branch
%watermark -b

# Complete Git info
%watermark -g -r -b

GPU Information

# Requires: pip install "watermark[gpu]"
%watermark --gpu

Combined Examples

# Research reproducibility
%watermark -a "Dr. Jane Smith" -u -i -v -p numpy,scipy,pandas -m -iv

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

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

# Quick version check
%watermark -v -p numpy,pandas

Magic vs Function Interface

The magic command arguments map to function parameters as follows:

Magic Argument	Function Parameter	Type
`-a/--author`	`author`	str
`-gu/--github_username`	`github_username`	str
`-e/--email`	`email`	str
`-ws/--website`	`website`	str
`-d/--date`	`current_date`	bool
`-n/--datename`	`datename`	bool
`-t/--time`	`current_time`	bool
`-i/--iso8601`	`iso8601`	bool
`-z/--timezone`	`timezone`	bool
`-u/--updated`	`updated`	bool
`-c/--custom_time`	`custom_time`	str
`-v/--python`	`python`	bool
`-p/--packages`	`packages`	str
`-co/--conda`	`conda`	bool
`-h/--hostname`	`hostname`	bool
`-m/--machine`	`machine`	bool
`-g/--githash`	`githash`	bool
`-r/--gitrepo`	`gitrepo`	bool
`-b/--gitbranch`	`gitbranch`	bool
`-w/--watermark`	`watermark`	bool
`-iv/--iversions`	`iversions`	bool
`--gpu`	`gpu`	bool

Extension Registration

The extension is automatically registered when loaded:

%load_ext watermark

This is equivalent to:

from watermark.magic import load_ipython_extension
load_ipython_extension(get_ipython())

Exception Handling

class PackageNotFoundError(Exception):
    """
    Custom exception for package not found scenarios.
    Raised when specified packages cannot be located.
    """
    pass

Magic Command Workflow

Argument Parsing: CLI-style arguments parsed using IPython's magic argument system
Parameter Mapping: Magic arguments converted to function parameters
Context Injection: Magic instance (self) passed as watermark_self for iversions functionality
Function Call: Core watermark() function called with converted parameters
Output Display: Formatted result printed directly to the console

Interactive Features

The magic command is designed for interactive workflows:

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

Install with Tessl CLI

npx tessl i tessl/pypi-watermark

docs