or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-wtfpython

Educational collection of surprising Python code snippets that demonstrate counter-intuitive behaviors and language internals

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/wtfpython@3.0.x

To install, run

npx @tessl/cli install tessl/pypi-wtfpython@3.0.0

index.mddocs/

wtfpython

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.

Package Information

  • Package Name: wtfpython
  • Package Type: PyPI
  • Language: Python
  • Installation: pip install wtfpython
  • Python Requirement: ^3.9

IMPORTANT: This package provides no importable API. It is purely an educational resource consisting of documentation and example code snippets.

Core Imports

No imports available - wtfpython cannot be imported as a module:

# This will NOT work:
import wtfpython  # ModuleNotFoundError
from wtfpython import anything  # ModuleNotFoundError

Basic Usage

wtfpython is designed to be:

  1. Read: Study the comprehensive README.md documentation
  2. Explored: Run individual Python example files
  3. Learned from: Understand the explanations of surprising behaviors

Accessing Content After Installation

# Install the package
pip install wtfpython

# Find installation location
python -c "import pkg_resources; print(pkg_resources.get_distribution('wtfpython').location)"

# Navigate to the installed package to read examples
# The main content is in README.md (125KB+ of examples and explanations)

Running Example Snippets

The package includes standalone Python files demonstrating specific behaviors:

# Run string behavior examples directly
python -c "
import pkg_resources
import os
import subprocess
pkg_path = pkg_resources.get_distribution('wtfpython').location
subprocess.run(['python', os.path.join(pkg_path, 'wtfpython', 'snippets', '2_tricky_strings.py')])
"

# Or navigate to package directory and run files
cd $(python -c "import pkg_resources; print(pkg_resources.get_distribution('wtfpython').location)")/wtfpython
python snippets/2_tricky_strings.py
python mixed_tabs_and_spaces.py

# Run validation tests using nox (if nox is installed)
nox -s tests
# Tests run across Python versions: 3.9, 3.10, 3.11, 3.12, 3.13

Architecture

wtfpython is structured as an educational content package:

  • README.md: Comprehensive collection of Python examples with explanations
  • Example files: Standalone Python scripts demonstrating specific behaviors
  • Educational structure: Content organized by behavior categories (string quirks, scoping issues, etc.)
  • Test framework: nox configuration for validating example code

The package serves as a reference guide for understanding Python's internal mechanics, object model, and interpreter behaviors that can surprise developers.

Capabilities

Educational Content Categories

The main educational content covers various Python behaviors and internals, organized into sections that demonstrate surprising or counter-intuitive language features.

# No programmatic API - content is accessed by reading files
# Key content areas include:
# - String interning and identity behaviors
# - Variable scoping and closure edge cases  
# - Boolean and comparison quirks
# - Mutable default arguments
# - Generator and iterator surprises
# - Class and inheritance behaviors
# - Numeric type behaviors
# - Exception handling edge cases

Content Access Pattern:

  • Install package to get local access to content files
  • Read README.md for comprehensive examples and explanations
  • Run individual .py files to see behaviors in action
  • Use as reference when encountering surprising Python behaviors

Example Code Execution

Standalone Python files that can be executed to demonstrate specific behaviors.

# Files available for execution:
# - snippets/2_tricky_strings.py: String identity and interning examples
# - mixed_tabs_and_spaces.py: Mixed indentation demonstration  
# - noxfile.py: Test runner configuration

# Executable functions available in package files:
def square(x):
    """
    Demonstrates mixed tab/space indentation issue in Python.
    Located in: mixed_tabs_and_spaces.py
    
    Args:
        x (int): Number to square
        
    Returns:
        int: Square of x (calculated via repeated addition)
        
    Note: This function intentionally contains mixed indentation
    that will raise TabError in Python 3
    """

@nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13"], reuse_venv=True)
def tests(session):
    """
    nox session for running wtfpython example validation.
    Located in: noxfile.py
    
    Args:
        session: nox session object
        
    Returns:
        None
        
    Runs:
        python snippets/2_tricky_strings.py
    """

Usage Pattern:

# After installation, find and execute example files
python path/to/wtfpython/snippets/2_tricky_strings.py

# Run mixed indentation demonstration
python path/to/wtfpython/mixed_tabs_and_spaces.py

# Run tests using nox
nox -s tests

Development and Utility Functions

Additional functions available in development/utility files (not part of main educational content):

def generate_random_id_comment():
    """
    Generate random UUID comment for README sections.
    Located in: irrelevant/insert_ids.py
    
    Returns:
        str: UUID comment string for HTML insertion
    """

# notebook_generator.py contains functions for:
# - Converting README.md to Jupyter notebook format
# - Processing example sections into notebook cells
# - Handling code extraction and formatting

# obsolete/parse_readme.py contains legacy functions for:
# - Parsing original README format
# - Categorizing examples
# - Reordering content structure

# obsolete/generate_contributions.py contains functions for:
# - Parsing contributor information from README
# - Generating CONTRIBUTORS.md table
# - Processing GitHub issue references

Package Structure

wtfpython/
├── README.md                    # Main educational content (125KB+ examples)
├── pyproject.toml              # Package metadata and dependencies
├── noxfile.py                  # Test configuration (nox sessions)
├── mixed_tabs_and_spaces.py    # Mixed indentation demonstration
├── snippets/
│   ├── __init__.py             # Empty file (no imports)
│   └── 2_tricky_strings.py     # String behavior examples
├── irrelevant/                 # Utility and development files
│   ├── insert_ids.py           # UUID insertion utility
│   ├── notebook_generator.py   # Jupyter notebook generator
│   └── obsolete/               # Legacy utilities
│       ├── parse_readme.py     # README parsing utility
│       └── generate_contributions.py # Contribution generator
├── images/                     # Logo and visual assets
├── translations/               # Multi-language versions
├── .github/                    # GitHub configuration
├── .gitignore                  # Git ignore rules
├── .markdownlint.yaml         # Markdown linting config
├── .pre-commit-config.yaml    # Pre-commit hooks
├── .travis.yml                # CI configuration
├── LICENSE                     # WTFPL 2.0 license
├── CONTRIBUTING.md             # Contribution guidelines
├── CONTRIBUTORS.md             # Contributor list
└── code-of-conduct.md         # Code of conduct

Educational Value

wtfpython serves as:

  • Learning tool: Understand Python's internal mechanisms
  • Reference guide: Quick lookup for explaining unexpected behaviors
  • Interview preparation: Familiarity with Python edge cases
  • Code review aid: Recognize patterns that might surprise other developers
  • Debugging assistant: Understand why certain Python code behaves unexpectedly

Dependencies

  • nox: ^2024.10.9 (for running example validation)
  • python: ^3.9

Important Notes

  • No API surface: Cannot be imported or used programmatically
  • Read-only content: Designed for study and reference, not integration
  • Educational focus: Prioritizes learning over practical utility
  • Version awareness: Content may vary between versions as new examples are added