Title Fix

A Python package for intelligent title case conversion and text formatting. This package provides a comprehensive solution for converting text between different case styles while maintaining proper capitalization rules and offering additional text analysis features.

🌐 Live Demo

Try the web interface powered by this package: https://title-fix-app.onrender.com/

Experience all the features through a modern, responsive web application built with React and FastAPI. The web app provides:

• Real-time text conversion as you type
• All citation styles and case types
• Copy-to-clipboard functionality
• Text statistics and headline scoring
• Beautiful, user-friendly interface

Features

• Multiple case conversion options:

  • Title Case (follows standard style guidelines)
  • Sentence case
  • UPPERCASE
  • lowercase
  • First Letter Case
  • AlTeRnAtInG cAsE
  • tOGGLE cAsE

• Citation Style Support:

  • APA (American Psychological Association)
  • Chicago Manual of Style
  • AP (Associated Press)
  • MLA (Modern Language Association)
  • NYT (New York Times)

• Additional features:

  • Custom acronyms - Add your own acronyms (API, SDK, REST, etc.)
  • Preserve uppercase - Keep words that are already fully uppercase
  • Word and character count
  • Straight quotes conversion
  • Quick copy functionality
  • Headline scoring
  • Input validation and error handling

Installation

pip install title-fix

Usage

Basic Usage

from title_fix import title_fix

# Simple title case conversion (using default APA style)
result = title_fix("this is a test title")
print(result["text"])  # Output: "This Is a Test Title"

# Get word and character count
print(result["word_count"])  # Output: 5
print(result["char_count"])  # Output: 20

Citation Styles

# APA Style (default) - capitalizes words with 4+ letters
result = title_fix("the theory of relativity in physics", style="apa")
print(result["text"])  # Output: "The Theory of Relativity in Physics"

# Chicago Style - capitalizes all major words
result = title_fix("the theory of relativity in physics", style="chicago")
print(result["text"])  # Output: "The Theory of Relativity in Physics"

# AP Style - capitalizes words with 4+ letters
result = title_fix("the theory of relativity in physics", style="ap")
print(result["text"])  # Output: "The Theory of Relativity in Physics"

# MLA Style - capitalizes all principal words
result = title_fix("the theory of relativity in physics", style="mla")
print(result["text"])  # Output: "The Theory of Relativity in Physics"

# NYT Style - capitalizes words with 5+ letters
result = title_fix("the theory of relativity in physics", style="nyt")
print(result["text"])  # Output: "The Theory of Relativity in Physics"

Different Case Styles

# Sentence case
result = title_fix("THIS IS A TEST.", case_type="sentence")
print(result["text"])  # Output: "This is a test."

# UPPERCASE
result = title_fix("test text", case_type="upper")
print(result["text"])  # Output: "TEST TEXT"

# lowercase
result = title_fix("TEST TEXT", case_type="lower")
print(result["text"])  # Output: "test text"

# First Letter Case
result = title_fix("test text", case_type="first")
print(result["text"])  # Output: "Test Text"

# AlTeRnAtInG cAsE
result = title_fix("test text", case_type="alt")
print(result["text"])  # Output: "TeSt TeXt"

# tOGGLE cAsE
result = title_fix("Test Text", case_type="toggle")
print(result["text"])  # Output: "tEST tEXT"

Additional Features

# Convert curly quotes to straight quotes
result = title_fix("test with quotes", straight_quotes=True)
print(result["text"])  # Converts any curly quotes to straight quotes

# Get headline score (0-100 based on best practices)
result = title_fix("How to Write the Perfect Headline in 7 Steps")
print(result["headline_score"])  # Output: 75

# Get available options
from title_fix import get_supported_styles, get_supported_case_types
print(get_supported_styles())     # ['apa', 'chicago', 'ap', 'mla', 'nyt']
print(get_supported_case_types()) # ['title', 'sentence', 'upper', 'lower', 'first', 'alt', 'toggle']

Special Handling

The package intelligently handles various text elements:

# Roman numerals
result = title_fix("world war ii and chapter iv")
print(result["text"])  # Output: "World war II and Chapter IV"

# Acronyms
result = title_fix("nasa, fbi, and cia collaboration")
print(result["text"])  # Output: "NASA, FBI, and CIA Collaboration"

# Hyphenated words
result = title_fix("well-known state-of-the-art solution")
print(result["text"])  # Output: "Well-Known State-of-the-art Solution"

# Subtitles after colons
result = title_fix("main title: a subtitle here")
print(result["text"])  # Output: "Main Title: A Subtitle Here"

Custom Acronyms

You can now provide your own acronyms to be capitalized:

# Add custom acronyms like API, SDK, REST, etc.
result = title_fix("the api and sdk documentation", acronyms=["api", "sdk"])
print(result["text"])  # Output: "The API and SDK Documentation"

# Works with default acronyms too
result = title_fix("nasa api and fbi database", acronyms=["api", "database"])
print(result["text"])  # Output: "NASA API and FBI DATABASE"

# Handles acronyms with numbers
result = title_fix("using oauth2 authentication", acronyms=["oauth2"])
print(result["text"])  # Output: "Using OAUTH2 Authentication"

# Works with hyphenated acronyms
result = title_fix("jwt-based authentication", acronyms=["jwt"])
print(result["text"])  # Output: "JWT-Based Authentication"

Preserve Uppercase Words

Keep words that are already fully uppercase in your input:

# Preserve all-uppercase words from the input
result = title_fix("REST API with GRAPHQL backend", preserve_uppercase=True)
print(result["text"])  # Output: "REST API With GRAPHQL Backend"

# Works with mixed content
result = title_fix("Using JWT tokens with OAUTH2", preserve_uppercase=True)
print(result["text"])  # Output: "Using JWT Tokens With OAUTH2"

# Combine with custom acronyms for maximum flexibility
result = title_fix(
    "REST api and SDK integration",
    acronyms=["api", "sdk"],
    preserve_uppercase=True
)
print(result["text"])  # Output: "REST API and SDK Integration"

Citation Style Rules

Each citation style follows specific rules for capitalization:

APA Style

• Capitalize first word and first word after colons
• Capitalize all major words with 4+ letters
• Capitalize both parts of hyphenated major words
• Always capitalize: proper nouns, acronyms, and verbs

Chicago Style

• Capitalize first and last words
• Capitalize all major words regardless of length
• Lowercase articles (a, an, the), coordinating conjunctions, and prepositions
• Capitalize both parts of hyphenated words

AP Style

• Capitalize words with 4+ letters
• Capitalize first and last words
• Always capitalize: proper nouns, acronyms
• Special handling for AP-specific terms

MLA Style

• Capitalize first word and all principal words
• Capitalize verbs (including is, are, was, were)
• Lowercase articles, prepositions, and coordinating conjunctions
• Capitalize both parts of hyphenated major words

NYT Style

• Capitalize words with 5+ letters
• Always capitalize proper nouns and acronyms
• More conservative with capitalization of short words
• Capitalize first and last words

Headline Score

The headline score is calculated based on several factors:

• Optimal length (40-60 characters scores highest)
• Word count (6-10 words ideal)
• Use of power words (how, why, what, when, top, best, new, ultimate, complete, guide)
• Use of emotional words (amazing, incredible, shocking, secret, proven)
• Presence of numbers
• Overall structure and readability

A score of 100 indicates an optimal headline according to common best practices. Scores above 70 are generally considered good.

Error Handling

The package includes comprehensive input validation:

from title_fix import validate_input

# Validate parameters before processing
try:
    validate_input("test text", "title", "apa")  # Valid
    validate_input("test text", "invalid", "apa")  # Raises ValueError
except ValueError as e:
    print(f"Validation error: {e}")

API Reference

Main Function

title_fix(text, case_type="title", style="apa", straight_quotes=False, quick_copy=True, 
          acronyms=None, preserve_uppercase=False)

Parameters:

• text (str): Input text to process
• case_type (str): One of "title", "sentence", "upper", "lower", "first", "alt", "toggle"
• style (str): Citation style for title case - "apa", "chicago", "ap", "mla", "nyt"
• straight_quotes (bool): Convert curly quotes to straight quotes
• quick_copy (bool): Enable quick copy functionality
• acronyms (Iterable[str], optional): Custom acronyms to capitalize (e.g., ["api", "sdk", "rest"])
• preserve_uppercase (bool): Keep words that are already fully uppercase in the input

Returns:

• Dictionary with keys: text, word_count, char_count, headline_score, quick_copy, case_type, style

Utility Functions

• get_supported_styles(): Returns list of supported citation styles
• get_supported_case_types(): Returns list of supported case types
• validate_input(text, case_type, style): Validates input parameters

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.