Skip to content

CLI.md

Latest commit

 

History

History
292 lines (201 loc) · 5.91 KB

CLI.md

File metadata and controls

292 lines (201 loc) · 5.91 KB

CLI Guide

The quotes-convert CLI provides a convenient way to convert quotes in files and streams directly from your terminal.

Installation

The CLI requires the typer dependency, which is installed as an optional extra:

pip install quotes-convert[cli]

Quick Start

# Convert to single quotes
echo 'x = "hello"' | quotes-convert --single

# Convert to double quotes
echo "x = 'hello'" | quotes-convert --double

# Use short flags
quotes-convert -s file.py
quotes-convert -d file.py

# Check version
quotes-convert --version

Command Reference

quotes-convert [OPTIONS] [FILES]...

Options

Option Short Description
--single -s Convert matching quotes to single quotes
--double -d Convert matching quotes to double quotes
--in-place -i Edit files in place (requires file arguments)
--output PATH -o PATH Write output to specified file
--version -V Show version and exit
--help Show help message and exit

Arguments

Argument Description
FILES Files to convert. If not provided, reads from stdin.

Usage Patterns

1. Standard Input/Output (Pipes)

Process text from stdin and output to stdout:

# From echo
echo 'name = "Alice"' | quotes-convert -s
# Output: name = 'Alice'

# From file via cat
cat script.py | quotes-convert -s

# Chain with other commands
cat data.txt | quotes-convert -s | grep "pattern"

2. File to Standard Output

Preview changes before modifying files:

# Display converted content
quotes-convert -s myfile.py

# Check before applying
quotes-convert -s config.py | less

3. In-Place File Editing

Modify files directly:

# Single file
quotes-convert -s -i script.py

# Multiple files
quotes-convert -s -i file1.py file2.py file3.py

# Glob patterns (shell expansion)
quotes-convert -s -i src/*.py
quotes-convert -s -i *.py

Warning: In-place editing modifies files directly. Always use version control (git) or create backups before batch editing.

4. Output to File

Save converted content to a new file:

# From stdin
echo 'x = "test"' | quotes-convert -s -o output.py

# From file
quotes-convert -s input.py -o output.py

Real-World Examples

Python Code Formatting

# Convert Python files to use single quotes
quotes-convert -s -i src/*.py tests/*.py

# Preview changes first
quotes-convert -s main.py > /tmp/preview.py
diff main.py /tmp/preview.py

JavaScript/TypeScript Projects

# Convert to double quotes
quotes-convert -d -i src/*.ts src/*.js

Batch Processing with Find

# Convert all Python files in a directory tree
find . -name "*.py" -type f -exec quotes-convert -s -i {} \;

# With progress indicator
find . -name "*.py" -type f | while read f; do
    echo "Processing: $f"
    quotes-convert -s -i "$f"
done

Parallel Processing with xargs

# Process 4 files at a time in parallel
find . -name "*.py" | xargs -P 4 -n 1 quotes-convert -s -i

Integration with Git

# Convert only staged Python files
git diff --cached --name-only | grep '\.py$' | xargs quotes-convert -s -i

# Convert files changed in current branch vs main
git diff --name-only main | grep '\.py$' | xargs quotes-convert -s -i

Shell Aliases

Add to your ~/.bashrc or ~/.zshrc:

alias sq='quotes-convert --single'
alias dq='quotes-convert --double'
alias sqi='quotes-convert --single --in-place'
alias dqi='quotes-convert --double --in-place'

Usage:

sq file.py           # preview
sqi file.py          # in-place
echo 'x="y"' | sq    # pipe

Error Handling

The CLI provides clear error messages for common issues:

Missing Quote Style

$ quotes-convert file.py
Error: Must specify either --single or --double

Conflicting Options

$ quotes-convert -s -d file.py
Error: Cannot specify both --single and --double

$ quotes-convert -s -i -o output.py file.py
Error: Cannot specify both --in-place and --output

File Not Found

$ quotes-convert -s nonexistent.txt
Error: Invalid value for '[FILES]...': Path 'nonexistent.txt' does not exist.

Permission Denied

$ quotes-convert -s -i /root/protected.py
Error: Permission denied: /root/protected.py

Non-UTF-8 Files

$ quotes-convert -s binary.dat
Error: Cannot decode file (not UTF-8): binary.dat

Performance Tips

Streaming Mode

The CLI uses streaming by default when not editing in-place, efficiently handling large files:

# Efficiently handles large files
quotes-convert -s huge_file.txt > output.txt

Memory Usage

  • Streaming mode (default): Low memory, handles any file size
  • In-place mode (-i): Loads entire file into memory

Parallel Processing

For many files, use parallel processing:

# Process 4 files at a time
find . -name "*.py" | xargs -P 4 -n 1 quotes-convert -s -i

Troubleshooting

CLI Command Not Found

If quotes-convert command is not found:

# Ensure CLI extras are installed
pip install quotes-convert[cli]

# Verify installation
pip show quotes-convert

# Check if it's in PATH
which quotes-convert

# Alternative: run with python -m
python -m quotes_convert.cli --help

Import Errors

If you get "CLI dependencies not installed":

# Reinstall with CLI extras
pip install --force-reinstall quotes-convert[cli]

Unexpected Results

# Check version
quotes-convert --version

# Test with simple input
echo 'test = "value"' | quotes-convert -s

See Also