Text Tools: A Minimal Python CLI for Email Extraction, Phone Detection, and Text Cleaning with 6 Simple Commands

Text Tools: Extract Emails and Phones with a Simple Python CLI

Sometimes you need to do basic text operations quickly: extract emails from logs, find phone patterns in documents, clean up messy whitespace, or count lines across files. Instead of wrestling with complex dependencies, I built text-tools — a minimal ~100-line Python CLI using only the standard library that handles these common tasks.

What It Does

The tool provides six subcommands for everyday text manipulation:

1. extract-emails — Finds all email addresses in input
2. extract-phones — Detects phone number patterns
3. remove-blank-lines — Strips empty lines from text
4. compress-spaces — Normalizes whitespace (optional paragraph blank handling)
5. count-files — Counts lines/words across multiple files
6. truncate-lines — Shortens long lines with a suffix like [...]

All commands support file arguments or stdin, enabling Unix-style piping:

cat article.txt | python text_tools.py extract-emails

Why Build This?

I needed lightweight utilities for processing copy-paste dumps, logs, and documents without installing pandas/pytest/spark. The existing regex-based tools often assume clean input; text-tools handles messy files directly (non-UTF8 chars get ignored). By keeping it minimal — no third-party dependencies beyond Python itself — you can drop the script into any directory and use it immediately.

Installation

# Simple copy
cp ~/projects/text-tools/text_tools.py ~/bin/
chmod +x ~/bin/text_tools.py

# Then any time:
python text_tools.py help

No pip install needed. Python 3.x is all that's required.

Usage Examples

Extract emails from a support ticket dump

cat tickets/january.txt | python text_tools.py extract-emails

Output:

Found 5 email(s):
[e-mail]
[e-mail]
[e-mail]
...

Find phone patterns in scraped data

Often documents contain phones as [phone], 123.456.7890, or just digits. The regex handles all common US formats:

python text_tools.py extract-phones -f docs/legal/* -q

Output (quiet mode, just phone patterns):

[phone]
[phone]
786-555-4321
...

Clean up a pasted config file

Pasted files often have inconsistent spacing or blank lines between sections:

python text_tools.py compress-spaces -f /tmp/scrapped.yaml -o cleaned.yaml

The -c flag replaces multiple spaces with single spaces. Paragraphs get one preserved blank line for readability.

Remove all blank lines from a log

Some logs have extra spacing between stack traces:

python text_tools.py remove-blank-lines -f server.log -o compact.log

This preserves non-empty content while stripping blanks, making diffs clearer.

Count lines across multiple project files

python text_tools.py count-files -F project/*/*.log --summary

Output example:

/app/debug.log: 1523 lines, 8920 words (45K chars)
/app/error.log: 876 lines, 4512 words (32K chars)

Summary:
  Total across 2 logs: 2400 lines, 13K+ words

Truncate long lines for terminal wrapping

When output contains extremely long entries (timestamps with full paths, JSON with massive fields), terminal wrapping becomes unreadable. Truncate-line solves this cleanly:

python text_tools.py truncate-lines -l 80 < wide_file.txt > narrow.txt --suf "[...]"

Lines over 80 characters get cut and suffixed; everything else passes through intact. Useful for creating portable diffs or pastes that wrap cleanly in editors.

Implementation Notes

The tool's code is deliberately simple:

• Regex patterns: Pre-tested against sample emails/phones from real-world text
• No external deps: re, sys, argparse only — runs everywhere Python exists
• Error handling: Invalid characters when reading files are caught and skipped; broken files show warnings to stderr

The email extractor uses:

r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'

This catches [e-mail] while avoiding false positives on domains with TLDs under two letters.

The phone matcher tries multiple patterns progressively to avoid missing non-standard formats:

r'[\(]?\d{3}[\)]?[-.\s]?\d{3}[-.\s]?\d{4}'

The blank-line remover strips all empties by default, adding one back at the end for readability — mimicking how many editors handle paste input.

Where to Use It

• Quick extraction of contact info from pasted text
• Pre-processing files before diffing or version control review
• Testing email validation without writing full form tools
• Cleaning up scraped web data before analysis
• Normalizing multiline logs extracted from systems

The Code Repo

The complete source lives at:

https://github.com/Poolion/text-tools

If you find this useful, you can support development: https://www.buymeacoffee.com/poolion