Shellingham

Shellingham is a small, dependency-free Python library that inspects the process tree to figure out which shell launched the current Python interpreter. It returns a simple tuple of the shell’s name and the command used to invoke it, working across POSIX systems (via /proc or the ps command) and Windows (via the parent process name).

The library is best known as the shell-detection engine behind pip and Typer/Click-based CLIs that offer shell-completion installation, letting a tool automatically figure out whether to write a bash, zsh, fish, or PowerShell completion script without asking the user.

What You Get

• A single detect_shell() function returning a (name, command) tuple
• POSIX detection via /proc process trees with a ps-based fallback when /proc is unavailable
• Windows detection via parent process executable name
• A dedicated ShellDetectionFailure exception for graceful fallback handling
• Zero runtime dependencies and a tiny (~450 line) codebase

Common Use Cases

• Auto-installing shell completion scripts in CLI tools built with Click or Typer
• Selecting the correct shell syntax when a tool needs to print an eval-able activation command (similar to how pipenv and pyenv wrappers behave)
• Any command-line application that needs to branch behavior based on the user’s interactive shell
• Falling back gracefully to a POSIX $SHELL or Windows %COMSPEC% default when detection fails

Under The Hood

Architecture The package splits detection into an internal _core.py dispatcher that picks between posix and nt (Windows) implementations at import time based on os.name; the POSIX path (posix/__init__.py, proc.py, ps.py) walks /proc/<pid>/stat parent links when available and falls back to shelling out to ps for BSD/macOS-style systems without /proc, while nt.py walks the Windows process tree via ctypes calls to find the parent executable name.

Tech Stack Pure Python (100%), zero runtime dependencies, packaged via classic setup.py/setup.cfg with a src/ layout; uses Pipenv for development and towncrier for changelog generation, targeting Python 3.7+.

Code Quality The codebase is intentionally minimal (roughly 450 lines total) and readable, with a single POSIX test module (tests/test_posix.py) covering the process-walking logic; there is no Windows-specific test coverage in the repository, and comments are sparse but the code’s small surface area keeps it easy to audit.

API Design The public API is deliberately tiny — one function (detect_shell) and one exception class — making adoption a one-line integration; the try/except pattern recommended in the README for handling ShellDetectionFailure is idiomatic and low-friction for CLI authors.