uvxy 0.0.1__tar.gz

uvxy-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+# A push to a branch that has an open pull request runs through the
+# pull_request event. Push therefore covers only the main branch.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  lint:
+    name: fmt and clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # This action installs the toolchain and caches the cargo registry and
+      # the target directory. It wraps Swatinem/rust-cache.
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          # No `toolchain` input. The action then reads rust-toolchain.toml,
+          # which pins the version. See that file.
+          components: rustfmt, clippy
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      # --all-targets also lints the test code.
+      - name: Run clippy
+        run: cargo clippy --locked --all-targets -- -D warnings
+
+  test:
+    name: test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # Do not cancel the other platforms when one platform fails. src/uvbin.rs
+      # holds separate Unix and Windows branches. A failure on one platform must
+      # not hide a failure on another.
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          # No `toolchain` input. rust-toolchain.toml pins the version.
+          # Cache each platform under its own key.
+          cache-key: ${{ matrix.os }}
+
+      - name: Run tests
+        run: cargo test --locked

uvxy-0.0.1/.github/workflows/drift.yml

@@ -0,0 +1,140 @@
+name: Drift
+
+# This workflow watches the uv completion format. uvxy reads flag arity from
+# `uv generate-shell-completion zsh`. See docs/adr/0002. A failure here means
+# that uv changed its completion format. It does not mean that uvxy changed.
+on:
+  schedule:
+    # Run every day at 06:17 UTC.
+    - cron: "17 6 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+  # The drift test skips itself unless this variable is set.
+  UVXY_DRIFT: "1"
+
+jobs:
+  drift:
+    name: uv completion format drift check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+
+      # Always take the newest uv release. This workflow must see a format
+      # change on the day that uv ships it.
+      - name: Install the latest uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          version: latest
+
+      # Record the uv version. A reader of a failed run needs this value to
+      # find the release that changed the format.
+      - name: Record the uv version
+        id: uv-version
+        run: |
+          set -euo pipefail
+          uv --version
+          echo "version=$(uv --version)" >> "$GITHUB_OUTPUT"
+          echo "Tested against: \`$(uv --version)\`" >> "$GITHUB_STEP_SUMMARY"
+
+      # cargo test exits 0 when a filter matches no test. This step proves that
+      # a drift test exists. Without it the workflow can pass and monitor
+      # nothing.
+      - name: Confirm that a drift test exists
+        run: |
+          set -euo pipefail
+          cargo test --locked --no-run
+          cargo test --locked -- --list | tee test-list.txt
+          if ! grep -qi drift test-list.txt; then
+            echo "::error title=No drift test::cargo test lists no test with 'drift' in its name. This workflow monitors nothing. Add the drift test to tests/ or fix this workflow."
+            exit 1
+          fi
+
+      # Run the whole suite. The suite name of the drift test is not fixed, so
+      # a filter can miss it. UVXY_DRIFT=1 stops the drift test from skipping.
+      - name: Run the test suite against the current uv release
+        id: drift-test
+        run: cargo test --locked -- --nocapture
+
+      - name: Report the drift failure
+        if: failure() && steps.drift-test.outcome == 'failure'
+        run: |
+          {
+            echo "## uv changed its completion format"
+            echo
+            echo "The drift check failed against uv \`${{ steps.uv-version.outputs.version }}\`."
+            echo
+            echo "uvxy reads flag arity from \`uv generate-shell-completion zsh\`."
+            echo "One or more drift tests failed. Read the test output above for the"
+          echo "assertion that failed, and for what changed."
+            echo
+            echo "Next steps:"
+            echo "1. Run \`uv generate-shell-completion zsh\` and read the new output."
+            echo "2. Update the parser in \`src/flags.rs\`."
+            echo "3. Update \`docs/adr/0002-derive-flag-arity-from-shell-completions.md\` if the approach no longer holds."
+          } >> "$GITHUB_STEP_SUMMARY"
+          echo "::error title=uv changed its completion format::uvxy cannot build a flag table from uv ${{ steps.uv-version.outputs.version }}. Read the job summary."
+          exit 1
+
+  # rust-toolchain.toml pins the toolchain, so a new Rust release cannot turn a
+  # pull request red. This job reads the newest stable Rust instead, and it
+  # reports a new lint here rather than in somebody's pull request.
+  rust:
+    name: newest stable Rust check
+    runs-on: ubuntu-latest
+    env:
+      # rust-toolchain.toml wins over the toolchain that the action installs.
+      # This variable wins over rust-toolchain.toml.
+      RUSTUP_TOOLCHAIN: stable
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+          components: rustfmt, clippy
+          cache-key: drift-stable
+
+      - name: Record the Rust version
+        id: version
+        run: |
+          set -euo pipefail
+          rustc --version | tee rust-version.txt
+          echo "rust=$(rustc --version)" >> "$GITHUB_OUTPUT"
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      - name: Run clippy
+        run: cargo clippy --locked --all-targets -- -D warnings
+
+      - name: Run the tests
+        run: cargo test --locked
+
+      - name: Report the Rust drift
+        if: failure()
+        run: |
+          set -euo pipefail
+          {
+            echo "## The newest stable Rust rejects this code"
+            echo
+            echo "The check failed under \`${{ steps.version.outputs.rust }}\`."
+            echo "\`rust-toolchain.toml\` pins an older version, so pull"
+            echo "requests still pass."
+            echo
+            echo "Next steps:"
+            echo "1. Read the clippy output above."
+            echo "2. Fix the code."
+            echo "3. Raise the channel in \`rust-toolchain.toml\`."
+          } >> "$GITHUB_STEP_SUMMARY"
+          echo "::error title=Newest stable Rust rejects this code::Read the job summary."
+          exit 1

uvxy-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,213 @@
+name: Release
+
+# uvxy is a Rust binary. It does not link PyO3. maturin therefore tags one
+# `py3-none-<platform>` wheel per platform, and that wheel serves every Python
+# version. See docs/adr/0004.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  # maturin reads the version from Cargo.toml, and it ignores the tag. A tag
+  # that disagrees with Cargo.toml therefore publishes the version that
+  # Cargo.toml names, and it reports nothing. A PyPI version is permanent, so
+  # this job runs before every build job.
+  version:
+    name: check the tag against Cargo.toml
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Compare the tag with the version
+        run: |
+          set -euo pipefail
+          crate=$(python3 -c "import tomllib; print(tomllib.load(open('Cargo.toml','rb'))['package']['version'])")
+          echo "Cargo.toml names $crate"
+
+          if [ "${GITHUB_REF_TYPE}" != "tag" ]; then
+            echo "This run carries no tag, so it publishes nothing."
+            exit 0
+          fi
+
+          tag="${GITHUB_REF_NAME#v}"
+          echo "the tag names   $tag"
+
+          if [ "$crate" != "$tag" ]; then
+            echo "::error title=The tag and Cargo.toml disagree::The tag names $tag. Cargo.toml names $crate. maturin reads Cargo.toml, so this release would publish $crate. Correct Cargo.toml, or move the tag."
+            exit 1
+          fi
+          echo "The tag and Cargo.toml agree."
+
+  macos:
+    name: wheel for ${{ matrix.target }}
+    needs: version
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - aarch64-apple-darwin
+          - x86_64-apple-darwin
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build the wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          # Pin maturin. An unpinned action installs the newest maturin, and a
+          # new maturin can change the wheel that this workflow publishes.
+          maturin-version: "1.15.0"
+          args: --release --locked --out dist
+          sccache: "true"
+
+      # actions/upload-artifact v4 and later reject a repeated artifact name.
+      # Each matrix job therefore names its artifact after its target.
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist-wheel-macos-${{ matrix.target }}
+          path: dist
+          if-no-files-found: error
+
+  manylinux:
+    name: wheel for ${{ matrix.target }}
+    needs: version
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - x86_64-unknown-linux-gnu
+          - aarch64-unknown-linux-gnu
+    steps:
+      - uses: actions/checkout@v7
+
+      # maturin-action cross compiles inside a container, so this job needs
+      # no QEMU. The `manylinux` input names that container.
+      - name: Build the wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          # `2014` names the container. `auto` resolves a tag at build time,
+          # and that tag can change.
+          manylinux: "2014"
+          maturin-version: "1.15.0"
+          args: --release --locked --out dist
+          sccache: "true"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist-wheel-manylinux-${{ matrix.target }}
+          path: dist
+          if-no-files-found: error
+
+  musllinux:
+    name: wheel for ${{ matrix.target }}
+    needs: version
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - x86_64-unknown-linux-musl
+          - aarch64-unknown-linux-musl
+    steps:
+      - uses: actions/checkout@v7
+
+      # maturin-action builds a musl target in a rust-musl-cross container.
+      - name: Build the wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: musllinux_1_2
+          maturin-version: "1.15.0"
+          args: --release --locked --out dist
+          sccache: "true"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist-wheel-musllinux-${{ matrix.target }}
+          path: dist
+          if-no-files-found: error
+
+  windows:
+    name: wheel for x86_64-pc-windows-msvc
+    needs: version
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build the wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: x86_64-pc-windows-msvc
+          maturin-version: "1.15.0"
+          args: --release --locked --out dist
+          sccache: "true"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist-wheel-windows-x86_64-pc-windows-msvc
+          path: dist
+          if-no-files-found: error
+
+  sdist:
+    name: sdist
+    needs: version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build the sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          maturin-version: "1.15.0"
+          args: --out dist
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist-sdist
+          path: dist
+          if-no-files-found: error
+
+  publish:
+    name: publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [macos, manylinux, musllinux, windows, sdist]
+    # A manual run builds and uploads every artifact. Only a tag publishes.
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/uvxy
+    permissions:
+      # Trusted publishing needs this permission. The workflow holds no API
+      # token.
+      id-token: write
+    steps:
+      - name: Collect every wheel and the sdist
+        uses: actions/download-artifact@v8
+        with:
+          # Every build job names its artifact with a "dist-" prefix. One
+          # glob therefore collects the wheels and the sdist.
+          pattern: dist-*
+          path: dist
+          merge-multiple: true
+
+      # A reader of the run log needs the file list. It proves that all seven
+      # wheels and the sdist arrived.
+      - name: List the distributions
+        run: ls -l dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

uvxy-0.0.1/.gitignore

@@ -0,0 +1,3 @@
+/target
+*.whl
+dist/

uvxy-0.0.1/CONTEXT.md

@@ -0,0 +1,31 @@
+# uvxy
+
+`uvxy` is a wrapper around `uvx`. `uvx` infers a package name from the command
+you type. When the two names differ, you must pass `--from`. `uvxy` reads that
+`--from` value from a configuration file instead.
+
+## Language
+
+**Command**:
+The executable name that a Python package installs, and the name a user types.
+_Avoid_: tool name, script, entry point
+
+**Package Spec**:
+The value that `uvxy` supplies to `uvx --from`. It names a package, and it can
+also constrain a version.
+_Avoid_: package name, requirement, distribution
+
+**Mapping**:
+One entry in the configuration file. A mapping connects a command to a package
+spec.
+_Avoid_: alias, override, rule
+
+**Passthrough Argument**:
+An argument that `uvxy` sends to uvx without a change. Every argument is a
+passthrough argument, except a namespaced flag.
+_Avoid_: forwarded arg, pass-along, proxied argument
+
+**Namespaced Flag**:
+A flag that starts with `--uvxy-`. `uvxy` reads it and removes it. `uvxy` never
+sends it to uvx.
+_Avoid_: own flag, internal flag, private flag

uvxy-0.0.1/Cargo.lock

@@ -0,0 +1,253 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "anyhow"
+version = "1.0.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "indexmap"
+version = "2.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07aa2048142242915a31d35844fb311e0e53fcca590c3a0a40dcf1b841fa09eb"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_spanned"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6662b5879511e06e8999a8a235d848113e942c9124f211511b16466ee2995f26"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6275cddf4610d1775e6d1fe9469b2e77d0f39fd98fb7450901b821e0c53649f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom",
+ "once_cell",
+ "rustix",
+ "windows-sys",
+]
+
+[[package]]
+name = "toml"
+version = "1.1.4+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3aace63f4bbcdfc2c965b059de67119c89c4017a70d633be6c104910f67056f5"
+dependencies = [
+ "indexmap",
+ "serde_core",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_parser",
+ "toml_writer",
+ "winnow",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "1.1.1+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.1.3+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d38ac1cf9b95face32296c0a3ede1fdc270627c9d9c02a7274dd6d960dc4d56"
+dependencies = [
+ "winnow",
+]
+
+[[package]]
+name = "toml_writer"
+version = "1.1.2+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "uvxy"
+version = "0.0.1"
+dependencies = [
+ "anyhow",
+ "tempfile",
+ "toml",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "winnow"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"