uvr 0.1.22__tar.gz

uvr-0.1.22/.gitignore

@@ -0,0 +1,24 @@
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+.python-version
+
+# Virtual environments
+.venv
+
+# vscode
+.vscode
+
+# uv
+uv.lock
+
+# Coverage
+.coverage
+coverage.*
+

uvr-0.1.22/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: uvr
+Version: 0.1.22
+Summary: Simple script execution with uv - run Python scripts without explicit --project flag
+Project-URL: Homepage, https://github.com/karnigen/uvr
+Project-URL: Repository, https://github.com/karnigen/uvr.git
+Project-URL: Issues, https://github.com/karnigen/uvr/issues
+Author-email: karnigen <karnigen@gmail.com>
+License: MIT
+Keywords: python,runner,script,tool,uv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+
+
+# Simple Script Execution with uvr
+
+[`uv`](https://github.com/astral-sh/uv.git) is a fast, modern Python package installer and resolver, designed as a drop-in replacement for pip and pip-compile.
+
+Unfortunately, [`uv`](https://github.com/astral-sh/uv.git)
+prioritizes virtual environments within the current directory. This makes it cumbersome to execute scripts located elsewhere, requiring the use of the `--project` flag.
+
+This script offers a streamlined workaround for running Python scripts via `uv`, allowing you to use `uvr [options] script.py` instead of `uv run [options] --project <script_path> script.py`."
+
+Its primary value lies in its simplicity and immediate usability, providing a *quick fix* for a pressing pain point.
+
+
+## Installation
+
+To install `uvr`, use the following command:
+
+```bash
+uv tool install --from git+https://github.com/karnigen/uvr uvr
+```
+
+To upgrade `uvr`, use the following command:
+
+```bash
+uv tool upgrade uvr
+```
+
+
+
+## Usage
+
+Several ways to run your Python scripts with `uv`:
+
+1.  **Using `uv run --project <script_path> script.py`:**
+
+    * This command explicitly tells `uv` to run the specified Python script (`script.py`) within the context of the project located at `<script_path>`.
+    * This is useful when your script relies on dependencies defined within a specific project directory.
+    * Example:
+
+        ```bash
+        uv run [options] --project /path/to/project run_script.py [script_options]
+        ```
+
+2.  **Using `uvr script.py`:**
+
+    * This is a more direct way to execute your Python script (`run_script.py`) using `uvr`.
+    * `uvr` automatically determines the project directory based on the script path, effectively mimicking the `--project` flag's behavior.
+    * Example:
+
+        ```bash
+        uvr [options] [--] run_script.py [script_options]
+        ```
+    * Always use `--` if the automatic script identification fails or could be ambiguous.
+
+
+3.  **Shebang Usage:**
+
+    * Example:
+
+        ```python
+        #!/usr/bin/env -S uvr [options] [--]
+
+        # Your Python code here...
+        ```
+    * Always use `--` if the automatic script identification fails or could be ambiguous.
+
+4. **Scripts without `.py` or `.pyw` extension:**
+    * Automatic `--script` option is added if not already present (`--script` or `--gui-script`) in options.
+    * Otherwise, `uv` might loop indefinitely.
+
+    * Example: For a `foo` script:
+
+        ```python
+            #!/usr/bin/env -S uvr [options] [--]
+            # Your Python code here...
+        ```
+
+        This will be executed as `uv run [options] --script ...` if `[options]` do not already contain `--script` or `--gui-script`.
+
+    * Or, to be more explicit, you can include the `--script`  flag directly in the shebang:
+
+        ```python
+        #!/usr/bin/env -S uvr --script
+        ```
+
+    * **Important Exception for Non-Files**: If the identified `script_path` (the argument immediately following options or `--`) does not point to an actual file on disk, `uvr` will not automatically add the `--script` or `--gui-script` option. This behavior ensures `uvr` can correctly pass through commands that are executables within the virtual environment (e.g., `uvr black .`, `uvr pytest`), rather than a Python script file.
+
+
+5.  **Debug usage:**
+    * Example:
+        ```bash
+        uvr -v [options] [--] run_script.py [script_options]
+        uvr -vv [options] [--] run_script.py [script_options]
+        ```
+
+
+## General Rule for Using the `--` Separator
+The `--` argument functions as a standard command-line delimiter. It explicitly separates options intended for `uvr` (and its underlying `uv` process) from arguments specifically designated for the Python script being executed.
+
+Arguments appearing before the `--` are processed by `uvr` (`uv`). Arguments appearing after the `--` are passed directly to the invoked Python script.
+
+This explicit separation is crucial for:
+
+* **Preventing Ambiguity**: `uvr` employs a basic heuristic to identify the script path (the first non-hyphenated argument). This can lead to misinterpretation if the script itself accepts options that resemble `uvr/uv` arguments.
+
+* **Ensuring Precise Argument Passing**: By using `--`, users guarantee that all subsequent arguments are correctly delivered to their script, bypassing `uvr's` argument parsing logic.
+
+**Recommendation**: Utilize the `--` separator whenever precise control over argument distribution between `uvr/uv` and the target script is required.
+

uvr-0.1.22/README.md

@@ -0,0 +1,110 @@
+
+
+# Simple Script Execution with uvr
+
+[`uv`](https://github.com/astral-sh/uv.git) is a fast, modern Python package installer and resolver, designed as a drop-in replacement for pip and pip-compile.
+
+Unfortunately, [`uv`](https://github.com/astral-sh/uv.git)
+prioritizes virtual environments within the current directory. This makes it cumbersome to execute scripts located elsewhere, requiring the use of the `--project` flag.
+
+This script offers a streamlined workaround for running Python scripts via `uv`, allowing you to use `uvr [options] script.py` instead of `uv run [options] --project <script_path> script.py`."
+
+Its primary value lies in its simplicity and immediate usability, providing a *quick fix* for a pressing pain point.
+
+
+## Installation
+
+To install `uvr`, use the following command:
+
+```bash
+uv tool install --from git+https://github.com/karnigen/uvr uvr
+```
+
+To upgrade `uvr`, use the following command:
+
+```bash
+uv tool upgrade uvr
+```
+
+
+
+## Usage
+
+Several ways to run your Python scripts with `uv`:
+
+1.  **Using `uv run --project <script_path> script.py`:**
+
+    * This command explicitly tells `uv` to run the specified Python script (`script.py`) within the context of the project located at `<script_path>`.
+    * This is useful when your script relies on dependencies defined within a specific project directory.
+    * Example:
+
+        ```bash
+        uv run [options] --project /path/to/project run_script.py [script_options]
+        ```
+
+2.  **Using `uvr script.py`:**
+
+    * This is a more direct way to execute your Python script (`run_script.py`) using `uvr`.
+    * `uvr` automatically determines the project directory based on the script path, effectively mimicking the `--project` flag's behavior.
+    * Example:
+
+        ```bash
+        uvr [options] [--] run_script.py [script_options]
+        ```
+    * Always use `--` if the automatic script identification fails or could be ambiguous.
+
+
+3.  **Shebang Usage:**
+
+    * Example:
+
+        ```python
+        #!/usr/bin/env -S uvr [options] [--]
+
+        # Your Python code here...
+        ```
+    * Always use `--` if the automatic script identification fails or could be ambiguous.
+
+4. **Scripts without `.py` or `.pyw` extension:**
+    * Automatic `--script` option is added if not already present (`--script` or `--gui-script`) in options.
+    * Otherwise, `uv` might loop indefinitely.
+
+    * Example: For a `foo` script:
+
+        ```python
+            #!/usr/bin/env -S uvr [options] [--]
+            # Your Python code here...
+        ```
+
+        This will be executed as `uv run [options] --script ...` if `[options]` do not already contain `--script` or `--gui-script`.
+
+    * Or, to be more explicit, you can include the `--script`  flag directly in the shebang:
+
+        ```python
+        #!/usr/bin/env -S uvr --script
+        ```
+
+    * **Important Exception for Non-Files**: If the identified `script_path` (the argument immediately following options or `--`) does not point to an actual file on disk, `uvr` will not automatically add the `--script` or `--gui-script` option. This behavior ensures `uvr` can correctly pass through commands that are executables within the virtual environment (e.g., `uvr black .`, `uvr pytest`), rather than a Python script file.
+
+
+5.  **Debug usage:**
+    * Example:
+        ```bash
+        uvr -v [options] [--] run_script.py [script_options]
+        uvr -vv [options] [--] run_script.py [script_options]
+        ```
+
+
+## General Rule for Using the `--` Separator
+The `--` argument functions as a standard command-line delimiter. It explicitly separates options intended for `uvr` (and its underlying `uv` process) from arguments specifically designated for the Python script being executed.
+
+Arguments appearing before the `--` are processed by `uvr` (`uv`). Arguments appearing after the `--` are passed directly to the invoked Python script.
+
+This explicit separation is crucial for:
+
+* **Preventing Ambiguity**: `uvr` employs a basic heuristic to identify the script path (the first non-hyphenated argument). This can lead to misinterpretation if the script itself accepts options that resemble `uvr/uv` arguments.
+
+* **Ensuring Precise Argument Passing**: By using `--`, users guarantee that all subsequent arguments are correctly delivered to their script, bypassing `uvr's` argument parsing logic.
+
+**Recommendation**: Utilize the `--` separator whenever precise control over argument distribution between `uvr/uv` and the target script is required.
+

uvr-0.1.22/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "uvr"
+version = "0.1.22"
+description = "Simple script execution with uv - run Python scripts without explicit --project flag"
+readme = "README.md"
+authors = [
+    { name = "karnigen", email = "karnigen@gmail.com" }
+]
+requires-python = ">=3.9"
+dependencies = []
+license = { text = "MIT" }
+keywords = ["uv", "script", "runner", "python", "tool"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/karnigen/uvr"
+Repository = "https://github.com/karnigen/uvr.git"
+Issues = "https://github.com/karnigen/uvr/issues"
+
+[project.scripts]
+uvr = "uvr:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-cov>=6.1.0",
+]

uvr-0.1.22/src/uvr/__init__.py

@@ -0,0 +1 @@
+from .uvr import *

uvr-0.1.22/src/uvr/uvr.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python
+
+import os
+import sys
+import subprocess
+
+# Option '--' is separator.  When you use it, you're telling uvr to treat all arguments that come after it
+#   as destined exclusively for your Python script, not for uvr or uv.
+def resolve_argv():
+    pre_opt = []
+    run_script = None
+    post_opt = []
+
+    # The '--' argument explicitly separates `uvr`/`uv` options (pre-options)
+    # from the script path and any arguments meant for the script (post-options).
+    # Example: uvr <pre_opt> -- <script_path> <post_opt>
+    # For instance, `uvr -a --b -- my_script.py --d` would pass `-a --b` to `uvr`/`uv`
+    # and `my_script.py --d` to the script.
+
+    if '--' in sys.argv:
+        idx = sys.argv.index('--')
+        pre_opt = sys.argv[1:idx]
+
+    else:
+        # Simple heuristic for pre-options:
+        # Identifies options (starting with '-') at the beginning of the arguments.
+        # The first argument found that doesn't start with '-' is assumed to be the script path.
+        # Example: uvr -a -b script_name --arg1 --arg2
+        # Here, pre_opt would be ['-a', '-b'], and 'script_name' is identified as the script.
+
+        idx = 0
+        for i in range(1, len(sys.argv)):
+            if sys.argv[i].startswith('-'):
+                idx = i
+            else:
+                break
+        pre_opt = sys.argv[1:idx + 1]
+
+    if idx + 1 >= len(sys.argv) or sys.argv[idx + 1].startswith('-'):
+        return pre_opt, run_script, post_opt
+
+    run_script = sys.argv[idx + 1]
+    post_opt = sys.argv[idx + 2:]
+
+    # prevent looping forever the same script not ending with .py or .pyw
+    if not (run_script.endswith('.py') or run_script.endswith('.pyw')):
+        if '--script' not in pre_opt and '--gui-script' not in pre_opt:
+            if os.path.isfile(run_script):  # check if the script is a valid file
+                pre_opt.append('--script')  # if it is a file, we assume it is a python script
+
+    return pre_opt, run_script, post_opt
+
+
+def main():  # pragma: no cover
+    if len(sys.argv) < 2:
+        print("Shebang usage:      #!/usr/bin/env -S uvr [options] [--]")
+        print(
+            "Command line usage: uvr [options] [--] script.py [script options]"
+        )
+        print(
+            "Debug usage:        uvr -v [options] [--] script.py [script options]"
+        )
+
+        sys.exit(1)
+
+    pre_opt, run_script, post_opt = resolve_argv()
+
+    if '-v' in pre_opt or '-vv' in pre_opt:
+        print(f"DEBUG uvr {sys.argv=}", file=sys.stderr)
+        print(f"DEBUG uvr {pre_opt=} {run_script=} {post_opt=}", file=sys.stderr)
+
+        if '-vv' in pre_opt:  # exit after debug output
+            sys.exit(0)
+
+    if run_script is None:
+        print("No script provided", file=sys.stderr)
+        sys.exit(1)
+
+    if not os.path.isfile(run_script):    # fall back to uv run
+        prog_args = ['uv', 'run'] + pre_opt + [
+            run_script
+        ] + post_opt  # fall back to uv run
+    else:
+        run_script = os.path.realpath(run_script)
+        run_script_dir = os.path.dirname(run_script)
+        prog_args = ['uv', 'run'] + pre_opt + [
+            '--project', run_script_dir, run_script
+        ] + post_opt
+
+    if '-v' in pre_opt:
+        print(f"DEBUG uv {prog_args=}", file=sys.stderr)
+
+
+    subprocess.run(prog_args)
+    sys.exit(0)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

uvr-0.1.22/tests/foo

@@ -0,0 +1,7 @@
+#!/usr/bin/env -S uvr -vv
+
+#!/usr/bin/env -S uvr --gui-script
+
+#!/usr/bin/env -S uvr --script
+
+print("Hello from uvr!")

uvr-0.1.22/tests/foo.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env -S uvr -vv --
+
+# will be called as: uvr -vv  tests/foo.py
+
+
+#!/usr/bin/env -S uvr -vv -- no-other-option-after--
+
+#!/usr/bin/env -S uvr --gui-script
+
+#!/usr/bin/env -S uvr --script
+
+import sys
+
+print(sys.argv)

uvr-0.1.22/tests/test_uvr.py

@@ -0,0 +1,61 @@
+import pytest
+import sys
+
+from uvr import *
+
+
+def test_resolve_argv():
+    this_script = os.path.realpath(__file__)
+    this_script_dir = os.path.dirname(this_script)
+
+    # Test case 1: No arguments
+    sys.argv = ['uvr']
+    pre_opt, run_script, post_opt = resolve_argv()
+    assert pre_opt == []
+    assert run_script is None
+    assert post_opt == []
+
+    # Test case 2: Only pre-options
+    sys.argv = ['uvr', '-v', '--']
+    pre_opt, run_script, post_opt = resolve_argv()
+    assert pre_opt == ['-v']
+    assert run_script is None
+    assert post_opt == []
+
+    # Test case 3: Pre-options and script
+    sys.argv = ['uvr', '-v', 'foo.py', 'arg1', 'arg2']
+    pre_opt, run_script, post_opt = resolve_argv()
+    assert pre_opt == [
+        '-v',
+    ]
+    assert run_script == 'foo.py'
+    assert post_opt == ['arg1', 'arg2']
+
+    # Test case 4: Only script
+    sys.argv = ['uvr', 'foo.py']
+    pre_opt, run_script, post_opt = resolve_argv()
+    assert pre_opt == []
+    assert run_script == 'foo.py'
+    assert post_opt == []
+
+    # Test case 5: Script with pre-options and post-options
+    sys.argv = ['uvr', '-v', '--script', 'foo.py', '--option1', '--option2']
+    pre_opt, run_script, post_opt = resolve_argv()
+    assert pre_opt == ['-v', '--script']
+    assert run_script == 'foo.py'
+    assert post_opt == ['--option1', '--option2']
+
+    # Test case 6: Script with pre-options and post-options
+    sys.argv = ['uvr', '--', 'foo.py', '--option1', '--option2']
+    pre_opt, run_script, post_opt = resolve_argv()
+    assert pre_opt == []
+    assert run_script == 'foo.py'
+    assert post_opt == ['--option1', '--option2']
+
+    # Test case 7: Not .py or .pyw extension
+    foo_full_path = os.path.join(this_script_dir, 'foo')
+    sys.argv = ['uvr', '--', foo_full_path, '--option1', '--option2']
+    pre_opt, run_script, post_opt = resolve_argv()
+    assert pre_opt == ['--script']
+    assert run_script == foo_full_path
+    assert post_opt == ['--option1', '--option2']

uvr-0.1.22/uv_scripts/install_github_uvr.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+# just
+
+set -eo pipefail
+
+# where to install uvr
+# ~/.local/bin is a common place for user scripts
+UVR_LOCAL_PATH=~/.local/bin
+UVR_NAME=uvr
+UVR_GIT_NAME=uvr-git
+UVR_LOCAL_FULL_NAME=$UVR_LOCAL_PATH/$UVR_NAME
+
+# if exists uvr-git, rename it to uvr
+if [[ -L $UVR_LOCAL_PATH/$UVR_GIT_NAME ]]; then
+
+    mv $UVR_LOCAL_PATH/$UVR_GIT_NAME $UVR_LOCAL_PATH/$UVR_NAME  # rename uvr-git to uvr
+    echo "Renamed $UVR_GIT_NAME to $UVR_NAME"
+
+else
+
+    echo "No existing $UVR_GIT_NAME link found."
+    # uv uninstall uvr
+    # uv tool install --from git+https://github.com/karnigen/uvr uvr
+
+fi
+

uvr-0.1.22/uv_scripts/install_local_uvr.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+# install local version of uvr in ~/.local/bin
+
+set -eo pipefail
+
+# where to install uvr
+# ~/.local/bin is a common place for user scripts
+UVR_LOCAL_PATH=~/.local/bin
+UVR_NAME=uvr
+UVR_GIT_NAME=uvr-git
+UVR_LOCAL_FULL_NAME=$UVR_LOCAL_PATH/$UVR_NAME   # .local/bin/uvr
+
+# check if script is link use [[  ]]
+if [[ -L $UVR_LOCAL_FULL_NAME ]]; then
+    LINK_TARGET=$(readlink -f $UVR_LOCAL_FULL_NAME)  # get the target of the link: uvr -> ...
+    if [[ $LINK_TARGET == *".local/share"* ]]; then  # this is uvr-git version
+        mv $UVR_LOCAL_FULL_NAME $UVR_LOCAL_PATH/$UVR_GIT_NAME  # rename uvr to uvr-git
+        echo "Renamed $UVR_NAME to $UVR_GIT_NAME"
+    else  # local version active
+        # rm $UVR_LOCAL_FULL_NAME
+        # echo "Removed existing link at $UVR_LOCAL_FULL_NAME"
+        echo "local version active: $LINK_TARGET"
+        exit 0
+    fi
+fi
+
+
+# git root directory
+GIT_ROOT_DIR=$(git rev-parse --show-toplevel)
+
+# if not installed create symbolic link to local uvr.py, and use force to overwrite existing link
+ln -s -f $GIT_ROOT_DIR/src/uvr/uvr.py $UVR_LOCAL_FULL_NAME
+
+echo "Installed $UVR_NAME to $UVR_LOCAL_FULL_NAME"
+echo "Make sure $UVR_LOCAL_PATH is in your PATH"

uvr-0.1.22/uv_scripts/run_tests.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+set -e
+
+# uvr pytest
+#uvr pytest --cov-report term-missing --cov-report html --cov-report xml --cov=uvr
+
+GIT_ROOT_DIR=$(git rev-parse --show-toplevel)
+cd $GIT_ROOT_DIR
+echo "Current working directory: $(pwd)"
+
+# uvr full path, maybe use type uvr to find it
+UVR=$(type -p uvr)
+echo "Using uvr at: $UVR"
+if [[ -L $UVR ]]; then
+    UVR=$(readlink -f $UVR)   # resolve symlink to the actual file
+    echo "Resolved uvr to: $UVR"
+fi
+
+
+uvr pytest --cov=uvr --cov-report html:coverage --cov-report xml --cov-report term