Global rules for shell command generation and Python package management to prevent common disruptive issues

02-shell-python-best-practices.mdc

---
alwaysApply: true
description: "Global rules for shell command generation and Python package management to prevent common disruptive issues"
---

# $HOME/.cursor/rules/02-shell-python-best-practices.mdc

# Shell and Python Best Practices

This rule file prevents common issues that cause shells to hang or break system Python installations.

## SHELL COMMAND GENERATION

### CRITICAL: Avoid Exclamation Points in Double-Quoted Strings

**NEVER** use exclamation points (`!`) inside double-quoted strings in shell commands.

**Why this matters:**
- In zsh, `!` inside double quotes triggers history expansion
- The sequence `!"` causes zsh to think there's an unterminated quote
- This causes the shell to wait for more input, showing `dquote>` prompt
- Users must manually type `"` to continue, breaking automation
- This is extremely disruptive and problematic for automated workflows

**Examples:**

Bad (causes `dquote>` prompt in zsh):
```bash
echo "Fixed CLIENT_DOMAIN redirect issue!"
echo "✅ All tests passed!"
echo "Success! All tests passed!"
echo --message="foo!"
```

Good (works in all shells):
```bash
echo "Fixed CLIENT_DOMAIN redirect issue"
echo "Fixed CLIENT_DOMAIN redirect issue."
echo 'Fixed CLIENT_DOMAIN redirect issue!'
echo "✅ All tests passed"
printf '%s\n' "Fixed CLIENT_DOMAIN redirect issue!"
echo --message="foo"
echo --message='foo!'
```

**Best practices:**
- Prefer single quotes for literal strings with special characters
- Use `printf '%s\n' "..."` for complex strings that need double quotes
- Keep echo messages professional without unnecessary punctuation
- Avoid emoji + exclamation combinations like `"✅ Done!"`
- When you must use `!`, use single quotes: `echo 'Done!'`

### Additional Shell Pitfalls to Avoid

- Always quote variables: `"$VAR"` not `$VAR`
- Use `set -e` in scripts to exit on errors
- Use `set -u` to catch undefined variables
- Prefer `[[ ]]` over `[ ]` in bash/zsh for better safety

## PYTHON PACKAGE MANAGEMENT

### CRITICAL: Never Install Packages at System Level

**NEVER** use `pip install --break-system-packages` or install Python packages at the system level.

**Why this matters:**
- System-level installations can break system Python
- Package conflicts with system tools
- Difficult to manage dependencies
- Can cause permission issues
- Makes environments non-reproducible

**Always use virtual environments or `uv`:**

### Preferred: Use `uv` (Fastest and Most Reliable)

`uv` is the preferred tool for Python package management. It automatically handles virtual environments and is much faster than pip.

**Creating environments:**
```bash
# Create a virtual environment
uv venv

# Or specify Python version
uv venv --python=3.11

# Or specify location
uv venv .venv
```

**Installing packages:**
```bash
# Use uv pip install (recommended)
uv pip install package-name

# Or use uv add (for project dependencies)
uv add package-name

# Install from requirements file
uv pip install -r requirements.txt
```

**Running scripts:**
```bash
# Run script in isolated environment
uv run script.py

# Run command in environment
uv run python -m pytest
```

**Synchronizing dependencies:**
```bash
# Sync from pyproject.toml or requirements.txt
uv sync
```

### Alternative: Use Standard `venv`

If `uv` is not available, use standard Python `venv`:

**Creating environments:**
```bash
# Create virtual environment
python3 -m venv .venv

# Or specify Python version
python3.11 -m venv .venv
```

**Activating and using:**
```bash
# Activate (bash/zsh)
source .venv/bin/activate

# Then install packages
pip install package-name

# Deactivate when done
deactivate
```

**Examples:**

Bad (system-level installation):
```bash
pip install package-name
pip install --break-system-packages package-name
sudo pip install package-name
pip install --user package-name  # Still problematic
```

Good (isolated environment):
```bash
# Using uv (preferred)
uv venv
uv pip install package-name

# Or using standard venv
python3 -m venv .venv
source .venv/bin/activate
pip install package-name
deactivate
```

### When Installing Dependencies for Scripts

**Always:**
1. Create a virtual environment first
2. Install packages in that environment
3. Run scripts using the environment

**Example workflow:**
```bash
# Create environment
uv venv

# Install dependencies
uv pip install requests pandas

# Run script
uv run python script.py
```

### GitHub Actions / CI Workflows

In CI/CD pipelines:
```yaml
- name: Install uv
  run: pip install uv

- name: Create environment & install deps
  run: |
    uv venv
    uv sync

- name: Run tests
  run: uv run pytest
```

## SUMMARY OF RULES

### Shell Commands
- ❌ Never: `echo "Done!"` (double quotes with `!`)
- ✅ Always: `echo "Done"` or `echo 'Done!'` (single quotes) or `printf '%s\n' "Done!"`

### Python Packages
- ❌ Never: `pip install package` (system level)
- ❌ Never: `pip install --break-system-packages package`
- ✅ Always: `uv pip install package` or `uv add package`
- ✅ Always: Use `uv venv` or `python3 -m venv .venv` first
- ✅ Always: Use `uv run script.py` for execution

## References

- zsh history expansion issue: https://github.com/ohmyzsh/ohmyzsh/issues/7557
- uv documentation: https://github.com/astral-sh/uv
- Python venv best practices: https://docs.python.org/3/library/venv.html