vexx 0.1.0__tar.gz

vexx-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2014 Sasha Hart
+Copyright (c) 2026 Adam Henderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vexx-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: vexx
+Version: 0.1.0
+Summary: Run commands in a virtualenv
+Project-URL: Homepage, https://github.com/a-hendo/vex
+Project-URL: Repository, https://github.com/a-hendo/vex
+Author-email: Adam Henderson <adamhenderson90@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: deployment,installation,virtualenv,virtualenvwrapper,workon
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: virtualenv
+Description-Content-Type: text/markdown
+
+# Vex
+
+**Run a command in a virtualenv.**
+
+Vex is an elegant, shell-agnostic tool for running commands inside virtual environments. Unlike traditional methods that rely on "activating" and "deactivating" environments by mutating your current shell's state, Vex simply launches a new process with the correct environment variables (like `PATH` and `VIRTUAL_ENV`) already set.
+
+When the command finishes, the environment is gone. No cleanup, no `deactivate`, no shell-specific hacks.
+
+## Modernization
+
+Vex has been modernized to support the latest Python standards:
+
+- **Python 3.12+ Required**: Leveraging modern features and built-in type safety.
+- **UV Integration**: Vex now detects and uses [uv](https://github.com/astral-sh/uv) for lightning-fast virtualenv creation when using `--make`.
+- **Pyproject.toml**: Fully migrated to modern PEP 517/518 packaging.
+- **Type Safety**: The entire codebase is now fully type-hinted.
+
+## How it works
+
+`vex` runs any command in a virtualenv without modifying your current shell.
+
+The standard way to use a virtualenv involves sourcing an `activate` script which modifies your shell's environment and adds a `deactivate` function. This is often brittle and shell-specific.
+
+Vex takes a simpler approach: it calculates the environment required for the virtualenv and passes it directly to a new subprocess. This makes it naturally compatible with **bash, zsh, fish, PowerShell, cmd.exe**, and any other shell or executable.
+
+## Examples
+
+- `vex myenv bash`: Launch a bash shell with virtualenv `myenv` enabled. Exit the shell (Ctrl-D) to "deactivate".
+- `vex myenv python`: Launch a Python interpreter inside virtualenv `myenv`.
+- `vex myenv pip install requests`: Install a package into `myenv` without activating it.
+- `vex -m ephemeral echo "Hello"`: Create a new virtualenv named `ephemeral`, run the command, and then immediately **remove** the virtualenv.
+- `vex --path ./venv python script.py`: Run a script using a virtualenv located at a specific path.
+
+## Installation
+
+The recommended way to install Vex is using [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv tool install vexx
+```
+
+Alternatively, you can use pip:
+
+```bash
+pip install --user vexx
+```
+
+### Usage with UV
+
+Vex is designed to work seamlessly with `uv`. If `uv` is installed on your system, `vex --make` will automatically use `uv venv` to create environments, which is significantly faster than traditional `virtualenv`.
+
+## Config
+
+Vex looks for an optional configuration file at `~/.vexrc`.
+
+```ini
+shell=bash
+virtualenvs=~/.virtualenvs
+python=python3.12
+env:
+    ANSWER=42
+```
+
+- **shell**: The default shell to run if no command is provided (e.g., `vex myenv`).
+- **virtualenvs**: The directory where your named virtualenvs are stored (defaults to `$WORKON_HOME` or `~/.virtualenvs`).
+- **python**: The default Python executable to use when creating new environments with `--make`.
+- **env**: Custom environment variables to inject into every Vex-managed process.
+
+## Environment Variables
+
+### WORKON_HOME
+
+Vex uses the `WORKON_HOME` environment variable to determine where named virtual environments are stored. By default, this is `~/.virtualenvs`.
+
+If you are using **uv** in a project and want Vex to target virtual environments local to your current directory (like a `.venv` folder), it is recommended to set `WORKON_HOME` to `./`:
+
+```bash
+export WORKON_HOME="./"
+```
+
+This allows you to use `vex .venv python` to run commands in your local project environment seamlessly.
+
+## Shell Prompts
+
+Vex does not automatically change your prompt. To see the current virtualenv in your prompt, you can use the `$VIRTUAL_ENV` variable in your shell configuration.
+
+**Bash Example (~/.bashrc):**
+
+```bash
+function virtualenv_prompt() {
+    if [ -n "$VIRTUAL_ENV" ]; then
+        echo "(${VIRTUAL_ENV##*/}) "
+    fi
+}
+export PS1='$(virtualenv_prompt)\u@\H> '
+```
+
+## Shell Completion
+
+Vex provides completion for virtualenv names. To enable it, add the following to your shell config:
+
+**Bash (~/.bashrc):**
+`eval "$(vex --shell-config bash)"`
+
+**Zsh (~/.zshrc):**
+`eval "$(vex --shell-config zsh)"`
+
+**Fish (~/.config/fish/config.fish):**
+`vex --shell-config fish | source`
+
+## Development
+
+Vex development is now managed with `uv`.
+
+```bash
+git clone https://github.com/a-hendo/vex
+cd vex
+uv sync
+uv run pytest
+```
+
+## Credits
+
+Vex was originally created by [Sasha Hart](https://github.com/sashahart). This version is a modernized fork of the [original project](https://github.com/sashahart/vex).

vexx-0.1.0/README.md

@@ -0,0 +1,124 @@
+# Vex
+
+**Run a command in a virtualenv.**
+
+Vex is an elegant, shell-agnostic tool for running commands inside virtual environments. Unlike traditional methods that rely on "activating" and "deactivating" environments by mutating your current shell's state, Vex simply launches a new process with the correct environment variables (like `PATH` and `VIRTUAL_ENV`) already set.
+
+When the command finishes, the environment is gone. No cleanup, no `deactivate`, no shell-specific hacks.
+
+## Modernization
+
+Vex has been modernized to support the latest Python standards:
+
+- **Python 3.12+ Required**: Leveraging modern features and built-in type safety.
+- **UV Integration**: Vex now detects and uses [uv](https://github.com/astral-sh/uv) for lightning-fast virtualenv creation when using `--make`.
+- **Pyproject.toml**: Fully migrated to modern PEP 517/518 packaging.
+- **Type Safety**: The entire codebase is now fully type-hinted.
+
+## How it works
+
+`vex` runs any command in a virtualenv without modifying your current shell.
+
+The standard way to use a virtualenv involves sourcing an `activate` script which modifies your shell's environment and adds a `deactivate` function. This is often brittle and shell-specific.
+
+Vex takes a simpler approach: it calculates the environment required for the virtualenv and passes it directly to a new subprocess. This makes it naturally compatible with **bash, zsh, fish, PowerShell, cmd.exe**, and any other shell or executable.
+
+## Examples
+
+- `vex myenv bash`: Launch a bash shell with virtualenv `myenv` enabled. Exit the shell (Ctrl-D) to "deactivate".
+- `vex myenv python`: Launch a Python interpreter inside virtualenv `myenv`.
+- `vex myenv pip install requests`: Install a package into `myenv` without activating it.
+- `vex -m ephemeral echo "Hello"`: Create a new virtualenv named `ephemeral`, run the command, and then immediately **remove** the virtualenv.
+- `vex --path ./venv python script.py`: Run a script using a virtualenv located at a specific path.
+
+## Installation
+
+The recommended way to install Vex is using [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv tool install vexx
+```
+
+Alternatively, you can use pip:
+
+```bash
+pip install --user vexx
+```
+
+### Usage with UV
+
+Vex is designed to work seamlessly with `uv`. If `uv` is installed on your system, `vex --make` will automatically use `uv venv` to create environments, which is significantly faster than traditional `virtualenv`.
+
+## Config
+
+Vex looks for an optional configuration file at `~/.vexrc`.
+
+```ini
+shell=bash
+virtualenvs=~/.virtualenvs
+python=python3.12
+env:
+    ANSWER=42
+```
+
+- **shell**: The default shell to run if no command is provided (e.g., `vex myenv`).
+- **virtualenvs**: The directory where your named virtualenvs are stored (defaults to `$WORKON_HOME` or `~/.virtualenvs`).
+- **python**: The default Python executable to use when creating new environments with `--make`.
+- **env**: Custom environment variables to inject into every Vex-managed process.
+
+## Environment Variables
+
+### WORKON_HOME
+
+Vex uses the `WORKON_HOME` environment variable to determine where named virtual environments are stored. By default, this is `~/.virtualenvs`.
+
+If you are using **uv** in a project and want Vex to target virtual environments local to your current directory (like a `.venv` folder), it is recommended to set `WORKON_HOME` to `./`:
+
+```bash
+export WORKON_HOME="./"
+```
+
+This allows you to use `vex .venv python` to run commands in your local project environment seamlessly.
+
+## Shell Prompts
+
+Vex does not automatically change your prompt. To see the current virtualenv in your prompt, you can use the `$VIRTUAL_ENV` variable in your shell configuration.
+
+**Bash Example (~/.bashrc):**
+
+```bash
+function virtualenv_prompt() {
+    if [ -n "$VIRTUAL_ENV" ]; then
+        echo "(${VIRTUAL_ENV##*/}) "
+    fi
+}
+export PS1='$(virtualenv_prompt)\u@\H> '
+```
+
+## Shell Completion
+
+Vex provides completion for virtualenv names. To enable it, add the following to your shell config:
+
+**Bash (~/.bashrc):**
+`eval "$(vex --shell-config bash)"`
+
+**Zsh (~/.zshrc):**
+`eval "$(vex --shell-config zsh)"`
+
+**Fish (~/.config/fish/config.fish):**
+`vex --shell-config fish | source`
+
+## Development
+
+Vex development is now managed with `uv`.
+
+```bash
+git clone https://github.com/a-hendo/vex
+cd vex
+uv sync
+uv run pytest
+```
+
+## Credits
+
+Vex was originally created by [Sasha Hart](https://github.com/sashahart). This version is a modernized fork of the [original project](https://github.com/sashahart/vex).

vexx-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vexx"
+dynamic = ["version"]
+description = "Run commands in a virtualenv"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+keywords = ["virtualenv", "virtualenvwrapper", "workon", "installation", "deployment"]
+authors = [
+    { name = "Adam Henderson", email = "adamhenderson90@gmail.com" },
+]
+classifiers = [
+    "Topic :: Utilities",
+    "Topic :: Software Development",
+    "Topic :: System :: Shells",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 3 - Alpha",
+    "Operating System :: POSIX",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "virtualenv",
+]
+
+[project.urls]
+Homepage = "https://github.com/a-hendo/vex"
+Repository = "https://github.com/a-hendo/vex"
+
+[project.scripts]
+vex = "vex.main:main"
+
+[tool.hatch.version]
+path = "vex/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vex"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/vex",
+    "/LICENSE",
+    "/README.md",
+]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "mypy",
+    "ruff",
+    "tox",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["vex/tests", "vex/functional_tests"]
+
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+envlist = py312, py313
+isolated_build = True
+
+[testenv]
+description = run tests
+deps =
+    pytest
+commands =
+    pytest {posargs:vex/tests vex/functional_tests}
+"""

vexx-0.1.0/vex/__init__.py

@@ -0,0 +1,5 @@
+"""This module makes "vex" a package."""
+
+from ._version import VERSION as __version__
+
+__all__ = ["__version__"]

vexx-0.1.0/vex/_version.py

@@ -0,0 +1 @@
+VERSION = "0.1.0"

vexx-0.1.0/vex/config.py

@@ -0,0 +1,165 @@
+"""Config file processing (.vexrc)."""
+
+import os
+import platform
+import re
+import shlex
+from collections import OrderedDict
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any
+from re import Pattern
+
+_IDENTIFIER_PATTERN: str = "[a-zA-Z][_a-zA-Z0-9]*"
+_SQUOTE_RE: Pattern[str] = re.compile(r"'([^']*)'\Z")  # NO squotes inside
+_DQUOTE_RE: Pattern[str] = re.compile(r'"([^"]*)"\Z')  # NO dquotes inside
+_HEADING_RE: Pattern[str] = re.compile(rf"^({_IDENTIFIER_PATTERN}):[ \t\n\r]*\Z")
+_VAR_RE: Pattern[str] = re.compile(
+    rf"[ \t]*({_IDENTIFIER_PATTERN}) *= *(.*)[ \t\n\r]*$"
+)
+
+
+class InvalidConfigError(Exception):
+    """Raised when there is an error during a .vexrc file parse."""
+
+    def __init__(self, filename: str, errors: list[tuple[int, str]]):
+        super().__init__()
+        self.filename = filename
+        self.errors = errors
+
+    def __str__(self) -> str:
+        return f"errors in {self.filename!r}, lines {[tup[0] for tup in self.errors]!r}"
+
+
+class Vexrc:
+    """Parsed representation of a .vexrc config file."""
+
+    default_heading: str = "root"
+    default_encoding: str = "utf-8"
+
+    def __init__(self) -> None:
+        self.encoding: str = self.default_encoding
+        self.headings: dict[str, dict[str, str]] = OrderedDict()
+        self.headings[self.default_heading] = OrderedDict()
+        self.headings["env"] = OrderedDict()
+
+    def __getitem__(self, key: str) -> dict[str, str] | None:
+        return self.headings.get(key)
+
+    @classmethod
+    def from_file(cls, path: str, environ: dict[str, str]) -> "Vexrc":
+        """Make a Vexrc instance from given file in given environ."""
+        instance = cls()
+        instance.read(path, environ)
+        return instance
+
+    def read(self, path: str, environ: dict[str, str]) -> None:
+        """Read data from file into this vexrc instance."""
+        try:
+            with open(path, "rb") as inp:
+                parsing = parse_vexrc(inp, environ)
+                for heading, key, value in parsing:
+                    heading = self.default_heading if heading is None else heading
+                    if heading not in self.headings:
+                        self.headings[heading] = OrderedDict()
+                    self.headings[heading][key] = value
+        except FileNotFoundError:
+            return None
+
+    def get_ve_base(self, environ: dict[str, str]) -> str:
+        """Find a directory to look for virtualenvs in."""
+        # set ve_base to a path we can look for virtualenvs:
+        # 1. .vexrc
+        # 2. WORKON_HOME (as defined for virtualenvwrapper's benefit)
+        # 3. $HOME/.virtualenvs
+        ve_base_value: str | None = self.headings[self.default_heading].get(
+            "virtualenvs"
+        )
+        ve_base: str = ""
+        if ve_base_value:
+            ve_base = os.path.expanduser(ve_base_value)
+        else:
+            ve_base = environ.get("WORKON_HOME", "")
+
+        if not ve_base:
+            home: str = ""
+            if platform.system() == "Windows":
+                _win_drive: str = environ.get("HOMEDRIVE", "")
+                home_path: str = environ.get("HOMEPATH", "")
+                if home_path:
+                    home = os.path.join(_win_drive, home_path)
+                else:
+                    home = os.path.expanduser("~")
+            else:
+                home = environ.get("HOME", "")
+                if not home:
+                    home = os.path.expanduser("~")
+
+            if not home:
+                return ""
+            ve_base = os.path.join(home, ".virtualenvs")
+
+        return ve_base
+
+    def get_shell(self, environ: dict[str, str]) -> list[str] | None:
+        """Find a command to run."""
+        command: str | None = self.headings[self.default_heading].get("shell")
+        if not command and os.name != "nt":
+            command = environ.get("SHELL", "")
+        return shlex.split(command) if command else None
+
+    def get_default_python(self, environ: dict[str, str]) -> str | None:
+        """Find a command to run."""
+        return self.headings[self.default_heading].get("python")
+
+
+def extract_heading(line: str) -> str | None:
+    """Return heading in given line or None if it's not a heading."""
+    match: Any = _HEADING_RE.match(line)
+    return match.group(1) if match else None
+
+
+def extract_key_value(line: str, environ: dict[str, str]) -> tuple[str, str] | None:
+    """Return key, value from given line if present, else return None."""
+    segments: list[str] = line.split("=", 1)
+    if len(segments) < 2:
+        return None
+    key, value = segments
+    value = value.strip()
+    if value:
+        if value.startswith("'") and _SQUOTE_RE.match(value):
+            value = value[1:-1]
+        elif value.startswith('"') and _DQUOTE_RE.match(value):
+            template: str = value[1:-1]
+            try:
+                value = template.format(**environ)
+            except KeyError:
+                # Fallback to literal if env var missing?
+                pass
+        value = value.strip()
+    key = key.strip()
+    return key, value
+
+
+def parse_vexrc(
+    inp: Any, environ: dict[str, str]
+) -> Generator[tuple[str | None, str, str], None, None]:
+    """Iterator yielding key/value pairs from given stream."""
+    heading: str | None = None
+    errors: list[Any] = []
+    for line_number, line_bytes in enumerate(inp):
+        line = line_bytes.decode("utf-8")
+        if not line.strip():
+            continue
+        extracted_heading: str | None = extract_heading(line)
+        if extracted_heading is not None:
+            heading = extracted_heading
+            continue
+        kv_tuple: tuple[str, str] | None = extract_key_value(line, environ)
+        if kv_tuple is None:
+            errors.append((line_number, line))
+            continue
+        yield heading, kv_tuple[0], kv_tuple[1]
+
+    if errors:
+        raise InvalidConfigError(getattr(inp, "name", "unknown"), errors)

vexx-0.1.0/vex/exceptions.py

@@ -0,0 +1,60 @@
+"""Exceptions for vex."""
+
+
+class InvalidArgument(Exception):
+    """Base class for exceptions raised by anything under main()."""
+
+    def __init__(self, message: str) -> None:
+        self.message: str = message
+        super().__init__(message)
+
+
+class NoVirtualenvName(InvalidArgument):
+    """No virtualenv name was given."""
+
+
+class NoVirtualenvsDirectory(InvalidArgument):
+    """There is no directory to find named virtualenvs in."""
+
+
+class OtherShell(InvalidArgument):
+    """The given argument to --shell-config is not recognized."""
+
+
+class UnknownArguments(InvalidArgument):
+    """Unknown arguments were given on the command line."""
+
+
+class InvalidVexrc(InvalidArgument):
+    """Config file specified or required but absent or unparseable."""
+
+
+class InvalidVirtualenv(InvalidArgument):
+    """No usable virtualenv was found."""
+
+
+class InvalidCommand(InvalidArgument):
+    """No runnable command was found."""
+
+
+class InvalidCwd(InvalidArgument):
+    """cwd specified or required but unusable."""
+
+
+class BadConfig(InvalidArgument):
+    """Fatal conditions encountered on the way to run."""
+
+
+class VirtualenvAlreadyMade(InvalidArgument):
+    """Virtualenv already exists."""
+
+
+class VirtualenvNotMade(InvalidArgument):
+    """Could not make virtualenv."""
+
+
+class VirtualenvNotRemoved(InvalidArgument):
+    """Virtualenv could not be removed."""
+
+
+CommandNotFoundError = FileNotFoundError

vexx-0.1.0/vex/functional_tests/not_python

@@ -0,0 +1,2 @@
+#!/usr/bin/env python3
+print("not python")