uv-pack 0.0.1__tar.gz → 0.1.0__tar.gz

uv_pack-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.3
+Name: uv-pack
+Version: 0.1.0
+Summary: Pack you uv environment for offline usage.
+Author: David Muhr
+Author-email: David Muhr <muhrdavid+github@gmail.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Utilities
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+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 :: Only
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Typing :: Typed
+Requires-Dist: packaging>=24.0
+Requires-Dist: requests>=2
+Requires-Dist: typer>=0.19
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+uv-pack
+=======
+
+[![Check Status](https://github.com/davnn/uv-pack/actions/workflows/check.yml/badge.svg)](https://github.com/davnn/uv-pack/actions?query=workflow%3Acheck)
+[![Semantic Versions](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--versions-e10079.svg)](https://github.com/davnn/uv-pack/releases)
+
+Bundle a locked `uv` environment into a self-contained, offline-installable directory.
+The output includes pinned requirements, third-party wheels, locally built wheels,
+and a portable Python interpreter.
+
+What it does
+------------
+- Exports locked requirements from your `uv` lock file.
+- Downloads third-party wheels into `pack/wheels/`.
+- Builds local workspace packages into `pack/vendor/`.
+- Downloads a python-build-standalone archive into `pack/python/` (unless you skip the `python` step).
+- Writes `unpack.sh`, `unpack.ps1`, and `unpack.cmd` to unpack the resulting venv offline.
+
+Install
+-------
+
+Install `uv-pack` as a dev-dependency.
+
+```bash
+uv add --dev uv-pack
+```
+
+Once installed, run using:
+
+```bash
+uv run uv-pack --help
+```
+
+You can also use ``uv-pack`` as a tool.
+
+```bash
+# specify the python version!
+uv tool run --python 3.12 uv-pack --help
+# or using uvx (equivalent)
+uvx --python 3.12 uv-pack --help
+```
+
+CLI
+---
+
+```bash
+uv-pack [STEPS...]
+```
+
+Options:
+- `STEPS`: subset of pipeline steps (default: `clean export download build python`)
+- `-s, --skip`: skip a pipeline step (can be supplied multiple times)
+- `-o, --output-directory`: path to output directory (default: `./pack`)
+- `-v, --verbose`: show more detailed pack progress logging
+- `--uv-build`: extra args passed to `uv build`
+- `--uv-export`: extra args passed to `uv export`
+- `--pip-download`: extra args passed to `pip download`
+
+Notes:
+- The CLI is structured into five pipeline steps, see description below.
+- Extra args are split on whitespace (for example: `--uv-export "--dev --all-extras"`).
+
+Pipeline steps:
+- `clean`: remove the output directory
+- `export`: write `requirements.txt` files for third-party and local packages
+- `download`: download third-party wheels
+- `build`: build local wheels and compile the combined requirements file
+- `python`: download a python-build-standalone archive for the current Python version and platform
+
+Example
+-------
+```bash
+# run the entire pipeline (default) with verbose outputs
+uv-pack --verbose
+# only clean and export the requirements
+uv-pack clean export
+```
+
+Output layout
+-------------
+```
+pack/
+  requirements.txt
+  wheels/
+    requirements.txt
+  vendor/
+    requirements.txt
+  python/   # (omitted when the python step is skipped)
+  unpack.sh
+  unpack.ps1
+  unpack.cmd
+  .gitignore
+  README.md
+```
+
+Unpack and install offline
+--------------------------
+
+POSIX (sh/bash/zsh):
+
+```bash
+./pack/unpack.sh
+```
+
+PowerShell:
+
+```powershell
+.\pack\unpack.ps1
+```
+
+Windows cmd:
+
+```cmd
+.\pack\unpack.cmd
+```
+
+All scripts also accept `VENV_DIR`, `PY_DEST` and `BASE_PY` environment variables.
+Use `BASE_PY` when you skipped the `python` step during packing to provide a system
+python interpreter. `VENV_DIR` (default = `.venv`) and `PY_DEST` (default = `.python`)
+can be used to customize the target python and venv directory.
+
+Configuration
+-------------
+
+`UV_PYTHON_INSTALL_MIRROR` can override the GitHub API endpoint to retrieve the
+Python releases, default is:
+<https://api.github.com/repos/astral-sh/python-build-standalone/releases/latest>.
+
+`GITHUB_TOKEN` can be used to authenticate requests to the GitHub API to
+prevent possible rate-limiting.
+
+Limitations
+-----------
+
+- The pack process must happen in the ``pyproject.toml`` or ``uv.toml`` directory, typically the repository root,
+  because ``uv`` exports relative paths to the project root.
+- The build platform is expected to equal the usage platform; it is currently not possible to pack an environment
+  for a different platform.
+- The project Python version is ignored when running `uv-pack` as a tool (`uv tool run` or `uvx`) and should be
+  specified using `uv tool run --python 3.11 uv-pack` or `uvx --python 3.11 uv-pack`, see
+  [uv#uv5951](https://github.com/astral-sh/uv/issues/5951) and [uv#8206](https://github.com/astral-sh/uv/issues/8206).
+- The download process can be slow because ``pip download`` is used as there is no native (parallel) uv download
+  option available for wheels, see [uv#3163](https://github.com/astral-sh/uv/issues/3163).
+
+FAQ
+-----------
+
+#### How do I pass extra options to `uv export` or another command?
+
+Use `--uv-export` to forward arguments, for example:
+
+- ``uv-pack --uv-export "--package $MY_PACKAGE"`` to export only a specific workspace package
+- ``uv-pack --uv-export "--locked  --dev"`` to include dev-deps and ensure an up-to-date lock file
+- ``uv-pack --uv-export "--all-extras"`` to include all extra dependencies
+
+The same is true for ``--uv-build`` and ``--pip-download`` arguments.
+
+#### How do I specify index-urls and extra-index-urls?
+
+The index urls set in ``pyproject.toml`` and ``uv.toml`` are not configured by default for the wheel
+download (``pip download``), you can specify them as:
+
+- ``uv-pack --pip-download "--index-url $MY_INDEX --extra-index-url $MY_EXTRA_INDEX"``
+
+#### How do I skip bundling Python?
+
+Skip the `python` step: ``uv-pack --skip python``. When unpacking, set `BASE_PY` to a system Python path.
+
+#### How do I rerun without deleting the existing pack directory?
+
+Skip the `clean` step: ``uv-pack --skip clean``. Note that this automatically re-uses downloaded wheels
+and the downloaded Python interpreter.
+
+#### How do I only re-build my package if my pack is already complete?
+
+Run only ``uv-pack build``.

uv_pack-0.1.0/README.md

@@ -0,0 +1,176 @@
+uv-pack
+=======
+
+[![Check Status](https://github.com/davnn/uv-pack/actions/workflows/check.yml/badge.svg)](https://github.com/davnn/uv-pack/actions?query=workflow%3Acheck)
+[![Semantic Versions](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--versions-e10079.svg)](https://github.com/davnn/uv-pack/releases)
+
+Bundle a locked `uv` environment into a self-contained, offline-installable directory.
+The output includes pinned requirements, third-party wheels, locally built wheels,
+and a portable Python interpreter.
+
+What it does
+------------
+- Exports locked requirements from your `uv` lock file.
+- Downloads third-party wheels into `pack/wheels/`.
+- Builds local workspace packages into `pack/vendor/`.
+- Downloads a python-build-standalone archive into `pack/python/` (unless you skip the `python` step).
+- Writes `unpack.sh`, `unpack.ps1`, and `unpack.cmd` to unpack the resulting venv offline.
+
+Install
+-------
+
+Install `uv-pack` as a dev-dependency.
+
+```bash
+uv add --dev uv-pack
+```
+
+Once installed, run using:
+
+```bash
+uv run uv-pack --help
+```
+
+You can also use ``uv-pack`` as a tool.
+
+```bash
+# specify the python version!
+uv tool run --python 3.12 uv-pack --help
+# or using uvx (equivalent)
+uvx --python 3.12 uv-pack --help
+```
+
+CLI
+---
+
+```bash
+uv-pack [STEPS...]
+```
+
+Options:
+- `STEPS`: subset of pipeline steps (default: `clean export download build python`)
+- `-s, --skip`: skip a pipeline step (can be supplied multiple times)
+- `-o, --output-directory`: path to output directory (default: `./pack`)
+- `-v, --verbose`: show more detailed pack progress logging
+- `--uv-build`: extra args passed to `uv build`
+- `--uv-export`: extra args passed to `uv export`
+- `--pip-download`: extra args passed to `pip download`
+
+Notes:
+- The CLI is structured into five pipeline steps, see description below.
+- Extra args are split on whitespace (for example: `--uv-export "--dev --all-extras"`).
+
+Pipeline steps:
+- `clean`: remove the output directory
+- `export`: write `requirements.txt` files for third-party and local packages
+- `download`: download third-party wheels
+- `build`: build local wheels and compile the combined requirements file
+- `python`: download a python-build-standalone archive for the current Python version and platform
+
+Example
+-------
+```bash
+# run the entire pipeline (default) with verbose outputs
+uv-pack --verbose
+# only clean and export the requirements
+uv-pack clean export
+```
+
+Output layout
+-------------
+```
+pack/
+  requirements.txt
+  wheels/
+    requirements.txt
+  vendor/
+    requirements.txt
+  python/   # (omitted when the python step is skipped)
+  unpack.sh
+  unpack.ps1
+  unpack.cmd
+  .gitignore
+  README.md
+```
+
+Unpack and install offline
+--------------------------
+
+POSIX (sh/bash/zsh):
+
+```bash
+./pack/unpack.sh
+```
+
+PowerShell:
+
+```powershell
+.\pack\unpack.ps1
+```
+
+Windows cmd:
+
+```cmd
+.\pack\unpack.cmd
+```
+
+All scripts also accept `VENV_DIR`, `PY_DEST` and `BASE_PY` environment variables.
+Use `BASE_PY` when you skipped the `python` step during packing to provide a system
+python interpreter. `VENV_DIR` (default = `.venv`) and `PY_DEST` (default = `.python`)
+can be used to customize the target python and venv directory.
+
+Configuration
+-------------
+
+`UV_PYTHON_INSTALL_MIRROR` can override the GitHub API endpoint to retrieve the
+Python releases, default is:
+<https://api.github.com/repos/astral-sh/python-build-standalone/releases/latest>.
+
+`GITHUB_TOKEN` can be used to authenticate requests to the GitHub API to
+prevent possible rate-limiting.
+
+Limitations
+-----------
+
+- The pack process must happen in the ``pyproject.toml`` or ``uv.toml`` directory, typically the repository root,
+  because ``uv`` exports relative paths to the project root.
+- The build platform is expected to equal the usage platform; it is currently not possible to pack an environment
+  for a different platform.
+- The project Python version is ignored when running `uv-pack` as a tool (`uv tool run` or `uvx`) and should be
+  specified using `uv tool run --python 3.11 uv-pack` or `uvx --python 3.11 uv-pack`, see
+  [uv#uv5951](https://github.com/astral-sh/uv/issues/5951) and [uv#8206](https://github.com/astral-sh/uv/issues/8206).
+- The download process can be slow because ``pip download`` is used as there is no native (parallel) uv download
+  option available for wheels, see [uv#3163](https://github.com/astral-sh/uv/issues/3163).
+
+FAQ
+-----------
+
+#### How do I pass extra options to `uv export` or another command?
+
+Use `--uv-export` to forward arguments, for example:
+
+- ``uv-pack --uv-export "--package $MY_PACKAGE"`` to export only a specific workspace package
+- ``uv-pack --uv-export "--locked  --dev"`` to include dev-deps and ensure an up-to-date lock file
+- ``uv-pack --uv-export "--all-extras"`` to include all extra dependencies
+
+The same is true for ``--uv-build`` and ``--pip-download`` arguments.
+
+#### How do I specify index-urls and extra-index-urls?
+
+The index urls set in ``pyproject.toml`` and ``uv.toml`` are not configured by default for the wheel
+download (``pip download``), you can specify them as:
+
+- ``uv-pack --pip-download "--index-url $MY_INDEX --extra-index-url $MY_EXTRA_INDEX"``
+
+#### How do I skip bundling Python?
+
+Skip the `python` step: ``uv-pack --skip python``. When unpacking, set `BASE_PY` to a system Python path.
+
+#### How do I rerun without deleting the existing pack directory?
+
+Skip the `clean` step: ``uv-pack --skip clean``. Note that this automatically re-uses downloaded wheels
+and the downloaded Python interpreter.
+
+#### How do I only re-build my package if my pack is already complete?
+
+Run only ``uv-pack build``.

{uv_pack-0.0.1 → uv_pack-0.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uv-pack"
-version = "0.0.1"
+version = "0.1.0"
 description = "Pack you uv environment for offline usage."
 readme = "README.md"
 homepage = "https://github.com/davnn/uv-pack"
@@ -28,14 +28,15 @@ classifiers = [
     "Typing :: Typed"
 ]
 dependencies = [
-    "packaging>=26.0",
-    "requests>=2.32.5",
-    "typer>=0.21.1",
+    "packaging>=24.0",
+    "requests>=2",
+    "typer>=0.19",
 ]
 
 [dependency-groups]
 dev = [
     "bandit>=1.9.3",
+    "black>=26.1.0",
     "notebook>=7.5.2",
     "pre-commit>=4.5.1",
     "pyright>=1.1.408",
@@ -59,4 +60,18 @@ extend-exclude = [".github"]
 target-version = "py310"
 line-length = 120
 lint.select = ["ALL"]
-lint.ignore = ["D401", "D213", "D211", "S603", "PLR0913", "PERF402", "FBT001", "FBT003", "B008", "PGH003"]
+lint.ignore = [
+    "ANN401",
+    "B008",
+    "D203",
+    "D211",
+    "D213",
+    "D401",
+    "E731",
+    "FBT001",
+    "FBT003",
+    "PERF402",
+    "PGH003",
+    "PLR0913",
+    "S603",
+]

uv_pack-0.1.0/src/uv_pack/__init__.py

@@ -0,0 +1,258 @@
+"""uv-pack: Bundle a locked uv environment into an offline-installable bundle.
+
+Pipeline:
+1. Clean the output directory
+2. Export locked requirements via uv
+3. Download third-party wheels into ./wheels
+4. Build local workspace packages into ./vendor
+5. Download a python interpreter to ./python
+
+Result:
+pack/
+├── requirements.txt
+├── wheels/              # third-party wheels
+│   └── requirements.txt # index packages
+├── vendor/              # locally built wheels
+│   └── requirements.txt # local packages
+├── python/              # python interpreter
+├── unpack.sh
+├── unpack.ps1
+├── unpack.bat
+├── .gitignore
+└── README.md
+"""
+
+import shutil
+from collections.abc import Iterable
+from enum import Enum
+from pathlib import Path
+
+import typer
+
+from uv_pack._build import build_requirements, build_src_wheel
+from uv_pack._download import download_third_party_wheels
+from uv_pack._export import export_local_requirements, export_requirements
+from uv_pack._files import PackLayout
+from uv_pack._logging import ConsoleError, Verbosity, console_print, set_verbosity
+from uv_pack._process import run_step
+from uv_pack._python import download_latest_python_build
+from uv_pack._scripts import copy_unpack_scripts
+
+# -----------------------------------------------------------------------------
+# CLI setup
+# -----------------------------------------------------------------------------
+
+app: typer.Typer = typer.Typer(add_completion=True)
+
+
+def main() -> None:
+    """Main entry point for uv-pack CLI."""
+    try:
+        app()
+    except ConsoleError:
+        raise  # already formatted for user
+    except KeyboardInterrupt as err:
+        console_print("[yellow]Interrupted by user[/yellow]")
+        raise typer.Exit(130) from err
+    except Exception as err:
+        msg = (
+            "[bold red]✘ An unexpected internal error occurred, please try again or"
+            " open an issue https://github.com/davnn/uv-pack/issues.[/bold red]"
+        )
+        raise ConsoleError(msg) from err
+
+
+# -----------------------------------------------------------------------------
+# Step model
+# -----------------------------------------------------------------------------
+
+
+class Step(str, Enum):
+    """Steps to be performed in the pack pipeline."""
+
+    clean = "clean"
+    export = "export"
+    download = "download"
+    build = "build"
+    python = "python"
+
+
+PIPELINE_ORDER: tuple[Step, ...] = (
+    Step.clean,
+    Step.export,
+    Step.download,
+    Step.build,
+    Step.python,
+)
+
+
+# -----------------------------------------------------------------------------
+# Helper operations
+# -----------------------------------------------------------------------------
+
+
+def _additional_cli_args(cmd_name: str) -> str:
+    return f"Additional command line arguments to be provided to '{cmd_name}'"
+
+
+def _normalize_steps(
+    steps: Iterable[Step] | None,
+    skip: Iterable[Step] | None,
+) -> list[Step]:
+    selected = set(PIPELINE_ORDER) if steps is None else set(steps)
+    selected = selected.difference([] if skip is None else set(skip))
+    return [step for step in PIPELINE_ORDER if step in selected]
+
+
+def _raise_requirement_txt_missing(path: Path) -> None:
+    if not path.exists():
+        msg = f"[bold red]✘ No requirements file found:[/bold red] '{path}', did you skip the 'export' step?"
+        raise ConsoleError(msg)
+
+
+# -----------------------------------------------------------------------------
+# Orchestration command
+# -----------------------------------------------------------------------------
+
+
+@app.command()
+def pack(
+    *,
+    steps: list[Step] | None = typer.Argument(
+        PIPELINE_ORDER,
+        help="Pipeline steps to run (multiple can be whitespace-separated)",
+    ),
+    skip: list[Step] | None = typer.Option(
+        None,
+        "--skip",
+        "-s",
+        help="Pipeline steps to skip (can be supplied multiple times)",
+    ),
+    output_directory: Path = typer.Option(
+        Path("./pack"),
+        "--output-directory",
+        "-o",
+        help="Path to output directory",
+    ),
+    uv_export: str = typer.Option(
+        default="",
+        help=_additional_cli_args("uv export"),
+    ),
+    pip_download: str = typer.Option(
+        default="",
+        help=_additional_cli_args("pip download"),
+    ),
+    uv_build: str = typer.Option(
+        default="",
+        help=_additional_cli_args("uv build"),
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable verbose output",
+    ),
+) -> None:
+    """Pack a locked uv environment into an offline-installable bundle."""
+    set_verbosity(Verbosity.verbose if verbose else Verbosity.normal)
+    selected_steps = _normalize_steps(steps, skip)
+    console_print(
+        f"[dim]Running steps:[/dim] {[step.value for step in selected_steps]}",
+    )
+
+    if Step.clean in selected_steps:
+        with run_step("clean"):
+            shutil.rmtree(output_directory, ignore_errors=True)
+
+        console_print(
+            f"[green]✔ Cleaned[/green] output directory '{output_directory}'",
+            level=Verbosity.verbose,
+        )
+
+    # initialize pack directory structure and copy unpack scripts
+    pack = PackLayout.create(output_directory=output_directory)
+    copy_unpack_scripts(output_directory=output_directory)
+
+    if Step.export in selected_steps:
+        with run_step("export"):
+            export_requirements(
+                requirements_file=pack.requirements_export_txt,
+                other_args=uv_export,
+            )
+            export_local_requirements(
+                requirements_file=pack.requirements_local_txt,
+                other_args=uv_export,
+            )
+        console_print(
+            f"[green]✔ Exported[/green] requirements '{pack.requirements_export_txt}'",
+            level=Verbosity.verbose,
+        )
+        console_print(
+            f"[green]✔ Exported[/green] requirements '{pack.requirements_local_txt}'",
+            level=Verbosity.verbose,
+        )
+
+    if Step.download in selected_steps:
+        _raise_requirement_txt_missing(pack.requirements_export_txt)
+
+        with run_step("download"):
+            download_third_party_wheels(
+                requirements_file=pack.requirements_export_txt,
+                wheels_directory=pack.wheels_dir,
+                other_args=pip_download,
+            )
+
+    if Step.build in selected_steps:
+        _raise_requirement_txt_missing(pack.requirements_local_txt)
+        _raise_requirement_txt_missing(pack.requirements_export_txt)
+
+        # show the progress for each package in verbose mode, otherwise a single progress report is shown
+        with run_step("build", should_run=not verbose):
+            for line in pack.requirements_local_txt.read_text(
+                encoding="utf-8",
+            ).splitlines():
+                with run_step("build", should_run=verbose):
+                    build_src_wheel(
+                        source_path=Path(line),
+                        out_path=pack.vendor_dir,
+                        other_args=uv_build,
+                    )
+                console_print(
+                    f"[green]✔ Built[/green] wheel: '{line}'",
+                    level=Verbosity.verbose,
+                )
+
+            for sdist in pack.wheels_dir.glob("*.tar.gz"):
+                with run_step("build", should_run=verbose):
+                    build_src_wheel(
+                        source_path=sdist,
+                        out_path=pack.wheels_dir,
+                        other_args=uv_build,
+                    )
+                    sdist.unlink(missing_ok=True)
+                console_print(
+                    f"[green]✔ Built[/green] wheel: '{sdist}'",
+                    level=Verbosity.verbose,
+                )
+
+            build_requirements(
+                requirements_txt=pack.requirements_txt,
+                requirements_export_txt=pack.requirements_export_txt,
+                vendor_directory=pack.vendor_dir,
+            )
+            console_print(
+                f"[green]✔ Built[/green] requirements: '{pack.requirements_txt}'",
+                level=Verbosity.verbose,
+            )
+
+    if Step.python in selected_steps:
+        pack.python_dir.mkdir(exist_ok=True)
+        python_path = download_latest_python_build(
+            dest_dir=pack.python_dir,
+        )
+        console_print(
+            f"[green]✔ Python[/green] archive: '{python_path}'",
+            level=Verbosity.verbose,
+        )
+
+    console_print("[green]✔ Done[/green]")