0
# wtfpython
1

2
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.
3

4
## Overview
5

6
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.
7

8
**Key Features:**
9
- Interactive terminal display of Python examples with explanations
10
- Multi-language translation support for global accessibility
11
- Markdown rendering with syntax highlighting for Python code
12
- Automatic update notifications to keep content current
13
- System pager integration for comfortable reading experience
14

15
## Package Information
16

17
- **Package Name**: wtfpython
18
- **Package Type**: npm
19
- **Language**: JavaScript (Node.js)
20
- **Installation**: `npm install -g wtfpython`
21

22
## Core Imports
23

24
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:
25

26
```bash
27
# Install globally to make wtfpython command available
28
npm install -g wtfpython
29

30
# No programmatic imports available - CLI usage only
31
# Not available: import * from 'wtfpython'
32
# Not available: const wtfpython = require('wtfpython')
33
```
34

35
## Core Usage
36

37
The package provides a single global command-line executable:
38

39
```bash
40
wtfpython [options]
41
```
42

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

45
## Basic Usage
46

47
```bash
48
# Display Python gotchas in default language (English)
49
wtfpython
50

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

54
# Display help information
55
wtfpython --help
56
```
57

58
## Capabilities
59

60
### Command Line Interface
61

62
The primary interface for accessing Python gotchas and examples.
63

64
```bash { .api }
65
wtfpython [options]
66

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

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

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

79
**Usage Examples:**
80

81
```bash
82
# Basic usage - displays content in system pager
83
wtfpython
84

85
# View available languages and help
86
wtfpython --help
87

88
# Display Portuguese translation
89
wtfpython --lang pt-br
90

91
# Display other supported languages (varies by available translations)
92
wtfpython -l es    # Spanish (if available)
93
wtfpython -l fr    # French (if available)
94
```
95

96
### Language Support
97

98
Multi-language translation support for Python examples and explanations.
99

100
```bash { .api }
101
--lang <language_code>
102
-l <language_code>
103

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

109
### Content Display Features
110

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

118
### Content Structure
119

120
The tool displays structured Python examples with consistent formatting:
121

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

128
### Error Handling
129

130
```bash { .api }
131
# Language not found
132
wtfpython --lang invalid-lang
133
# Output: "The invalid-lang translation does not exist"
134
# Exit code: Non-zero
135

136
# Missing content files
137
# If README.md or translation files are missing, the tool will exit with error
138
```
139

140
## Dependencies
141

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

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

152
## Environment Variables
153

154
```bash { .api }
155
PAGER    # System pager command (defaults to 'less' if not set)
156
LESS     # Less pager options (defaults to 'FRX' if not set)
157
```
158

159
## File Requirements
160

161
The tool requires the following files in its installation directory:
162

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

167
## Installation and Global Usage
168

169
```bash
170
# Install globally for command-line access
171
npm install -g wtfpython
172

173
# Verify installation
174
wtfpython --help
175

176
# Use from anywhere in terminal
177
cd /any/directory
178
wtfpython
179
```