zuv 0.0.1__tar.gz

zuv-0.0.1/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+/test/app/

zuv-0.0.1/.python-version

@@ -0,0 +1 @@
+3.14

zuv-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HamzaYslmn
+
+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.

zuv-0.0.1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: zuv
+Version: 0.0.1
+Summary: Bundle any uv project into a single runnable .py file.
+Project-URL: Homepage, https://github.com/HamzaYslmn/zuv
+Project-URL: Repository, https://github.com/HamzaYslmn/zuv
+Project-URL: Issues, https://github.com/HamzaYslmn/zuv/issues
+Author: HamzaYslmn
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bundle,packaging,pep723,single-file,uv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# zuv
+
+Bundle any `uv` project into a single runnable `.py` file. End users only need `uv` installed.
+
+```sh
+uv run app.py
+```
+
+That's it. The bundled script is a [PEP 723](https://peps.python.org/pep-0723/) self-contained script. On first run it creates a `.venv` next to itself, installs the project's dependencies into it via `uv pip install`, extracts the bundled source, and runs the entry point. Subsequent runs reuse the cache.
+
+## Install
+
+```sh
+uv tool install zuv
+```
+
+## Project layout
+
+Your project needs a `pyproject.toml` and a `src/main.py` with a `main()` function:
+
+```
+my-project/
+  pyproject.toml         # [project] dependencies = [...]
+  src/
+    main.py              # def main(): ...
+```
+
+## Build
+
+```sh
+zuv build ./my-project
+# -> ./dist/my-project.py
+```
+
+`zuv build` wipes `./dist/` first, then writes a fresh single-file script. Override the path with `-o` and the entry point with `-e module:function` (default `main:main`).
+
+### Build the included examples
+
+```sh
+zuv build examples/bigtest -o dist/bigtest.py
+zuv build examples/fastapi -o dist/fastapi.py
+```
+
+Then:
+
+```sh
+uv run dist/bigtest.py
+uv run dist/fastapi.py
+```
+
+## Sibling overrides
+
+The script `chdir`s to its own folder before invoking your entry point, so any file you drop next to the `.py` is visible to user code as a cwd-relative path:
+
+| File next to the bundle | Effect |
+| --- | --- |
+| `.env` | `load_dotenv(".env")` picks it up |
+| `frontend/` | `Path("frontend")` resolves to the override |
+| `.venv/` | shared dep cache (auto-created on first run) |
+| `.zuv/` | extracted source cache (per build hash) |
+
+This lets you ship a single `.py` and let users tweak config or assets next to it without rebuilding.
+
+## How it works
+
+The output `.py` is a normal Python script with three parts:
+
+1. A `#!/usr/bin/env -S uv run --script` shebang plus a PEP 723 metadata block declaring the Python version.
+2. An `_ZUV_ENV` dict with the entry point and the project's dependency list, and a `_ZUV_PAYLOAD` base85-encoded `tar.gz` of `src/`.
+3. A small loader that bootstraps the venv, extracts the source, sets `ZUV_DIR` / `ZUV_CWD` / `ZUV_CACHE`, and imports the entry callable.
+
+Deps are NOT bundled inside the `.py`. uv handles them at runtime, so the bundle stays tiny (under 15 KB even for a FastAPI app) and binary wheels work natively without extraction tricks.
+
+## Layout
+
+```
+src/
+  pyproject.toml
+  zuv/
+    cli.py                 # zuv build CLI
+    builder.py             # tar.gz + base85 + emit .py
+    _loader_template.py    # runtime loader embedded in every output
+    constants.py
+examples/
+  bigtest/                 # rich + pydantic smoke test
+  fastapi/                 # FastAPI + uvicorn web app
+```

zuv-0.0.1/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "zuv"
+version = "0.0.1"
+description = "Bundle any uv project into a single runnable .py file."
+requires-python = ">=3.13"
+dependencies = []
+dynamic = ["readme"]
+license = "MIT"
+authors = [{name = "HamzaYslmn"}]
+keywords = ["uv", "bundle", "pep723", "packaging", "single-file"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/HamzaYslmn/zuv"
+Repository = "https://github.com/HamzaYslmn/zuv"
+Issues = "https://github.com/HamzaYslmn/zuv/issues"
+
+[project.scripts]
+zuv = "zuv.cli:main"
+
+[build-system]
+requires = ["hatchling", "hatch-fancy-pypi-readme"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["zuv"]
+
+# README lives at repo root; pull it in at build time via a relative reference.
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "../README.md"

zuv-0.0.1/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.13"
+
+[[package]]
+name = "zuv"
+version = "0.0.1"
+source = { editable = "." }

zuv-0.0.1/zuv/__init__.py

@@ -0,0 +1,3 @@
+from .__version__ import __version__
+
+__all__ = ["__version__"]

zuv-0.0.1/zuv/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

zuv-0.0.1/zuv/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

zuv-0.0.1/zuv/_loader_template.py

@@ -0,0 +1,106 @@
+"""Runtime loader embedded inside every .zuv file.
+
+Built into the .zuv as plain source. uv executes the file via PEP 723 with an
+empty dependency list, so this loader runs in a minimal env (stdlib only).
+
+On first run, the loader:
+  1. Materializes a `.venv` next to the .zuv using `uv venv` + `uv pip install`.
+  2. Extracts the embedded user source tarball to `<dir>/.zuv/<name>_<hash>/`.
+  3. Writes a `.zuv-ready` marker.
+On every run:
+  4. Prepends the venv's site-packages and the extracted source dir to sys.path.
+  5. chdirs to the .zuv's folder so user code can use cwd-relative paths
+     (e.g. `load_dotenv('.env')`, `open('frontend/index.html')`).
+  6. Exports ZUV_DIR / ZUV_CWD / ZUV_CACHE env vars.
+  7. Imports the entry callable and invokes it.
+"""
+import base64
+import io
+import os
+import subprocess
+import sys
+import tarfile
+from importlib import import_module
+from pathlib import Path
+
+# Builder injects these literals above the loader body:
+#   _ZUV_ENV: dict   (entry, build_id, build_tag, dependencies)
+#   _ZUV_PAYLOAD: bytes  (base85 of the tar.gz of the user source tree)
+
+
+def _venv_site_packages(venv_dir: Path) -> Path:
+    if os.name == "nt":
+        return venv_dir / "Lib" / "site-packages"
+    py = f"python{sys.version_info.major}.{sys.version_info.minor}"
+    return venv_dir / "lib" / py / "site-packages"
+
+
+def _uv(*args: str) -> None:
+    proc = subprocess.run(["uv", *args], capture_output=True, text=True)
+    if proc.returncode != 0:
+        sys.stderr.write(proc.stdout + proc.stderr)
+        raise SystemExit(f"error: uv {' '.join(args)} failed (exit {proc.returncode})")
+
+
+def _ensure_venv(venv_dir: Path, deps: list[str]) -> None:
+    if not (venv_dir / "pyvenv.cfg").exists():
+        _uv("venv", str(venv_dir), "--python", sys.executable, "--quiet")
+    if deps:
+        py = venv_dir / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+        _uv("pip", "install", "--python", str(py), "--quiet", *deps)
+
+
+def _extract(payload: bytes, target: Path) -> None:
+    tmp = target.with_name(target.name + ".tmp")
+    if tmp.exists():
+        import shutil
+        shutil.rmtree(tmp)
+    tmp.mkdir(parents=True)
+    with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as tf:
+        tf.extractall(tmp, filter="data")
+    if target.exists():
+        import shutil
+        shutil.rmtree(target)
+    tmp.rename(target)
+
+
+def _import_callable(target: str):
+    module_name, _, attr = target.partition(":")
+    obj = import_module(module_name)
+    for part in attr.split(".") if attr else ():
+        obj = getattr(obj, part)
+    return obj
+
+
+def _run() -> int:
+    env = _ZUV_ENV  # noqa: F821 - injected by builder
+    archive_path = Path(sys.argv[0]).resolve()
+    arch_dir = archive_path.parent
+
+    venv_dir = arch_dir / ".venv"
+    cache = arch_dir / ".zuv" / f"{archive_path.stem}_{env['build_id'][:12]}"
+    marker = cache / ".zuv-ready"
+    deps = env.get("dependencies", [])
+
+    if not marker.exists():
+        _ensure_venv(venv_dir, deps)
+        _extract(base64.b85decode(_ZUV_PAYLOAD), cache)  # noqa: F821 - injected by builder
+        marker.write_text("ok")
+    elif deps and not (venv_dir / "pyvenv.cfg").exists():
+        _ensure_venv(venv_dir, deps)
+
+    sys.path.insert(0, str(cache))
+    sp = _venv_site_packages(venv_dir)
+    if sp.is_dir():
+        sys.path.insert(0, str(sp))
+
+    os.environ["ZUV_DIR"] = str(arch_dir)
+    os.environ["ZUV_CWD"] = str(arch_dir)
+    os.environ["ZUV_CACHE"] = str(cache)
+    os.chdir(arch_dir)
+
+    return int(_import_callable(env["entry"])() or 0)
+
+
+if __name__ == "__main__":
+    sys.exit(_run())

zuv-0.0.1/zuv/builder.py

@@ -0,0 +1,128 @@
+"""Build a runnable .py from a project (pyproject.toml + src/main.py).
+
+The output is a PEP 723 script that uv executes. It does NOT bundle deps —
+instead it embeds a list of dependencies; the runtime loader materializes a
+`.venv` next to the script on first run and `uv pip install`s them there.
+
+Build steps:
+  1. Read deps from <project>/pyproject.toml.
+  2. tar.gz the <project>/src/ tree.
+  3. Emit <output> = shebang + latin-1 coding decl + PEP 723 header +
+     ENV literal + raw bytes payload literal + loader source.
+"""
+import base64
+import compileall
+import hashlib
+import io
+import platform
+import shutil
+import sys
+import tarfile
+import tempfile
+import tomllib
+from pathlib import Path
+from stat import S_IXGRP, S_IXOTH, S_IXUSR
+
+from .__version__ import __version__
+from .constants import PAYLOAD_VAR, ZUV_SHEBANG
+
+PEP723_HEADER = """\
+# /// script
+# requires-python = ">={py}"
+# dependencies = []
+# ///
+"""
+
+
+def _build_tag() -> dict[str, str]:
+    return {
+        "system": platform.system().lower(),
+        "machine": platform.machine().lower(),
+        "python": f"{sys.version_info.major}.{sys.version_info.minor}",
+    }
+
+
+def _read_deps(pyproject: Path) -> list[str]:
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    return list(data.get("project", {}).get("dependencies", []))
+
+
+def _pre_compile(src_dir: Path) -> Path:
+    """Copy src/ to a temp dir and pre-compile .pyc files into it."""
+    tmp = Path(tempfile.mkdtemp(prefix="zuv-src-"))
+    shutil.copytree(src_dir, tmp, dirs_exist_ok=True)
+    compileall.compile_dir(tmp, quiet=1, workers=0)
+    return tmp
+
+
+def _make_tarball(root: Path) -> tuple[bytes, str]:
+    buf = io.BytesIO()
+    hasher = hashlib.sha256()
+    with tarfile.open(fileobj=buf, mode="w:gz", compresslevel=9) as tf:
+        for path in sorted(root.rglob("*"), key=str):
+            if not path.is_file():
+                continue
+            rel = path.relative_to(root).as_posix()
+            hasher.update(rel.encode("utf-8"))
+            hasher.update(path.read_bytes())
+            tf.add(path, arcname=rel)
+    return buf.getvalue(), hasher.hexdigest()
+
+
+def _loader_source() -> str:
+    return Path(__file__).with_name("_loader_template.py").read_text(encoding="utf-8")
+
+
+def build_pyz(project_dir: Path, output: Path, entry: str | None) -> int:
+    pyproject = project_dir / "pyproject.toml"
+    src_dir = project_dir / "src"
+
+    if not pyproject.exists():
+        print(f"error: no pyproject.toml in {project_dir}", file=sys.stderr)
+        return 2
+    if not (src_dir / "main.py").exists():
+        print(f"error: no src/main.py in {project_dir}", file=sys.stderr)
+        return 2
+
+    if output.parent.name == "dist" and output.parent.exists():
+        print(f"cleaning {output.parent}...")
+        shutil.rmtree(output.parent)
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    deps = _read_deps(pyproject)
+    print(f"deps: {len(deps)} ({', '.join(deps) if deps else 'none'})")
+
+    print("pre-compiling source...")
+    staging = _pre_compile(src_dir)
+    try:
+        print("packing source tar.gz...")
+        payload, build_id = _make_tarball(staging)
+    finally:
+        shutil.rmtree(staging, ignore_errors=True)
+
+    env = {
+        "zuv_version": __version__,
+        "entry": entry or "main:main",
+        "build_id": build_id,
+        "build_tag": _build_tag(),
+        "dependencies": deps,
+    }
+    py_req = f"{sys.version_info.major}.{sys.version_info.minor}"
+    b85 = base64.b85encode(payload).decode("ascii")
+
+    parts = [
+        ZUV_SHEBANG,
+        PEP723_HEADER.format(py=py_req),
+        f"_ZUV_ENV = {env!r}\n",
+        f"{PAYLOAD_VAR} = (\n",
+    ]
+    for i in range(0, len(b85), 80):
+        parts.append(f'    b"{b85[i:i+80]}"\n')
+    parts.append(")\n")
+    parts.append(_loader_source())
+
+    output.write_text("".join(parts), encoding="utf-8")
+    output.chmod(output.stat().st_mode | S_IXUSR | S_IXGRP | S_IXOTH)
+
+    print(f"built {output} ({output.stat().st_size / 1024:.1f} KB)")
+    return 0

zuv-0.0.1/zuv/cli.py

@@ -0,0 +1,57 @@
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .builder import build_pyz
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="zuv",
+        description="Build click-and-run Python apps powered by uv.",
+    )
+    parser.add_argument("--version", action="version", version=f"zuv {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    build = sub.add_parser("build", help="Build a single-file Python app from a uv project.")
+    build.add_argument(
+        "project",
+        nargs="?",
+        default=".",
+        help="Path to the uv project (containing pyproject.toml). Default: cwd.",
+    )
+    build.add_argument(
+        "-o", "--output",
+        default=None,
+        help="Output file path. Default: <cwd>/dist/<project-name>.py.",
+    )
+    build.add_argument(
+        "-e", "--entry",
+        default=None,
+        help="Entry point in 'module:function' form. Defaults to the project's first console script.",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "build":
+        project_dir = Path(args.project).expanduser().resolve()
+        if args.output is None:
+            output = Path.cwd() / "dist" / f"{project_dir.name}.py"
+        else:
+            output = Path(args.output).expanduser().resolve()
+        if output.suffix == "":
+            output = output.with_suffix(".py")
+        return build_pyz(
+            project_dir=project_dir,
+            output=output,
+            entry=args.entry,
+        )
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

zuv-0.0.1/zuv/constants.py

@@ -0,0 +1,5 @@
+STAGING_DIRNAME = ".zuv-staging"
+ZUV_CACHE_DIRNAME = ".zuv"
+ZUV_SKIP_PLATFORM_CHECK = "ZUV_SKIP_PLATFORM_CHECK"
+ZUV_SHEBANG = "#!/usr/bin/env -S uv run --script\n"
+PAYLOAD_VAR = "_ZUV_PAYLOAD"