0
# wtfpython
1
2
An educational collection of surprising Python code snippets that demonstrate counter-intuitive behaviors and language internals. wtfpython helps developers understand Python's quirks, edge cases, and the reasons behind unexpected behaviors through carefully curated examples with detailed explanations.
3
4
## Package Information
5
6
- **Package Name**: wtfpython
7
- **Package Type**: PyPI
8
- **Language**: Python
9
- **Installation**: `pip install wtfpython`
10
- **Python Requirement**: ^3.9
11
12
**IMPORTANT**: This package provides **no importable API**. It is purely an educational resource consisting of documentation and example code snippets.
13
14
## Core Imports
15
16
**No imports available** - wtfpython cannot be imported as a module:
17
18
```python
19
# This will NOT work:
20
import wtfpython # ModuleNotFoundError
21
from wtfpython import anything # ModuleNotFoundError
22
```
23
24
## Basic Usage
25
26
wtfpython is designed to be:
27
28
1. **Read**: Study the comprehensive README.md documentation
29
2. **Explored**: Run individual Python example files
30
3. **Learned from**: Understand the explanations of surprising behaviors
31
32
### Accessing Content After Installation
33
34
```bash
35
# Install the package
36
pip install wtfpython
37
38
# Find installation location
39
python -c "import pkg_resources; print(pkg_resources.get_distribution('wtfpython').location)"
40
41
# Navigate to the installed package to read examples
42
# The main content is in README.md (125KB+ of examples and explanations)
43
```
44
45
### Running Example Snippets
46
47
The package includes standalone Python files demonstrating specific behaviors:
48
49
```bash
50
# Run string behavior examples directly
51
python -c "
52
import pkg_resources
53
import os
54
import subprocess
55
pkg_path = pkg_resources.get_distribution('wtfpython').location
56
subprocess.run(['python', os.path.join(pkg_path, 'wtfpython', 'snippets', '2_tricky_strings.py')])
57
"
58
59
# Or navigate to package directory and run files
60
cd $(python -c "import pkg_resources; print(pkg_resources.get_distribution('wtfpython').location)")/wtfpython
61
python snippets/2_tricky_strings.py
62
python mixed_tabs_and_spaces.py
63
64
# Run validation tests using nox (if nox is installed)
65
nox -s tests
66
# Tests run across Python versions: 3.9, 3.10, 3.11, 3.12, 3.13
67
```
68
69
## Architecture
70
71
wtfpython is structured as an educational content package:
72
73
- **README.md**: Comprehensive collection of Python examples with explanations
74
- **Example files**: Standalone Python scripts demonstrating specific behaviors
75
- **Educational structure**: Content organized by behavior categories (string quirks, scoping issues, etc.)
76
- **Test framework**: nox configuration for validating example code
77
78
The package serves as a reference guide for understanding Python's internal mechanics, object model, and interpreter behaviors that can surprise developers.
79
80
## Capabilities
81
82
### Educational Content Categories
83
84
The main educational content covers various Python behaviors and internals, organized into sections that demonstrate surprising or counter-intuitive language features.
85
86
```python { .api }
87
# No programmatic API - content is accessed by reading files
88
# Key content areas include:
89
# - String interning and identity behaviors
90
# - Variable scoping and closure edge cases
91
# - Boolean and comparison quirks
92
# - Mutable default arguments
93
# - Generator and iterator surprises
94
# - Class and inheritance behaviors
95
# - Numeric type behaviors
96
# - Exception handling edge cases
97
```
98
99
**Content Access Pattern**:
100
- Install package to get local access to content files
101
- Read README.md for comprehensive examples and explanations
102
- Run individual .py files to see behaviors in action
103
- Use as reference when encountering surprising Python behaviors
104
105
### Example Code Execution
106
107
Standalone Python files that can be executed to demonstrate specific behaviors.
108
109
```python { .api }
110
# Files available for execution:
111
# - snippets/2_tricky_strings.py: String identity and interning examples
112
# - mixed_tabs_and_spaces.py: Mixed indentation demonstration
113
# - noxfile.py: Test runner configuration
114
115
# Executable functions available in package files:
116
def square(x):
117
"""
118
Demonstrates mixed tab/space indentation issue in Python.
119
Located in: mixed_tabs_and_spaces.py
120
121
Args:
122
x (int): Number to square
123
124
Returns:
125
int: Square of x (calculated via repeated addition)
126
127
Note: This function intentionally contains mixed indentation
128
that will raise TabError in Python 3
129
"""
130
131
@nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13"], reuse_venv=True)
132
def tests(session):
133
"""
134
nox session for running wtfpython example validation.
135
Located in: noxfile.py
136
137
Args:
138
session: nox session object
139
140
Returns:
141
None
142
143
Runs:
144
python snippets/2_tricky_strings.py
145
"""
146
```
147
148
**Usage Pattern**:
149
```bash
150
# After installation, find and execute example files
151
python path/to/wtfpython/snippets/2_tricky_strings.py
152
153
# Run mixed indentation demonstration
154
python path/to/wtfpython/mixed_tabs_and_spaces.py
155
156
# Run tests using nox
157
nox -s tests
158
```
159
160
### Development and Utility Functions
161
162
Additional functions available in development/utility files (not part of main educational content):
163
164
```python { .api }
165
def generate_random_id_comment():
166
"""
167
Generate random UUID comment for README sections.
168
Located in: irrelevant/insert_ids.py
169
170
Returns:
171
str: UUID comment string for HTML insertion
172
"""
173
174
# notebook_generator.py contains functions for:
175
# - Converting README.md to Jupyter notebook format
176
# - Processing example sections into notebook cells
177
# - Handling code extraction and formatting
178
179
# obsolete/parse_readme.py contains legacy functions for:
180
# - Parsing original README format
181
# - Categorizing examples
182
# - Reordering content structure
183
184
# obsolete/generate_contributions.py contains functions for:
185
# - Parsing contributor information from README
186
# - Generating CONTRIBUTORS.md table
187
# - Processing GitHub issue references
188
```
189
190
## Package Structure
191
192
```
193
wtfpython/
194
├── README.md # Main educational content (125KB+ examples)
195
├── pyproject.toml # Package metadata and dependencies
196
├── noxfile.py # Test configuration (nox sessions)
197
├── mixed_tabs_and_spaces.py # Mixed indentation demonstration
198
├── snippets/
199
│ ├── __init__.py # Empty file (no imports)
200
│ └── 2_tricky_strings.py # String behavior examples
201
├── irrelevant/ # Utility and development files
202
│ ├── insert_ids.py # UUID insertion utility
203
│ ├── notebook_generator.py # Jupyter notebook generator
204
│ └── obsolete/ # Legacy utilities
205
│ ├── parse_readme.py # README parsing utility
206
│ └── generate_contributions.py # Contribution generator
207
├── images/ # Logo and visual assets
208
├── translations/ # Multi-language versions
209
├── .github/ # GitHub configuration
210
├── .gitignore # Git ignore rules
211
├── .markdownlint.yaml # Markdown linting config
212
├── .pre-commit-config.yaml # Pre-commit hooks
213
├── .travis.yml # CI configuration
214
├── LICENSE # WTFPL 2.0 license
215
├── CONTRIBUTING.md # Contribution guidelines
216
├── CONTRIBUTORS.md # Contributor list
217
└── code-of-conduct.md # Code of conduct
218
```
219
220
## Educational Value
221
222
wtfpython serves as:
223
224
- **Learning tool**: Understand Python's internal mechanisms
225
- **Reference guide**: Quick lookup for explaining unexpected behaviors
226
- **Interview preparation**: Familiarity with Python edge cases
227
- **Code review aid**: Recognize patterns that might surprise other developers
228
- **Debugging assistant**: Understand why certain Python code behaves unexpectedly
229
230
## Dependencies
231
232
- **nox**: ^2024.10.9 (for running example validation)
233
- **python**: ^3.9
234
235
## Important Notes
236
237
- **No API surface**: Cannot be imported or used programmatically
238
- **Read-only content**: Designed for study and reference, not integration
239
- **Educational focus**: Prioritizes learning over practical utility
240
- **Version awareness**: Content may vary between versions as new examples are added