Metadata-Version: 2.4
Name: venvm
Version: 0.4.0
Summary: Select a virtual environment and run Python scripts or modules.
Author: FastFingertips
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/venvm/
Project-URL: Repository, https://github.com/fastfingertips/venvm
Project-URL: Issues, https://github.com/fastfingertips/venvm/issues
Keywords: cli,python,venv,virtual-environment
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">
  <h1>venvm</h1>
  <p>Select a Python virtual environment and run scripts or modules with it.</p>
  <p>
    <a href="https://pypi.org/project/venvm/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/venvm.svg"></a>
    <a href="https://pypi.org/project/venvm/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/venvm.svg"></a>
    <a href="https://github.com/fastfingertips/venvm/actions/workflows/tests.yml"><img alt="Tests" src="https://github.com/fastfingertips/venvm/actions/workflows/tests.yml/badge.svg"></a>
    <a href="https://github.com/fastfingertips/venvm/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/venvm.svg"></a>
  </p>
  <p><strong>English</strong> | <a href="https://github.com/fastfingertips/venvm/blob/main/README.tr.md">Türkçe</a></p>
</div>

## Installation

Install venvm from PyPI:

```console
python -m pip install venvm
```

## Usage

Select an environment and script interactively:

```console
venvm
```

In an interactive terminal, use the arrow keys and Enter or type an option
number and press Enter. Numbered prompts remain available in non-interactive
terminals.

Script discovery scans the project recursively and displays paths relative to
the project root. Virtual environments, version-control metadata, caches,
build output, and `node_modules` are excluded from the scan. Root-level scripts
are listed first, followed by scripts in progressively deeper directories.

The script picker shows only the current directory and child directories that
contain scripts. Use Right or Enter to open a directory, Left to return to its
parent, and Enter to run a script. Numbered selection remains available.

Run a script with arguments:

```console
venvm app.py --port 8000
```

Select an environment explicitly or use the system interpreter:

```console
venvm --env .venv app.py
venvm --system app.py
```

Run a Python module:

```console
venvm --env .venv --module pytest -q
venvm --system --module http.server 8000
```

Values after `--module` are passed directly to the module. Place environment
options before `--module`.

List detected environments without running anything:

```console
venvm --list
```

`--yes` accepts confirmation prompts. If multiple environments exist, `.venv`
is used when available. Otherwise, specify the environment with `--env`.

Use `--install-deps` to install detected dependency sources without additional
confirmation. `--yes` alone never installs dependencies automatically.

The command scans direct children of the current directory for `pyvenv.cfg` and
the platform-specific Python executable. If no environment exists, it offers to
create `.venv`. The system Python interpreter remains available as an option.

After creating an environment, `venvm` detects `requirements.txt`,
`requirements-dev.txt`, and `pyproject.toml`. It asks for confirmation before
installing each source.

## Project Configuration

Add `.venvm.json` to the project root to define defaults:

```json
{
  "environment": ".venv",
  "script": "app.py"
}
```

For a module:

```json
{
  "environment": ".venv",
  "module": "pytest"
}
```

`script` and `module` cannot be used together. Command-line values override the
configuration file. When run from a subdirectory, venvm searches parent
directories for the nearest `.venvm.json` and uses its directory as the project
root.

## Development

Install the repository in editable mode:

```console
python -m pip install -e .
```

Run the standard-library test suite:

```console
python -m unittest discover -s tests
```

## Roadmap

Planned configuration and project management work is tracked in
[`.github/TODO.md`](https://github.com/fastfingertips/venvm/blob/main/.github/TODO.md).
