python-environment

sunxd3's avatarfrom sunxd3

Python environment setup with uv, shared utilities, and script structure guidelines.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026

When & Why to Use This Skill

This Claude skill optimizes Python development workflows by implementing a standardized environment setup powered by 'uv'. It solves the common 'dependency hell' and environment inconsistency issues by enforcing the use of 'uv run' and pyproject.toml. Additionally, it provides a blueprint for modular script architecture and shared utility integration, ensuring that Python projects remain scalable, reproducible, and easy to maintain.

Use Cases

  • Standardizing Python environments: Ensuring all team members and AI agents use identical virtual environments and dependencies via 'uv' to prevent execution errors.
  • Modular Script Organization: Breaking down monolithic Python files into small, focused scripts (e.g., separate files for fitting, diagnostics, and plotting) for better maintainability.
  • Shared Utility Integration: Centralizing common logic into a shared-utils package to reduce code duplication and ensure consistent API usage across multiple experiment scripts.
  • Automated Workflow Execution: Using 'uv run' to automatically handle environment activation and script execution from the project root, simplifying CI/CD and local development.
namepython-environment
descriptionPython environment setup with uv, shared utilities, and script structure guidelines.

Python Environment

Always use uv run. Never search for Python or use venv directly.

uv run uses the venv from the nearest pyproject.toml up the directory tree. Run scripts from the project root:

cd /path/to/project  # directory with pyproject.toml
uv run python experiments/experiment_X/fit/run_fit.py

Shared Utilities

shared-utils is a project dependency. Import directly:

from shared_utils import compile_model, fit_model, check_convergence, ...

Read the package source at /workspace/shared_utils/ for API details.

Script Structure

Write small, focused scripts - not monolithic files. Separate concerns:

experiment_X/
  fit/
    run_fit.py        # Main entry point
    diagnostics.py    # Convergence checks
    plots.py          # Visualization

Each script should:

  • Do one thing well
  • Be runnable independently via uv run python script.py
  • Import shared logic from shared_utils