wtfpython

wtfpython is a command-line tool that displays a collection of interesting, subtle, and tricky Python examples to help developers understand Python's unexpected behaviors and internals. It provides an educational resource for learning about Python language quirks, interpreter optimizations, and common pitfalls through an interactive terminal interface.

Overview

wtfpython provides a curated collection of Python gotchas and unexpected behaviors designed to help developers understand Python's internals. The tool displays educational content about Python language quirks, interpreter optimizations, and common pitfalls through a paginated terminal interface with syntax highlighting and multi-language support.

Key Features:

• Interactive terminal display of Python examples with explanations
• Multi-language translation support for global accessibility
• Markdown rendering with syntax highlighting for Python code
• Automatic update notifications to keep content current
• System pager integration for comfortable reading experience

Package Information

• Package Name: wtfpython
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install -g wtfpython

Core Imports

This package provides a command-line executable only and does not expose any programmatic API for import. It is designed exclusively as a global command-line tool:

# Install globally to make wtfpython command available
npm install -g wtfpython

# No programmatic imports available - CLI usage only
# Not available: import * from 'wtfpython'
# Not available: const wtfpython = require('wtfpython')

Core Usage

The package provides a single global command-line executable:

wtfpython [options]

No programmatic API is available - this package is designed exclusively as a command-line tool.

Basic Usage

# Display Python gotchas in default language (English)
wtfpython

# Display in Portuguese (Brazil)
wtfpython --lang pt-br

# Display help information
wtfpython --help

Capabilities

Command Line Interface

The primary interface for accessing Python gotchas and examples.

wtfpython [options]

Options:
  --lang, -l <language>  Specify translation language code
  --help, -h            Display help information

Exit Codes:
  0                     Successful execution and content display
  Non-zero              Error (file not found, invalid language, etc.)

Note: The built-in help text displays "bash-handbook" instead of "wtfpython" 
in usage examples due to the source code being based on a bash-handbook template.

Usage Examples:

# Basic usage - displays content in system pager
wtfpython

# View available languages and help
wtfpython --help

# Display Portuguese translation
wtfpython --lang pt-br

# Display other supported languages (varies by available translations)
wtfpython -l es    # Spanish (if available)
wtfpython -l fr    # French (if available)

Language Support

Multi-language translation support for Python examples and explanations.

--lang <language_code>
-l <language_code>

Supported format: ISO language codes (e.g., pt-br, es, fr)
Translation files: README-{lang}.md format
Fallback: English (README.md) if translation not found

Content Display Features

• Markdown Rendering: Converts markdown content to formatted terminal output using msee
• Syntax Highlighting: Python code examples with proper syntax highlighting
• Pager Integration: Uses system pager (less/more) for comfortable reading
• Terminal Styling: Colored output and formatting using chalk for better readability
• Update Notifications: Automatic checking for newer package versions
• Responsive Display: Adapts to terminal width and capabilities

Content Structure

The tool displays structured Python examples with consistent formatting:

• Example Title: Clear, descriptive heading for each Python gotcha
• Code Snippets: Python code demonstrating unexpected behavior
• Output Sections: Expected vs actual output with version information
• Explanations: Detailed explanations of why the behavior occurs
• Additional Examples: Related code samples for clarification

Error Handling

# Language not found
wtfpython --lang invalid-lang
# Output: "The invalid-lang translation does not exist"
# Exit code: Non-zero

# Missing content files
# If README.md or translation files are missing, the tool will exit with error

Dependencies

The package uses the following Node.js dependencies for functionality:

• boxen: Creates bordered boxes for update notifications
• chalk: Provides terminal string styling and colors
• default-pager: Integrates with system pager for content display
• meow: Handles command-line argument parsing
• msee: Parses and renders markdown content for terminal display
• through2: Provides stream transformation capabilities
• update-notifier: Checks for and displays package update notifications

Environment Variables

PAGER    # System pager command (defaults to 'less' if not set)
LESS     # Less pager options (defaults to 'FRX' if not set)

File Requirements

The tool requires the following files in its installation directory:

• README.md: Main content file with Python examples (English)
• README-{lang}.md: Translation files for other languages (optional)
• package.json: Package metadata for version checking and updates

Installation and Global Usage

# Install globally for command-line access
npm install -g wtfpython

# Verify installation
wtfpython --help

# Use from anywhere in terminal
cd /any/directory
wtfpython