Skip to content

add flexible venv naming and setup #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
remytuyeras merged 1 commit into from
Dec 26, 2025
Merged

add flexible venv naming and setup #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,27 +72,36 @@ Once Python and Rust are installed, clone the repo and initialize the environmen
```bash
git clone https://github.com/Summoner-Network/summoner-core.git
cd summoner-core
source setup.sh # optional flags: [--uv] [--server <prefix>] (see below)
source setup.sh # optional flags: [--uv] [--server <prefix>] [--venv <path>] (see below)
```

Optional flags for `source setup.sh`:

* `--uv` uses `uv` instead of `pip` and requires `uv` on `PATH`.
* `--server <prefix>` selects which Rust servers to (re)install by prefix. The prefix is appended to `rust_server_`. Any crate starting with `rust_server_<prefix>` will be installed. Default prefix is `v1_0_0`.
* `--venv <path>` selects which virtual environment to use. This lets you use `venv/`, `.venv/`, or any custom name. If omitted, the default is `venv/` unless you already activated a venv (in which case the active `$VIRTUAL_ENV` is used).

Examples:

```bash
source setup.sh --uv
source setup.sh --server v1_ # installs all rust_server_v1_* crates if present
source setup.sh --uv --server v1_1_0 # installs rust_server_v1_1_0 only

# Flexible venv naming
python3 -m venv .venv
source .venv/bin/activate
source setup.sh --uv # uses the active venv via $VIRTUAL_ENV

# Or explicitly select a venv path (no need to pre-activate)
source setup.sh --venv .venv --uv
```

The `setup.sh` script performs the following actions:

**Python environment**

* Creates and activates a Python virtual environment at `venv/`.
* Creates and activates a Python virtual environment (default: `venv/`).
* Installs core Python build tooling: `setuptools`, `wheel`, `maturin`.
* Uses `pip` by default, or `uv` when `--uv` is set.

Expand Down
142 changes: 103 additions & 39 deletions reinstall_python_sdk.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,92 +2,114 @@
# ======================
# reinstall_python_sdk.sh
# ======================

#
# Purpose
# -------
# This script reinstalls the Summoner Python SDK inside an existing virtual environment, and (as part of the workflow)
# This script reinstalls the Summoner Python SDK inside a virtual environment, and (as part of the workflow)
# also triggers a Rust-side reinstall via `reinstall_rust_server.sh`.

#
# The goal is to make "reinstall everything I need to run Summoner" a single command, while remaining compatible
# with different virtualenv naming conventions (venv/.venv/custom) and different Python installers (pip vs uv).
#
# What it does, step by step
# --------------------------
# 1) Selects which virtual environment to use:
# - Default: <repo-root>/venv
# - With --dev-core: <this-script-dir>/venv

# 1) Selects which virtual environment to use (in priority order):
# - If --venv <path> is provided: uses that venv.
# - Else if $VIRTUAL_ENV is set (i.e., you already activated a venv): uses the active venv.
# - Else:
# - Default: <repo-root>/venv
# - With --dev-core: <this-script-dir>/venv
#
# 2) Activates that virtual environment (it must already exist).

#
# 3) Reinstalls Rust components by calling:
# - ./reinstall_rust_server.sh [<optional-prefix>] [--dev-core]

#
# 4) Reinstalls the Python package named `summoner`:
# - If `summoner` is already installed, it is uninstalled first.
# - Then it is installed again from this directory:
# - Default: installs normally (pkg install .)
# - With --dev-core: editable (pkg install -e .)

#
# Arguments
# ---------
# Usage:
# bash reinstall_python_sdk.sh [<optional-prefix>] [--dev-core] [--uv]

# bash reinstall_python_sdk.sh [<optional-prefix>] [--dev-core] [--uv] [--venv <path>]
#
# - <optional-prefix>
# An optional string forwarded to the Rust reinstall script. If you do not need it, omit it.

#
# - --dev-core
# Switches the venv location and also switches Python installation mode:
# - Uses venv at: <this-script-dir>/venv
# Switches the default venv location (only used when neither --venv nor $VIRTUAL_ENV is provided),
# and also switches Python installation mode:
# - Default venv becomes: <this-script-dir>/venv
# - Installs `summoner` in editable mode (-e), which is useful when you are actively developing the SDK.

#
# - --uv
# Uses `uv` as the package manager instead of `pip` for Python install/uninstall/show operations.
# This is useful in repos that standardize on uv and do not want direct `pip ...` commands in their workflow.

#
# Important details:
# - You must have `uv` installed and available on PATH.
# - The script still activates a venv; `--uv` only changes how packages are installed inside it.
# - In `--uv` mode, the script sets VIRTUAL_ENV to the chosen venv path so `uv pip ...` targets the correct environment.

#
# - --venv <path>
# Explicitly selects which venv to use (supports venv/.venv/myvenv/etc).
# This has priority over both $VIRTUAL_ENV and the default conventions.
#
# Examples:
# bash reinstall_python_sdk.sh --venv .venv
# bash reinstall_python_sdk.sh --venv myvenv --uv
#
# Environment expectations
# ------------------------
# - A virtual environment must already exist at the expected location:
# - <repo-root>/venv/bin/activate (default)
# - <this-script-dir>/venv/bin/activate (with --dev-core)
# - A virtual environment must already exist at the selected location.
# If it does not exist, create it first (examples below).

#
# - Default mode requires `pip` to exist inside the venv.
# If your venv was created in a way that does not include pip, either:
# - recreate the venv with pip available, or
# - rerun this script with --uv.

#
# Examples
# --------
# 1) Typical usage (pip, normal install into <repo-root>/venv):
# 1) Typical usage (pip, normal install into <repo-root>/venv unless $VIRTUAL_ENV is set):
# bash reinstall_python_sdk.sh

#
# 2) With a Rust prefix forwarded to reinstall_rust_server.sh:
# bash reinstall_python_sdk.sh rust_server_v1_0_0

# 3) Developer workflow (editable install, venv next to this script):
#
# 3) Developer workflow (editable install, venv next to this script unless $VIRTUAL_ENV/--venv is provided):
# bash reinstall_python_sdk.sh --dev-core

#
# 4) uv workflow (uses uv pip instead of pip):
# bash reinstall_python_sdk.sh --uv
# bash reinstall_python_sdk.sh rust_server_v1_0_0 --uv
# bash reinstall_python_sdk.sh --dev-core --uv

#
# 5) Flexible venv naming:
# python3 -m venv .venv
# source .venv/bin/activate
# bash reinstall_python_sdk.sh --uv
#
# # or explicitly:
# bash reinstall_python_sdk.sh --venv .venv --uv
#
# Creating the venv (if missing)
# ------------------------------
# Default venv:
# python3 -m venv venv
# source venv/bin/activate

#
# uv venv (if your repo standardizes on uv):
# uv venv venv
# source venv/bin/activate

#
# Troubleshooting
# ---------------
# - "Virtualenv not found": create the venv at the expected location (see above).
# - "Virtualenv not found": create the venv at the expected location (see above), or pass --venv <path>,
# or activate your venv first so $VIRTUAL_ENV is set.
# - "--uv was set but 'uv' is not on PATH": install uv and ensure it is available in your shell.
# - "'pip' not found in this environment": use --uv or recreate the venv with pip.
# ======================
Expand All @@ -101,35 +123,62 @@ ROOT_DIR="$(cd "$THIS_SCRIPT/.." && pwd)"
RUST_SCRIPT="$THIS_SCRIPT/reinstall_rust_server.sh"

# ─────────────────────────────────────────────────────────────
# Parse args: <optional-prefix> [--dev-core] [--uv]
# Parse args: <optional-prefix> [--dev-core] [--uv] [--venv <path>]
# ─────────────────────────────────────────────────────────────
DEV_CORE=false
USE_UV=false
PREFIX_FILTER=""
VENV_OVERRIDE=""

echo "🔍 Raw arguments: $*"

prev=""
for arg in "$@"; do
if [[ "$arg" == "--dev-core" ]]; then
DEV_CORE=true
elif [[ "$arg" == "--uv" ]]; then
USE_UV=true
elif [[ "$prev" == "--venv" ]]; then
VENV_OVERRIDE="$arg"
prev=""
continue
elif [[ "$arg" == "--venv" ]]; then
prev="--venv"
elif [[ -z "$PREFIX_FILTER" && "$arg" != --* ]]; then
PREFIX_FILTER="$arg"
fi
done

echo "✅ Final values: DEV_CORE=$DEV_CORE, USE_UV=$USE_UV, PREFIX_FILTER=$PREFIX_FILTER"
if [[ "$prev" == "--venv" ]]; then
echo "❌ --venv requires a value, e.g. --venv .venv" >&2
exit 1
fi

echo "✅ Final values: DEV_CORE=$DEV_CORE, USE_UV=$USE_UV, PREFIX_FILTER=$PREFIX_FILTER, VENV_OVERRIDE=$VENV_OVERRIDE"

# ─────────────────────────────────────────────────────────────
# Select venv location
# Select venv location (flexible)
# Priority:
# 1) --venv <path>
# 2) active venv via $VIRTUAL_ENV
# 3) default convention (dev-core vs parent venv)
# ─────────────────────────────────────────────────────────────
if [ "$DEV_CORE" = true ]; then
if [[ -n "$VENV_OVERRIDE" ]]; then
VENV_DIR="$VENV_OVERRIDE"
elif [[ -n "${VIRTUAL_ENV:-}" ]]; then
VENV_DIR="$VIRTUAL_ENV"
elif [[ "$DEV_CORE" == true ]]; then
VENV_DIR="$THIS_SCRIPT/venv"
else
VENV_DIR="$ROOT_DIR/venv"
fi

# If user passed a relative path via --venv, resolve it relative to ROOT_DIR for stability.
# (If it's already absolute, keep it as-is.)
if [[ "$VENV_DIR" != /* ]]; then
VENV_DIR="$(cd "$ROOT_DIR" && cd "$VENV_DIR" && pwd)"
fi

# ─────────────────────────────────────────────────────────────
# Activate virtualenv
# ─────────────────────────────────────────────────────────────
Expand All @@ -138,7 +187,10 @@ if [ -f "$VENV_DIR/bin/activate" ]; then
# shellcheck disable=SC1090
. "$VENV_DIR/bin/activate"
else
echo "❌ Virtualenv not found at: $VENV_DIR"
echo "❌ Virtualenv not found at: $VENV_DIR" >&2
echo " Tips:" >&2
echo " - pass --venv .venv (or your venv path)" >&2
echo " - or activate your venv first so \$VIRTUAL_ENV is set" >&2
exit 1
fi

Expand All @@ -162,6 +214,10 @@ pkg() {
# Diagnostic: show interpreter + tool in use
PY=$(command -v python 2>/dev/null || echo 'not found')
echo "🐍 Using Python: $PY"
echo "🧪 Selected venv: $VENV_DIR"
if [[ -n "${VIRTUAL_ENV:-}" ]]; then
echo "🧪 Active \$VIRTUAL_ENV: $VIRTUAL_ENV"
fi

if [[ "$USE_UV" == "true" ]]; then
UV=$(command -v uv 2>/dev/null || echo 'not found')
Expand Down Expand Up @@ -216,9 +272,17 @@ fi
echo "✅ Python SDK reinstalled successfully with prefix: '$PREFIX_FILTER'"

if [ "$DEV_CORE" = true ]; then
echo " (used --dev-core → venv at $THIS_SCRIPT/venv)"
echo " (used --dev-core → default venv would be $THIS_SCRIPT/venv if not overridden)"
else
echo " (used default → default venv would be $ROOT_DIR/venv if not overridden)"
fi

if [[ -n "$VENV_OVERRIDE" ]]; then
echo " (used --venv → venv at $VENV_DIR)"
elif [[ -n "${VIRTUAL_ENV:-}" ]]; then
echo " (used active \$VIRTUAL_ENV → venv at $VENV_DIR)"
else
echo " (used default → venv at $ROOT_DIR/venv)"
echo " (used convention → venv at $VENV_DIR)"
fi

if [[ "$USE_UV" == "true" ]]; then
Expand Down