or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-titlecase

Python port of John Gruber's titlecase.pl for intelligent title case conversion with style guide compliance

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/titlecase@2.4.x

To install, run

npx @tessl/cli install tessl/pypi-titlecase@2.4.0

index.mddocs/

Titlecase

A Python port of John Gruber's titlecase.pl that converts text to proper title case according to English style guides. The library applies intelligent capitalization rules, handling small words (a, an, the, etc.) based on the New York Times Manual of Style while preserving abbreviations, acronyms, and mixed-case words.

Package Information

  • Package Name: titlecase
  • Language: Python
  • Installation: pip install titlecase
  • Python Version: >=3.7
  • Optional Dependencies: regex (enhanced regex support, fallback to re)

Core Imports

from titlecase import titlecase

Alternative import pattern:

import titlecase

# Then use: titlecase.titlecase()

Basic Usage

from titlecase import titlecase

# Basic title casing
result = titlecase('this is a simple test')
print(result)  # "This Is a Simple Test"

# Handles all-caps input
result = titlecase('THIS IS ALL CAPS')
print(result)  # "This Is All Caps"

# Preserves mixed case when appropriate
result = titlecase('this is a TEST')
print(result)  # "This Is a TEST"

# Handles punctuation and contractions
result = titlecase("Q&A with steve jobs: 'that's what happens'")
print(result)  # "Q&A With Steve Jobs: 'That's What Happens'"

Capabilities

Primary Text Processing

The main titlecase function for converting text to proper title case with intelligent handling of small words, abbreviations, and special cases.

def titlecase(text, callback=None, small_first_last=True, preserve_blank_lines=False):
    """
    Convert text to title case with intelligent capitalization rules.
    
    Parameters:
    - text (str): Input text to convert to title case
    - callback (function, optional): Custom callback function for word-specific handling
    - small_first_last (bool, default=True): Whether to capitalize small words at beginning/end
    - preserve_blank_lines (bool, default=False): Whether to preserve blank lines in input
    
    Returns:
    str: Title-cased version of input text
    """

Configuration Functions

Functions for customizing titlecase behavior by modifying small word patterns and creating callback filters.

def set_small_word_list(small=SMALL):
    """
    Configure the list of small words that should not be capitalized.
    
    Parameters:
    - small (str, optional): Regex pattern of small words (defaults to built-in SMALL pattern)
    
    Returns:
    None (modifies global regex patterns)
    """

def create_wordlist_filter_from_file(file_path):
    """
    Create a callback function from a file containing abbreviations to preserve.
    
    Parameters:
    - file_path (str): Path to file containing abbreviations (one per line)
    
    Returns:
    function: Callback function for use with titlecase()
    """

Command Line Interface

Command-line utility for processing text files or command arguments.

def cmd():
    """
    Handler for command-line invocation of titlecase utility.
    
    Command-line options:
    - Positional: string arguments to titlecase
    - -f, --input-file: Input file path (or '-' for stdin)
    - -o, --output-file: Output file path (or '-' for stdout)
    - -w, --wordlist: Path to wordlist file for acronyms
    - --preserve-blank-lines: Flag to preserve blank lines
    
    Entry point: 'titlecase' console script
    """

Advanced Usage

Custom Callback Functions

from titlecase import titlecase

def tech_acronyms(word, **kwargs):
    """Custom callback to preserve technical acronyms"""
    acronyms = {'TCP', 'UDP', 'HTTP', 'API', 'JSON', 'XML'}
    if word.upper() in acronyms:
        return word.upper()
    return None  # Let titlecase handle normally

result = titlecase('a simple tcp and json api', callback=tech_acronyms)
print(result)  # "A Simple TCP and JSON API"

Wordlist File Processing

from titlecase import titlecase, create_wordlist_filter_from_file

# Create callback from wordlist file
# File contains: TCP\nUDP\nAPI\nJSON (one per line)
wordlist_filter = create_wordlist_filter_from_file('~/.titlecase.txt')

result = titlecase('working with tcp and json apis', callback=wordlist_filter)
print(result)  # "Working With TCP and JSON APIs"

Global Configuration

from titlecase import titlecase, set_small_word_list

# Customize small words (example: remove "and" from small words)
custom_small = r'a|an|as|at|but|by|en|for|if|in|of|on|or|the|to|v\.?|via|vs\.?'
set_small_word_list(custom_small)

result = titlecase('jack and jill')
print(result)  # "Jack And Jill" (now "and" gets capitalized)

Types and Constants

# Version information
__version__: str = '2.4.1'

# Base class for immutable types
class Immutable:
    """Base class for types that should remain unchanged during titlecase processing"""

# Immutable string classes for callback return values
class ImmutableString(str, Immutable):
    """String subclass that marks content as unchanged by titlecase processing"""

class ImmutableBytes(bytes, Immutable):
    """Bytes subclass that marks content as unchanged by titlecase processing"""

# Built-in constants for small words and patterns
SMALL: str = r'a|an|and|as|at|but|by|en|for|if|in|of|on|or|the|to|v\.?|via|vs\.?'  # Default small words pattern
PUNCT: str = r"""!""#$%&''()*+,\-–‒—―./:;?@[\\\]_`{|}~"""  # Punctuation characters pattern

Key Features

  • Intelligent Small Word Handling: Automatically handles articles, prepositions, and conjunctions according to style guides
  • Abbreviation Detection: Preserves existing capitalization for abbreviations and acronyms
  • Mac/Mc Name Support: Proper handling of Scottish and Irish surnames (MacDonald, McPherson)
  • Hyphenated Word Processing: Correctly handles compound words connected by hyphens
  • Slash-Separated Processing: Handles alternatives and paths (word/word)
  • Unicode Support: Works with international characters when regex module is available
  • Customizable via Callbacks: Extensible through user-defined word processing functions
  • Command-Line Utility: Full-featured CLI with file I/O and wordlist support
  • Contraction Handling: Proper capitalization of contractions and possessives

Error Handling

The library handles various edge cases gracefully:

  • Empty strings return empty strings
  • Invalid file paths in create_wordlist_filter_from_file() return a no-op callback
  • Missing regex module falls back to standard re module with reduced Unicode support
  • Invalid callback functions that return non-string values are ignored

Installation Options

# Standard installation
pip install titlecase

# With enhanced regex support
pip install titlecase[regex]

The regex extra provides enhanced Unicode support and additional pattern matching capabilities compared to the standard re module.