py_executer 0.1.2

A Rust-based command-line tool to execute Python scripts with automatic virtual environment and dependency management.
Documentation

py_executer

A Rust-based command-line tool to execute Python scripts with automatic virtual environment and dependency management. py_executer streamlines running Python code by handling environment setup, dependency installation, and environment variables, making your workflow faster and more reliable.

Features

  • Automatic Virtual Environment Management: Manage a Python virtual environment using uv.
  • Dependency Installation: Installs dependencies from requirements.txt automatically.
  • .env File Support: Loads environment variables from a .env file or from CLI.
  • Setup PYTHONVENV: Automatically set python path based on the path where the CLI is executed.
  • Custom Environment Variables: Pass additional environment variables via CLI.
  • Flexible Python Arguments: Pass extra arguments to the Python script.
  • Clean Mode: Clean the created uv-managed .venv and config files after execution, sensorless to execute a python script.
  • Cross-platform: Works on Unix-like systems and Windows.

Installation

  1. Install Rust and Cargo.
  2. Clone this repository: 
    git clone https://github.com/guangyu-he/py_executer
cd py_executer
  3. Build the project: 
    cargo build --release
  4. Or simply install the binary:
    cargo install --path .
  1. (Optional) Install uv if not already present. The tool will give a hint to install it if uv is essential to be called.

Usage

py_executer <SCRIPT_PATH> [OPTIONS]

Arguments

  • <SCRIPT_PATH>: Path to the Python script to execute.

Options

  • -v, --venv <VENV_PATH>: Specify a custom virtual environment path (default: .venv or venv). If a valid venv is present, this venv will be used directly (not managed by uv), requirements.txt will not be installed, and clean mode will be ignored.
  • -E, --env <KEY=VALUE>: Additional environment variables in the format KEY=VALUE. Can be used multiple times.
  • -e, --env-file <ENV_FILE>: Path to a .env file (default: .env in the current directory).
  • --quiet: Suppress output from the CLI.
  • --clean: Clean the created uv-managed .venv and config files after execution. Pre-existing files are not deleted.
  • -A, --py-arg <ARGs>: Additional arguments to pass to the Python script. Must be placed as the last argument(s) and will be passed directly to Python.

Example

minimum usage

assume there is a project like this:

project/
├── myscript.py
├── requirements.txt
└── .env

py_executer my_script.py

this will be equivalent to:

uv init --bare
uv venv
uv add -r requirements.txt
export $(grep -v '^#' .env | xargs)  # if .env exists
PYTHONPATH=$PYTHONPATH:$(pwd)
.venv/bin/python my_script.py

after the execution, the script will create uv project files

project/
├── myscript.py
├── requirements.txt
├── .env
├── uv.lock
├── .venv/
└── pyproject.toml

to clean up generated files afterward, you can add --clean in the argument

more customized options

py_executer my_script.py -v venv -E DEBUG=true -A --input data.txt

this will be equivalent to:

export $(grep -v '^#' .env | xargs)
PYTHONPATH=$PYTHONPATH:$(pwd)
DEBUG=true
venv/bin/python3 my_script.py --input data.txt

Project Structure

  • src/main.rs: Main CLI logic and environment setup.
  • src/lib/: Internal modules for utilities, macros, and uv integration.

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.