repak 0.1.0__py3-none-any.whl

repak/__init__.py

@@ -0,0 +1,5 @@
+"""repak: package a local directory as a synthetic PyPI wheel for transport."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

repak/archive.py

@@ -0,0 +1,64 @@
+"""Build a deterministic ``tar.gz`` of a directory's contents + checksum."""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import io
+import os
+import tarfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List
+
+VCS_DIRS = {".git", ".hg", ".svn", ".bzr"}
+
+# Fixed timestamp so identical trees produce identical archives (helps make
+# uploads/tests reproducible). 2020-01-01 UTC.
+_FIXED_MTIME = 1577836800
+
+
+@dataclass
+class Archive:
+    data: bytes
+    sha256: str
+    size: int  # compressed size in bytes
+
+
+def _iter_files(root: Path) -> List[Path]:
+    collected: List[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Prune VCS directories in-place so os.walk does not descend.
+        dirnames[:] = sorted(d for d in dirnames if d not in VCS_DIRS)
+        for name in sorted(filenames):
+            collected.append(Path(dirpath) / name)
+    return collected
+
+
+def build_archive(source_dir: str | os.PathLike) -> Archive:
+    """Tar (gzip) the *contents* of ``source_dir`` at the archive root.
+
+    VCS directories are excluded. The archive and its SHA-256 are
+    deterministic for a given set of file contents and relative paths.
+    """
+    root = Path(source_dir).resolve()
+    if not root.is_dir():
+        raise NotADirectoryError(f"{root} is not a directory")
+
+    raw = io.BytesIO()
+    with tarfile.open(fileobj=raw, mode="w") as tar:
+        for path in _iter_files(root):
+            rel = path.relative_to(root).as_posix()
+            info = tar.gettarinfo(str(path), arcname=rel)
+            info.mtime = _FIXED_MTIME
+            info.uid = info.gid = 0
+            info.uname = info.gname = ""
+            if info.isreg():
+                with open(path, "rb") as fh:
+                    tar.addfile(info, fh)
+            else:
+                tar.addfile(info)
+
+    compressed = gzip.compress(raw.getvalue(), compresslevel=9, mtime=0)
+    digest = hashlib.sha256(compressed).hexdigest()
+    return Archive(data=compressed, sha256=digest, size=len(compressed))

repak/cli.py

@@ -0,0 +1,143 @@
+"""repak command-line entry point (upload side)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from . import naming, pypi, versioning
+from .archive import build_archive
+from .wheel import WheelTooLarge, build_wheel
+
+TOKEN_ENV_VARS = ("PYPI_TOKEN", "TWINE_PASSWORD")
+
+
+def _get_token() -> str:
+    for var in TOKEN_ENV_VARS:
+        val = os.environ.get(var)
+        if val:
+            return val
+    raise SystemExit(
+        "ERROR: no PyPI token found. Set the PYPI_TOKEN environment variable "
+        "to a PyPI API token (passed via the environment, never as a flag, "
+        "so it stays out of shell history and process listings)."
+    )
+
+
+def _confirm(prompt: str, assume_yes: bool) -> bool:
+    if assume_yes:
+        return True
+    try:
+        answer = input(f"{prompt} [y/N] ").strip().lower()
+    except EOFError:
+        return False
+    return answer in ("y", "yes")
+
+
+def _parse_args(argv):
+    parser = argparse.ArgumentParser(
+        prog="repak",
+        description="Package a local directory as a synthetic PyPI wheel and "
+        "upload it to public PyPI for transport into an isolated mirror.",
+    )
+    parser.add_argument(
+        "--path",
+        default=".",
+        help="Directory to package (default: current directory).",
+    )
+    parser.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        help="Skip confirmation prompts (for non-interactive use).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv=None) -> int:
+    args = _parse_args(argv)
+
+    source = Path(args.path).resolve()
+    if not source.is_dir():
+        sys.stderr.write(f"ERROR: {source} is not a directory.\n")
+        return 1
+
+    try:
+        pypi_name = naming.pypi_name(source.name)
+    except naming.NameError_ as exc:
+        sys.stderr.write(f"ERROR: {exc}\n")
+        return 1
+
+    token = _get_token()
+
+    info = pypi.query(pypi_name)
+    if info.exists and not info.is_repak:
+        sys.stderr.write(
+            f"ERROR: '{pypi_name}' already exists on PyPI but was not created "
+            "by repak (no repak marker). Refusing to collide with an "
+            "unrelated package. Rename the source folder and retry.\n"
+        )
+        return 1
+
+    try:
+        version = versioning.next_version(info.versions if info.exists else None)
+    except versioning.VersionExhausted as exc:
+        sys.stderr.write(f"ERROR: {exc}\n")
+        return 1
+
+    if not info.exists:
+        print(f"Creating new package {pypi_name} at version {version}")
+    else:
+        latest = info.versions[-1] if info.versions else "?"
+        print(
+            f"Warning: {pypi_name} already exists at version {latest}\n"
+            f"This upload will create version {version}."
+        )
+        if not _confirm("Proceed?", args.yes):
+            print("Aborted.")
+            return 1
+
+    archive = build_archive(source)
+    print(
+        f"Archived contents of {source} "
+        f"({archive.size / (1024 * 1024):.2f} MiB compressed, "
+        f"sha256 {archive.sha256[:16]}...)"
+    )
+
+    with tempfile.TemporaryDirectory() as tmp:
+        try:
+            wheel = build_wheel(source.name, version, archive, tmp)
+        except WheelTooLarge as exc:
+            sys.stderr.write(f"ERROR: {exc}\n")
+            return 1
+
+        print(
+            f"Built wheel {wheel.filename} "
+            f"({wheel.size / (1024 * 1024):.2f} MiB)"
+        )
+        if not _confirm(f"Upload {wheel.filename} to public PyPI?", args.yes):
+            print("Aborted.")
+            return 1
+
+        try:
+            pypi.upload(wheel.path, token)
+        except pypi.UploadError as exc:
+            sys.stderr.write(f"ERROR: {exc}\n")
+            return 1
+
+    script = naming.console_script(source.name)
+    print(
+        f"\nUploaded {pypi_name} {version} to public PyPI.\n"
+        "Note: propagation to the internal mirror is NOT immediate; there is "
+        "an unknown sync lag before it becomes installable in the isolated "
+        "environment.\n"
+        f"Once available: pip install {pypi_name} && {script} /target/folder"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

repak/naming.py

@@ -0,0 +1,43 @@
+"""Folder name -> PyPI package name / Python module name normalization."""
+
+from __future__ import annotations
+
+import re
+
+REPAK_PREFIX = "repak"
+
+
+class NameError_(ValueError):
+    """Raised when a folder name cannot be normalized to a valid name."""
+
+
+def normalize(folder_name: str) -> str:
+    """Normalize a folder basename to a PEP 503-style component.
+
+    Lowercase, runs of non-alphanumeric characters collapse to a single
+    hyphen, leading/trailing hyphens stripped.
+    """
+    lowered = folder_name.strip().lower()
+    collapsed = re.sub(r"[^a-z0-9]+", "-", lowered)
+    stripped = collapsed.strip("-")
+    if not stripped:
+        raise NameError_(
+            f"folder name {folder_name!r} does not contain any characters "
+            "usable in a PyPI package name"
+        )
+    return stripped
+
+
+def pypi_name(folder_name: str) -> str:
+    """Return the public PyPI distribution name: ``repak-{normalized}``."""
+    return f"{REPAK_PREFIX}-{normalize(folder_name)}"
+
+
+def module_name(folder_name: str) -> str:
+    """Return the import package name: ``repak_{normalized_with_underscores}``."""
+    return f"{REPAK_PREFIX}_{normalize(folder_name).replace('-', '_')}"
+
+
+def console_script(folder_name: str) -> str:
+    """Return the destination-side console command: ``unpak-{normalized}``."""
+    return f"unpak-{normalize(folder_name)}"

repak/pypi.py

@@ -0,0 +1,75 @@
+"""PyPI interaction: version query, repak-marker detection, twine upload."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from .wheel import MARKER
+
+PYPI_JSON_URL = "https://pypi.org/pypi/{name}/json"
+
+
+@dataclass
+class PackageInfo:
+    exists: bool
+    versions: List[str]
+    is_repak: bool  # True only if an existing package carries the repak marker
+
+
+class UploadError(RuntimeError):
+    pass
+
+
+def query(pypi_name: str, *, timeout: float = 15.0) -> PackageInfo:
+    """Look up ``pypi_name`` on public PyPI.
+
+    A 404 means the name is free. If it exists, the repak marker keyword
+    distinguishes a package repak itself created from an unrelated public
+    package that merely shares the name.
+    """
+    url = PYPI_JSON_URL.format(name=pypi_name)
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            payload = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return PackageInfo(exists=False, versions=[], is_repak=False)
+        raise
+
+    versions = sorted((payload.get("releases") or {}).keys())
+    info = payload.get("info") or {}
+    keywords = (info.get("keywords") or "").lower()
+    is_repak = MARKER in keywords
+    return PackageInfo(exists=True, versions=versions, is_repak=is_repak)
+
+
+def upload(wheel_path: str | Path, token: str, *, repository_url: Optional[str] = None) -> None:
+    """Upload a wheel with ``twine`` using token auth.
+
+    The token is passed via the environment (``TWINE_PASSWORD`` with
+    ``TWINE_USERNAME=__token__``) so it never appears in argv or shell
+    history.
+    """
+    env = {
+        "TWINE_USERNAME": "__token__",
+        "TWINE_PASSWORD": token,
+    }
+    import os
+
+    full_env = {**os.environ, **env}
+    cmd = [sys.executable, "-m", "twine", "upload", str(wheel_path)]
+    if repository_url:
+        cmd[4:4] = ["--repository-url", repository_url]
+    result = subprocess.run(cmd, env=full_env, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise UploadError(
+            "twine upload failed:\n"
+            f"{result.stdout}\n{result.stderr}".strip()
+        )

repak/unpak_template.py

@@ -0,0 +1,102 @@
+"""Self-contained extractor embedded into every repak-generated wheel.
+
+This module ships *inside* the synthetic wheel as ``<pkg>/_unpak.py`` and is
+wired to the ``unpak-{name}`` console script. It must depend only on the
+Python standard library: repak is not installed on the destination side.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import io
+import os
+import sys
+import tarfile
+from importlib import resources
+from pathlib import Path
+
+PAYLOAD = "payload.tar.gz"
+CHECKSUM = "payload.sha256"
+
+
+def _read_resource(name: str) -> bytes:
+    return resources.files(__package__).joinpath(name).read_bytes()
+
+
+def _safe_members(tar: tarfile.TarFile, dest: Path):
+    """Yield only members that extract safely under ``dest``.
+
+    Rejects absolute paths and ``..`` traversal; restricts to regular files
+    and directories (mirrors the intent of tarfile's ``data`` filter while
+    remaining compatible with Python 3.9).
+    """
+    dest = dest.resolve()
+    for member in tar.getmembers():
+        name = member.name
+        if name.startswith("/") or os.path.isabs(name):
+            raise ValueError(f"unsafe absolute path in archive: {name!r}")
+        target = (dest / name).resolve()
+        if target != dest and dest not in target.parents:
+            raise ValueError(f"unsafe path traversal in archive: {name!r}")
+        if member.isdir() or member.isreg():
+            yield member
+        else:
+            raise ValueError(
+                f"archive contains unsupported entry {name!r} "
+                f"(type {member.type!r})"
+            )
+
+
+def _extract(data: bytes, dest: Path) -> None:
+    dest.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tar:
+        members = list(_safe_members(tar, dest))
+        for member in members:
+            out = dest / member.name
+            if member.isdir():
+                out.mkdir(parents=True, exist_ok=True)
+                continue
+            out.parent.mkdir(parents=True, exist_ok=True)
+            src = tar.extractfile(member)
+            if src is None:
+                continue
+            with open(out, "wb") as fh:
+                fh.write(src.read())
+            os.chmod(out, member.mode & 0o777)
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog=f"unpak ({__package__})",
+        description="Verify and extract a repak-transported directory.",
+    )
+    parser.add_argument(
+        "target",
+        help="Destination folder; created if missing. Existing unrelated "
+        "files are left untouched (overwrite/merge).",
+    )
+    args = parser.parse_args(argv)
+
+    data = _read_resource(PAYLOAD)
+    expected = _read_resource(CHECKSUM).decode("ascii").strip()
+    actual = hashlib.sha256(data).hexdigest()
+    if actual != expected:
+        sys.stderr.write(
+            "ERROR: checksum verification failed; the payload is corrupt "
+            "and nothing was written.\n"
+            f"  expected: {expected}\n"
+            f"  actual:   {actual}\n"
+        )
+        return 1
+
+    dest = Path(args.target)
+    _extract(data, dest)
+    sys.stdout.write(
+        f"Verified SHA-256 and extracted contents to {dest.resolve()}\n"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

repak/versioning.py

@@ -0,0 +1,47 @@
+"""Version scheme: 0.N where N is an integer 1..99.
+
+Sequence: 0.1, 0.2, ... 0.9, 0.10, 0.11, ... 0.99 (99 uploads per package).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Optional
+
+_VERSION_RE = re.compile(r"^0\.(\d+)$")
+
+MIN_MINOR = 1
+MAX_MINOR = 99
+
+
+class VersionExhausted(RuntimeError):
+    """Raised when the 0.99 ceiling has been reached for a package."""
+
+
+def next_version(existing: Optional[Iterable[str]]) -> str:
+    """Return the next ``0.N`` version string.
+
+    ``None`` or an empty iterable means the package does not exist yet, so
+    versioning starts at ``0.1``. Otherwise the next version is one greater
+    than the highest ``0.N`` already published; non-conforming version
+    strings are ignored.
+    """
+    if not existing:
+        return f"0.{MIN_MINOR}"
+
+    minors = [
+        int(m.group(1))
+        for m in (_VERSION_RE.match(v.strip()) for v in existing)
+        if m is not None
+    ]
+    if not minors:
+        return f"0.{MIN_MINOR}"
+
+    current = max(minors)
+    nxt = current + 1
+    if nxt > MAX_MINOR:
+        raise VersionExhausted(
+            f"package has reached the maximum version 0.{MAX_MINOR}; "
+            "no further uploads are possible under this package name"
+        )
+    return f"0.{nxt}"

repak/wheel.py

@@ -0,0 +1,108 @@
+"""Hand-built synthetic wheel: a transport container, not a real package."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import zipfile
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Dict
+
+from . import naming
+from .archive import Archive
+from .unpak_template import CHECKSUM, PAYLOAD
+
+MARKER = "repak-transport-container"
+
+# PyPI's default per-file upload limit.
+MAX_WHEEL_BYTES = 100 * 1024 * 1024
+
+
+class WheelTooLarge(RuntimeError):
+    def __init__(self, size: int):
+        self.size = size
+        super().__init__(
+            f"generated wheel is {size / (1024 * 1024):.2f} MiB, which "
+            f"exceeds PyPI's {MAX_WHEEL_BYTES // (1024 * 1024)} MiB per-file "
+            "limit. Reduce the directory size and try again."
+        )
+
+
+@dataclass
+class BuiltWheel:
+    path: Path
+    size: int
+    filename: str
+
+
+def _record_hash(data: bytes) -> str:
+    digest = hashlib.sha256(data).digest()
+    b64 = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return f"sha256={b64}"
+
+
+def _unpak_source() -> str:
+    return resources.files("repak").joinpath("unpak_template.py").read_text(
+        encoding="utf-8"
+    )
+
+
+def build_wheel(
+    folder_name: str,
+    version: str,
+    archive: Archive,
+    out_dir: str | Path,
+) -> BuiltWheel:
+    """Write ``repak_{name}-{version}-py3-none-any.whl`` into ``out_dir``."""
+    pkg = naming.module_name(folder_name)
+    dist_name = naming.pypi_name(folder_name)
+    script = naming.console_script(folder_name)
+    dist_info = f"{pkg}-{version}.dist-info"
+
+    metadata = (
+        "Metadata-Version: 2.1\n"
+        f"Name: {dist_name}\n"
+        f"Version: {version}\n"
+        "Summary: Directory payload transported by repak.\n"
+        f"Keywords: {MARKER}\n"
+    )
+    wheel_meta = (
+        "Wheel-Version: 1.0\n"
+        "Generator: repak\n"
+        "Root-Is-Purelib: true\n"
+        "Tag: py3-none-any\n"
+    )
+    entry_points = f"[console_scripts]\n{script} = {pkg}._unpak:main\n"
+
+    files: Dict[str, bytes] = {
+        f"{pkg}/__init__.py": b"",
+        f"{pkg}/_unpak.py": _unpak_source().encode("utf-8"),
+        f"{pkg}/{PAYLOAD}": archive.data,
+        f"{pkg}/{CHECKSUM}": archive.sha256.encode("ascii") + b"\n",
+        f"{dist_info}/METADATA": metadata.encode("utf-8"),
+        f"{dist_info}/WHEEL": wheel_meta.encode("utf-8"),
+        f"{dist_info}/entry_points.txt": entry_points.encode("utf-8"),
+    }
+
+    record_lines = [
+        f"{name},{_record_hash(data)},{len(data)}"
+        for name, data in files.items()
+    ]
+    record_path = f"{dist_info}/RECORD"
+    record_lines.append(f"{record_path},,")
+    files[record_path] = ("\n".join(record_lines) + "\n").encode("utf-8")
+
+    filename = f"{pkg}-{version}-py3-none-any.whl"
+    out_path = Path(out_dir) / filename
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for name, data in files.items():
+            zf.writestr(name, data)
+
+    size = out_path.stat().st_size
+    if size > MAX_WHEEL_BYTES:
+        out_path.unlink(missing_ok=True)
+        raise WheelTooLarge(size)
+
+    return BuiltWheel(path=out_path, size=size, filename=filename)

repak-0.1.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: repak
+Version: 0.1.0
+Summary: Transfer a local directory across a network boundary via a synthetic PyPI wheel
+Requires-Python: >=3.9
+Requires-Dist: twine>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

repak-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+repak/__init__.py,sha256=QMI24uAFXyzQ-GOGdXllmLjcMDcDR-6SCJ0QR-G464Q,130
+repak/archive.py,sha256=3xjdlMqNKI4knYV9dAYoI-QqzhPfQvEWLw1NEX-Qw1I,2054
+repak/cli.py,sha256=GErQjRB6gBTymh4-uAZCTylaRSrdKy9Bb3EYy1F1MSk,4221
+repak/naming.py,sha256=5vO369XEuQBbYTDZOqmsPWMEbiX9Wo-_EhEDOAdynSE,1356
+repak/pypi.py,sha256=nKr4vn4Qjwizl159dw3pa7vQDvJVqoYVYPrD1iNMgdo,2328
+repak/unpak_template.py,sha256=AkBMA5uMXtsdiuTGur3mSzvUWX0qcNLCFNgS3Q004Bo,3299
+repak/versioning.py,sha256=1IAOuswvr-h7qiMsjJfmVsqbr1KkBIDsJ6So_zdjTgs,1284
+repak/wheel.py,sha256=uLstphenb8NOnYokHilv4AOQSQjUTJ3G3grhaMgMhnQ,3206
+repak-0.1.0.dist-info/METADATA,sha256=LnVCCUfxyOANOGMHF9e8vsMa4DQBdDjbf4qohlcX5kQ,250
+repak-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+repak-0.1.0.dist-info/entry_points.txt,sha256=lX2p3GeQHHPMu5s5G6Z5Dv9PzGPv9GFAngXlcVOM6ho,41
+repak-0.1.0.dist-info/top_level.txt,sha256=jDYOl_fY_uwpgjJPzWs4GdZ4G34NItkq9fXYMMtVPK8,6
+repak-0.1.0.dist-info/RECORD,,

repak-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

repak-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+repak = repak.cli:main

repak-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+repak