Update 05.04.2026

zsh/plugins/python/README.md

@@ -12,8 +12,7 @@ plugins=(... python)
 
 | Command          | Description                                                                            |
 | ---------------- | -------------------------------------------------------------------------------------- |
-| `py`             | Runs `python3`                                                                         |
-| `ipython`        | Runs the appropriate `ipython` version according to the activated virtualenv           |
+| `py`             | Runs `python3`. Only set if `py` is not installed.                                     |
 | `pyfind`         | Finds .py files recursively in the current directory                                   |
 | `pyclean [dirs]` | Deletes byte-code and cache files from a list of directories or the current one        |
 | `pygrep <text>`  | Looks for `text` in `*.py` files in the current directory, recursively                 |
@@ -22,8 +21,48 @@ plugins=(... python)
 
 ## Virtual environments
 
-The plugin provides two utilities to manage Python venvs:
+The plugin provides three utilities to manage Python 3.3+ [venv](https://docs.python.org/3/library/venv.html)
+virtual environments:
 
-- `mkv [name]`: make a new virtual environment called `name` (default: `venv`) in current directory.
+- `mkv [name]`: make a new virtual environment called `name` in the current directory.
+  **Default**: `$PYTHON_VENV_NAME` if set, otherwise `venv`.
+
+- `vrun [name]`: activate the virtual environment called `name` in the current directory.
+  **Default**: the first existing in `$PYTHON_VENV_NAMES`.
+
+- `auto_vrun`: automatically activate the venv virtual environment when entering a directory containing
+  `<venv-name>/bin/activate`, and automatically deactivate it when navigating out of it (keeps venv activated
+  in subdirectories).
+  - To enable the feature, set `PYTHON_AUTO_VRUN=true` before sourcing oh-my-zsh.
+  - The plugin activates the first existing virtual environment, in order, appearing in `$PYTHON_VENV_NAMES`.
+    The default virtual environment name is `venv`. To use a different name, set
+    `PYTHON_VENV_NAME=<venv-name>`. For example: `PYTHON_VENV_NAME=".venv"`
+
+### Settings
+
+You can set these variables in your `.zshrc` file, before Oh My Zsh is sourced.
+For example:
+
+```sh
+PYTHON_VENV_NAME=".venv"
+PYTHON_VENV_NAMES=($PYTHON_VENV_NAME venv)
+...
+plugins=(... python)
+source "$ZSH/oh-my-zsh.sh"
+```
+
+
+## `$PYTHON_VENV_NAME`
+
+**Default**: `venv`.
+
+Preferred name for virtual environments, for example when creating via `mkv`.
+
+## `$PYTHON_VENV_NAMES`
+
+**Default**: `$PYTHON_VENV_NAME venv .venv`.
+
+Array of virtual environment names to be checked, in order, by `vrun` and `auto_vrun`.
+This means these functions will load the first existing virtual environment in this list.
+Duplicate names are ignored.
 
-- `vrun [name]`: activate virtual environment called `name` (default: `venv`) in current directory.