python

Use Python for practical project setup, dependency install, script execution, and environment troubleshooting with safe defaults. Use when tasks involve pypr...

Use this skill to keep Python workflows reproducible and low-risk across local/dev shells.

Safety Defaults

• Prefer project-local virtual environments (.venv) over global installs.
• Prefer python3 -m pip ... to avoid interpreter and pip mismatch.
• Inspect dependency files before install (requirements*.txt, pyproject.toml).
• Avoid executing unknown setup hooks or random install scripts without user approval.

Standard Workflow

1. Detect current environment:

python3 --version
python3 -c "import sys; print(sys.executable)"
{baseDir}/scripts/python_env_tool.py doctor

2. Create or refresh a venv:

{baseDir}/scripts/python_env_tool.py bootstrap --venv .venv --requirements requirements.txt

3. Install project package (if pyproject.toml exists):

{baseDir}/scripts/python_env_tool.py install --venv .venv --editable

4. Run tests/tools from the venv interpreter:

.venv/bin/python -m pytest -q
.venv/bin/python -m pip list --outdated

Task Recipes

# Install specific packages into venv
{baseDir}/scripts/python_env_tool.py install --venv .venv --package requests --package pydantic

# Install from requirements file
{baseDir}/scripts/python_env_tool.py install --venv .venv --requirements requirements-dev.txt

# Recreate corrupted venv from scratch
{baseDir}/scripts/python_env_tool.py bootstrap --venv .venv --recreate --requirements requirements.txt

Troubleshooting Rules

• ModuleNotFoundError: verify command is run via .venv/bin/python, then reinstall deps.
• externally-managed-environment: stop global install attempts; use venv.
• Build failures on native deps: upgrade pip setuptools wheel, then retry.
• Multiple Python versions: always print and confirm sys.executable before fixes.

Bundled Helper

Use the helper for repeatable environment setup and diagnosis:

{baseDir}/scripts/python_env_tool.py --help
{baseDir}/scripts/python_env_tool.py doctor