beam-lan 0.2.0__py3-none-any.whl

beam/__init__.py

@@ -0,0 +1,25 @@
+"""beam - move a project folder between two laptops over the local network.
+
+    import beam
+
+    beam.send_project("~/thesis", code="ab3f9c")        # laptop A
+    beam.receive_project(code="ab3f9c")                  # laptop B
+"""
+
+from ._files import DEFAULT_EXCLUDES
+from ._protocol import DEFAULT_PORT, BeamError, find_sender, lan_ip
+from .receiver import receive_project
+from .sender import send_project
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "send_project",
+    "receive_project",
+    "find_sender",
+    "lan_ip",
+    "BeamError",
+    "DEFAULT_EXCLUDES",
+    "DEFAULT_PORT",
+    "__version__",
+]

beam/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m beam`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

beam/_files.py

@@ -0,0 +1,137 @@
+"""Walking the project tree, exclude rules, hashing."""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import os
+import sys
+import tarfile
+from pathlib import Path
+
+from ._protocol import MANIFEST_NAME
+
+HASH_CHUNK = 1 << 20
+
+# Things you almost never want to carry between machines: virtualenvs are
+# platform-specific, caches are regenerable, .git is better cloned.
+DEFAULT_EXCLUDES = [
+    ".git",
+    ".hg",
+    ".svn",
+    "__pycache__",
+    "*.pyc",
+    "*.pyo",
+    ".venv",
+    "venv",
+    "env",
+    ".env",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    "*.egg-info",
+    "node_modules",
+    ".DS_Store",
+    "Thumbs.db",
+    MANIFEST_NAME,
+]
+
+# tarfile only learned about extraction filters in 3.12.
+EXTRACT_KW = {"filter": "data"} if sys.version_info >= (3, 12) else {}
+
+
+def human(n: float) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.0f} {unit}" if unit == "B" else f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} GB"
+
+
+def excluded(rel: Path, patterns) -> bool:
+    text = rel.as_posix()
+    for pat in patterns:
+        pat = pat.rstrip("/")
+        if fnmatch.fnmatch(rel.name, pat):
+            return True
+        if any(fnmatch.fnmatch(part, pat) for part in rel.parts):
+            return True
+        if fnmatch.fnmatch(text, pat):
+            return True
+    return False
+
+
+def read_ignore_file(root: Path) -> list:
+    """Read .beamignore if present. Simple glob patterns, one per line."""
+    path = root / ".beamignore"
+    if not path.is_file():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            out.append(line)
+    return out
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for block in iter(lambda: fh.read(HASH_CHUNK), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def walk(root: Path, patterns, max_bytes=None):
+    """Return ([(abs_path, rel_path, size)], [(rel_path, size)]) - kept, skipped."""
+    found, skipped = [], []
+    for dirpath, dirnames, filenames in os.walk(root):
+        here = Path(dirpath)
+        rel_dir = here.relative_to(root)
+        dirnames[:] = sorted(d for d in dirnames if not excluded(rel_dir / d, patterns))
+        for name in sorted(filenames):
+            rel = rel_dir / name
+            if excluded(rel, patterns):
+                continue
+            abs_path = here / name
+            if abs_path.is_symlink() and not abs_path.exists():
+                continue  # broken symlink
+            try:
+                size = abs_path.stat().st_size
+            except OSError:
+                continue
+            if max_bytes is not None and size > max_bytes:
+                skipped.append((rel, size))
+                continue
+            found.append((abs_path, rel, size))
+    return found, skipped
+
+
+def member_is_safe(name: str) -> bool:
+    path = Path(name)
+    return not path.is_absolute() and ".." not in path.parts
+
+
+def safe_extract(tar: tarfile.TarFile, member: tarfile.TarInfo, dest: Path) -> None:
+    if not member_is_safe(member.name):
+        raise ValueError(f"unsafe path in stream: {member.name!r}")
+    if (member.islnk() or member.issym()) and not member_is_safe(member.linkname):
+        raise ValueError(f"unsafe link target in stream: {member.linkname!r}")
+    tar.extract(member, dest, **EXTRACT_KW)
+
+
+class BytesReader:
+    """File-like wrapper so tar.addfile can consume an in-memory manifest."""
+
+    def __init__(self, data: bytes):
+        self.data = data
+        self.pos = 0
+
+    def read(self, n=-1) -> bytes:
+        if n is None or n < 0:
+            n = len(self.data) - self.pos
+        chunk = self.data[self.pos : self.pos + n]
+        self.pos += len(chunk)
+        return chunk

beam/_protocol.py

@@ -0,0 +1,162 @@
+"""Wire protocol: framing, errors, and network helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import socket
+import struct
+import threading
+import time
+
+PROTOCOL = 1
+DEFAULT_PORT = 8765
+DISCOVERY_PORT = 8766
+MANIFEST_NAME = ".beam-manifest.json"
+MAX_HEADER = 64 * 1024 * 1024
+
+
+class BeamError(RuntimeError):
+    """The other side refused us, or the stream was malformed."""
+
+
+def send_msg(sock: socket.socket, obj: dict) -> None:
+    raw = json.dumps(obj).encode("utf-8")
+    sock.sendall(struct.pack("!I", len(raw)) + raw)
+
+
+def recv_exact(sock: socket.socket, n: int) -> bytes:
+    buf = bytearray()
+    while len(buf) < n:
+        chunk = sock.recv(n - len(buf))
+        if not chunk:
+            raise BeamError("connection closed mid-message")
+        buf += chunk
+    return bytes(buf)
+
+
+def recv_msg(sock: socket.socket) -> dict:
+    (length,) = struct.unpack("!I", recv_exact(sock, 4))
+    if length > MAX_HEADER:
+        raise BeamError("refusing an absurdly large header")
+    return json.loads(recv_exact(sock, length).decode("utf-8"))
+
+
+def lan_ip() -> str:
+    """Best guess at this machine's address on the local network."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.connect(("8.8.8.8", 80))  # no packets are actually sent
+        return sock.getsockname()[0]
+    except OSError:
+        return "127.0.0.1"
+    finally:
+        sock.close()
+
+
+# --- discovery ---------------------------------------------------------------
+#
+# The receiver only knows the code. It broadcasts a UDP query carrying a hash
+# of the code; the sender with that code answers with its TCP port, and the
+# reply's source address tells the receiver where to connect.
+
+
+def code_tag(code: str) -> str:
+    return hashlib.sha256(f"beam:{code}".encode()).hexdigest()[:16]
+
+
+def _local_ipv4s() -> set[str]:
+    ips = {lan_ip()}
+    try:
+        for info in socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET):
+            ips.add(info[4][0])
+    except OSError:
+        pass
+    return {ip for ip in ips if not ip.startswith("127.")}
+
+
+def _broadcast_targets() -> list[str]:
+    targets = ["255.255.255.255", "127.0.0.1"]
+    # Windows often sends 255.255.255.255 out of one adapter only, so also hit
+    # each adapter's subnet broadcast (assuming the usual home /24).
+    for ip in _local_ipv4s():
+        targets.append(ip.rsplit(".", 1)[0] + ".255")
+    return targets
+
+
+class DiscoveryResponder:
+    """Answers discovery queries for one code until stopped."""
+
+    def __init__(
+        self, code: str, port: int, name: str, udp_port: int = DISCOVERY_PORT
+    ):
+        self.tag = code_tag(code)
+        self.reply = json.dumps(
+            {"beam": PROTOCOL, "id": self.tag, "port": port, "name": name}
+        ).encode("utf-8")
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self.sock.bind(("", udp_port))
+        self.sock.settimeout(0.5)
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def start(self) -> DiscoveryResponder:
+        self._thread.start()
+        return self
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                data, addr = self.sock.recvfrom(2048)
+                query = json.loads(data.decode("utf-8"))
+            except (OSError, ValueError):  # timeout, ICMP reset, junk
+                continue
+            if isinstance(query, dict) and query.get("find") == self.tag:
+                try:
+                    self.sock.sendto(self.reply, addr)
+                except OSError:
+                    pass
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=2)
+        self.sock.close()
+
+
+def find_sender(
+    code: str, timeout: float = 15.0, udp_port: int = DISCOVERY_PORT
+) -> tuple[str, int, str]:
+    """Locate the sender holding ``code`` on the LAN. Returns (host, port, name)."""
+    tag = code_tag(code)
+    query = json.dumps({"beam": PROTOCOL, "find": tag}).encode("utf-8")
+    targets = _broadcast_targets()
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+    sock.bind(("", 0))
+    sock.settimeout(0.3)
+    deadline = time.monotonic() + timeout
+    next_ping = 0.0
+    try:
+        while time.monotonic() < deadline:
+            if time.monotonic() >= next_ping:
+                for target in targets:
+                    try:
+                        sock.sendto(query, (target, udp_port))
+                    except OSError:
+                        pass
+                next_ping = time.monotonic() + 1.0
+            try:
+                data, addr = sock.recvfrom(2048)
+                reply = json.loads(data.decode("utf-8"))
+            except (OSError, ValueError):
+                continue
+            if isinstance(reply, dict) and reply.get("id") == tag:
+                return addr[0], int(reply["port"]), str(reply.get("name", ""))
+    finally:
+        sock.close()
+    raise BeamError(
+        f"no sender with code {code!r} found on this network after {timeout:.0f}s "
+        "(same Wi-Fi? firewall allowing Python? or pass --host IP)"
+    )

beam/cli.py

@@ -0,0 +1,100 @@
+"""Command line interface for beam."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from ._protocol import DEFAULT_PORT, BeamError
+from .receiver import receive_project
+from .sender import send_project
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="beam", description="Move a project folder between two laptops."
+    )
+    parser.add_argument("--version", action="version", version=f"beam {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    send = sub.add_parser("send", help="serve a folder to one receiver")
+    send.add_argument("path", help="project folder to send")
+    send.add_argument("--port", type=int, default=DEFAULT_PORT)
+    send.add_argument("--code", help="access code (random if omitted)")
+    send.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="extra pattern to skip (repeatable)",
+    )
+    send.add_argument(
+        "--all",
+        action="store_true",
+        help="do not apply the default excludes (.git, venv, __pycache__, ...)",
+    )
+    send.add_argument(
+        "--max-size",
+        type=float,
+        metavar="MB",
+        help="skip files larger than this many MB",
+    )
+    send.add_argument(
+        "--no-hash",
+        action="store_true",
+        help="skip SHA-256 hashing (faster on huge datasets, size-check only)",
+    )
+    send.add_argument("--fast", action="store_true", help="compress less, send sooner")
+
+    recv = sub.add_parser("recv", help="pull a folder from a sender")
+    recv.add_argument("code", help="the code shown by the sender")
+    recv.add_argument("--host", help="sender's IP (or IP:port); skips auto-discovery")
+    recv.add_argument("--port", type=int, default=DEFAULT_PORT)
+    recv.add_argument(
+        "--wait",
+        type=float,
+        default=15,
+        metavar="SEC",
+        help="how long to search the network for the sender",
+    )
+    recv.add_argument("--out", default=".", help="where to put the folder")
+    recv.add_argument("--name", help="rename the folder on arrival")
+    recv.add_argument(
+        "--force", action="store_true", help="write into a non-empty folder"
+    )
+    recv.add_argument("--no-verify", action="store_true")
+    return parser
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.cmd == "send":
+            send_project(
+                args.path,
+                port=args.port,
+                code=args.code,
+                excludes=[] if args.all else None,
+                extra_excludes=args.exclude,
+                hash_files=not args.no_hash,
+                max_size_mb=args.max_size,
+                compresslevel=1 if args.fast else 6,
+            )
+        else:
+            receive_project(
+                args.host,
+                port=args.port,
+                code=args.code,
+                wait=args.wait,
+                out=args.out,
+                name=args.name,
+                overwrite=args.force,
+                verify=not args.no_verify,
+            )
+    except (BeamError, OSError, NotADirectoryError) as exc:
+        print(f"\nbeam: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+    return 0

beam/receiver.py

@@ -0,0 +1,132 @@
+"""Pulling a project folder from a sender."""
+
+from __future__ import annotations
+
+import json
+import socket
+import sys
+import tarfile
+from pathlib import Path
+
+from ._files import human, safe_extract, sha256_file
+from ._protocol import (
+    DEFAULT_PORT,
+    MANIFEST_NAME,
+    PROTOCOL,
+    BeamError,
+    find_sender,
+    recv_msg,
+    send_msg,
+)
+
+
+def receive_project(
+    host: str | None = None,
+    port: int = DEFAULT_PORT,
+    code: str = "",
+    out=".",
+    name: str | None = None,
+    overwrite: bool = False,
+    verify: bool = True,
+    quiet: bool = False,
+    wait: float = 15.0,
+) -> Path:
+    """Pull a project from a sender. Returns the folder it was written to.
+
+    Leave ``host`` as None to find the sender on the LAN by its code.
+    """
+
+    def say(*args):
+        if not quiet:
+            print(*args, file=sys.stderr, flush=True)
+
+    if host is None:
+        if not code:
+            raise BeamError("need the code shown by the sender")
+        say(f"\n  looking for the sender with code {code} ...")
+        host, port, _ = find_sender(code, timeout=wait)
+        say(f"  found it at {host}:{port}")
+    elif ":" in host and host.count(":") == 1:
+        host, _, raw_port = host.partition(":")
+        port = int(raw_port)
+
+    sock = socket.create_connection((host, port), timeout=30)
+    try:
+        send_msg(sock, {"protocol": PROTOCOL, "code": code})
+        reply = recv_msg(sock)
+        if not reply.get("ok"):
+            raise BeamError(f"sender refused us: {reply.get('error', 'unknown')}")
+
+        total = reply.get("bytes", 0)
+        count = reply.get("count", 0)
+        dest = Path(out).expanduser().resolve() / (name or reply["name"])
+        if dest.exists() and any(dest.iterdir()) and not overwrite:
+            raise BeamError(
+                f"{dest} already exists and is not empty "
+                f"(pass overwrite=True or --force to write into it anyway)"
+            )
+        dest.mkdir(parents=True, exist_ok=True)
+
+        say(f"\n  receiving {reply['name']}  ({count} files, {human(total)})")
+        say(f"  into {dest}")
+
+        sock.settimeout(None)
+        manifest = None
+        done = 0
+        stream = sock.makefile("rb")
+        with tarfile.open(fileobj=stream, mode="r|gz") as tar:
+            for member in tar:
+                try:
+                    safe_extract(tar, member, dest)
+                except ValueError as exc:
+                    raise BeamError(str(exc)) from None
+                if member.name == MANIFEST_NAME:
+                    manifest = json.loads(
+                        (dest / MANIFEST_NAME).read_text(encoding="utf-8")
+                    )
+                    (dest / MANIFEST_NAME).unlink()
+                    continue
+                done += 1
+                if not quiet:
+                    print(
+                        f"\r  {done}/{count or '?'}   {member.name[:52]:<52}",
+                        end="",
+                        file=sys.stderr,
+                        flush=True,
+                    )
+        say("")
+
+        verified, mismatched = 0, []
+        if verify and manifest:
+            say("  verifying ...")
+            for rel, meta in manifest["files"].items():
+                target = dest / rel
+                if not target.is_file():
+                    mismatched.append(f"{rel} (missing)")
+                elif meta["sha256"] is None:
+                    if target.stat().st_size != meta["size"]:
+                        mismatched.append(f"{rel} (size differs)")
+                    else:
+                        verified += 1
+                elif sha256_file(target) != meta["sha256"]:
+                    mismatched.append(f"{rel} (checksum differs)")
+                else:
+                    verified += 1
+
+        try:
+            send_msg(
+                sock, {"ok": True, "verified": verified, "mismatched": len(mismatched)}
+            )
+        except OSError:
+            pass
+
+        if mismatched:
+            say(f"  {len(mismatched)} file(s) did not verify:")
+            for item in mismatched[:10]:
+                say(f"      {item}")
+            raise BeamError("transfer completed with verification failures")
+
+        say(f"  done - {verified or done} files in {dest}")
+        return dest
+    finally:
+        sock.close()

beam/sender.py

@@ -0,0 +1,223 @@
+"""Serving a project folder to one receiver."""
+
+from __future__ import annotations
+
+import gzip
+import json
+import secrets
+import socket
+import sys
+import tarfile
+import time
+from pathlib import Path
+
+from ._files import (
+    DEFAULT_EXCLUDES,
+    BytesReader,
+    human,
+    read_ignore_file,
+    sha256_file,
+    walk,
+)
+from ._protocol import (
+    DEFAULT_PORT,
+    DISCOVERY_PORT,
+    MANIFEST_NAME,
+    PROTOCOL,
+    BeamError,
+    DiscoveryResponder,
+    lan_ip,
+    recv_msg,
+    send_msg,
+)
+
+
+class SocketWriter:
+    """Minimal write-only file object so tarfile can stream into a socket."""
+
+    def __init__(self, sock: socket.socket):
+        self.sock = sock
+
+    def write(self, data: bytes) -> int:
+        self.sock.sendall(data)
+        return len(data)
+
+    def flush(self) -> None:
+        pass
+
+
+def send_project(
+    path,
+    port: int = DEFAULT_PORT,
+    code: str | None = None,
+    excludes=None,
+    extra_excludes=(),
+    hash_files: bool = True,
+    max_size_mb: float | None = None,
+    compresslevel: int = 6,
+    quiet: bool = False,
+    on_ready=None,
+    discoverable: bool = True,
+    discovery_port: int = DISCOVERY_PORT,
+) -> str:
+    """Serve one folder to one receiver, then stop.
+
+    Pass ``port=0`` to bind an ephemeral port; ``on_ready`` is then called with
+    ``{"host", "port", "code", "files", "bytes"}`` once the socket is listening.
+    With ``discoverable`` the sender answers LAN broadcasts, so the receiver
+    only needs the code.
+    Returns the access code.
+    """
+    root = Path(path).expanduser().resolve()
+    if not root.is_dir():
+        raise NotADirectoryError(f"{root} is not a directory")
+
+    patterns = list(DEFAULT_EXCLUDES if excludes is None else excludes)
+    patterns += list(extra_excludes)
+    patterns += read_ignore_file(root)
+
+    max_bytes = int(max_size_mb * 1024 * 1024) if max_size_mb else None
+    files, skipped = walk(root, patterns, max_bytes)
+    if not files:
+        raise BeamError(f"nothing to send from {root} after applying excludes")
+
+    total = sum(size for _, _, size in files)
+    code = code or secrets.token_hex(3)
+
+    def say(*args):
+        if not quiet:
+            print(*args, file=sys.stderr, flush=True)
+
+    say(f"\n  project : {root.name}  ({len(files)} files, {human(total)})")
+    biggest = sorted(files, key=lambda f: -f[2])[:3]
+    if biggest and biggest[0][2] > 10 * 1024 * 1024:
+        say("  largest : " + ", ".join(f"{r} ({human(s)})" for _, r, s in biggest))
+    for rel, size in skipped:
+        say(f"  skipped : {rel} ({human(size)}, over --max-size)")
+
+    manifest = {"name": root.name, "protocol": PROTOCOL, "files": {}}
+    if hash_files:
+        say("  hashing ...")
+        for abs_path, rel, size in files:
+            manifest["files"][rel.as_posix()] = {
+                "size": size,
+                "sha256": sha256_file(abs_path),
+            }
+    else:
+        for _, rel, size in files:
+            manifest["files"][rel.as_posix()] = {"size": size, "sha256": None}
+
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    server.bind(("0.0.0.0", port))
+    server.listen(1)
+    bound_port = server.getsockname()[1]
+
+    responder = None
+    if discoverable:
+        try:
+            responder = DiscoveryResponder(
+                code, bound_port, root.name, discovery_port
+            ).start()
+        except OSError as exc:
+            say(f"  (auto-discovery unavailable: {exc}; receiver needs --host)")
+
+    if on_ready is not None:
+        on_ready(
+            {
+                "host": lan_ip(),
+                "port": bound_port,
+                "code": code,
+                "files": len(files),
+                "bytes": total,
+            }
+        )
+
+    say(f"\n  code    : {code}")
+    say("\n  on the other laptop, run:\n")
+    if responder is not None:
+        say(f"      beam recv {code}\n")
+        say(f"  (if it is not found: --host {lan_ip()}:{bound_port})\n")
+    else:
+        say(f"      beam recv {code} --host {lan_ip()}:{bound_port}\n")
+    say("  waiting (Ctrl-C to cancel) ...")
+
+    try:
+        while True:
+            conn, addr = server.accept()
+            try:
+                conn.settimeout(30)
+                hello = recv_msg(conn)
+                if hello.get("protocol") != PROTOCOL:
+                    send_msg(conn, {"ok": False, "error": "protocol mismatch"})
+                    continue
+                if not secrets.compare_digest(str(hello.get("code", "")), code):
+                    send_msg(conn, {"ok": False, "error": "bad code"})
+                    say(f"  refused {addr[0]} (wrong code)")
+                    continue
+
+                say(f"  sending to {addr[0]} ...")
+                send_msg(
+                    conn,
+                    {
+                        "ok": True,
+                        "name": root.name,
+                        "count": len(files),
+                        "bytes": total,
+                        "hashed": hash_files,
+                    },
+                )
+
+                conn.settimeout(None)
+                _stream(conn, manifest, files, total, compresslevel, quiet)
+
+                conn.shutdown(socket.SHUT_WR)
+                conn.settimeout(600)
+                try:
+                    ack = recv_msg(conn)
+                    bad = ack.get("mismatched", 0)
+                    if bad:
+                        say(f"  done, but {bad} file(s) failed verification")
+                    else:
+                        say(f"  done - {ack.get('verified', len(files))} files landed")
+                except (BeamError, OSError):
+                    say("  stream finished (no confirmation from the receiver)")
+                return code
+            finally:
+                conn.close()
+    except KeyboardInterrupt:
+        say("\n  cancelled")
+        return code
+    finally:
+        if responder is not None:
+            responder.stop()
+        server.close()
+
+
+def _stream(conn, manifest, files, total, compresslevel, quiet):
+    sent = 0
+    writer = SocketWriter(conn)
+    # tarfile's "w|gz" only accepts compresslevel from 3.12, so gzip ourselves.
+    with gzip.GzipFile(
+        fileobj=writer, mode="wb", compresslevel=compresslevel, mtime=0
+    ) as gz, tarfile.open(fileobj=gz, mode="w|") as tar:
+        blob = json.dumps(manifest).encode("utf-8")
+        info = tarfile.TarInfo(MANIFEST_NAME)
+        info.size = len(blob)
+        info.mtime = int(time.time())
+        tar.addfile(info, BytesReader(blob))
+
+        for abs_path, rel, size in files:
+            tar.add(abs_path, arcname=rel.as_posix(), recursive=False)
+            sent += size
+            if not quiet:
+                pct = 100 * sent / total if total else 100
+                print(
+                    f"\r  {pct:5.1f}%  {human(sent)} / {human(total)}"
+                    f"   {str(rel)[:48]:<48}",
+                    end="",
+                    file=sys.stderr,
+                    flush=True,
+                )
+    if not quiet:
+        print("", file=sys.stderr, flush=True)

beam_lan-0.2.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: beam-lan
+Version: 0.2.0
+Summary: Move a project folder from one laptop to another over the local network.
+Project-URL: Homepage, https://github.com/NYLONXD/beam
+Project-URL: Source, https://github.com/NYLONXD/beam
+Project-URL: Issues, https://github.com/NYLONXD/beam/issues
+Project-URL: Changelog, https://github.com/NYLONXD/beam/blob/main/CHANGELOG.md
+Author-email: Nylonxd <Himanshujha202005@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Nylonxd
+        
+        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.
+License-File: LICENSE
+Keywords: cli,file-transfer,lan,local-network,project,sync,tar
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: File Sharing
+Classifier: Topic :: System :: Archiving
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# beam
+
+Move a project folder from one laptop to another over the local network.
+Pure Python standard library, no runtime dependencies, works on Windows,
+macOS and Linux (Python 3.9+).
+
+```bash
+# laptop A
+beam send ~/thesis
+
+# laptop B
+beam recv ab3f9c
+```
+
+## Install
+
+Both laptops need it:
+
+```bash
+pip install beam-lan
+```
+
+`pipx install beam-lan` also works and keeps it out of your other environments.
+
+If your shell says `beam` is not a recognised command, pip put the script in a
+folder that is not on your `PATH` (pip prints a warning naming it). Either add
+that folder to `PATH`, or run `python -m beam` instead of `beam`.
+
+## Use it
+
+On the laptop that has the project:
+
+```bash
+beam send ~/thesis
+```
+
+It prints a short one-time code. Send it to the other laptop however you like
+(chat, email, read it out), then run there:
+
+```bash
+beam recv ab3f9c
+```
+
+The receiver finds the sender on the local network by itself, so no IP address
+is needed. Both machines must be on the same network.
+
+## As a library
+
+```python
+import beam
+
+beam.send_project("~/thesis", code="ab3f9c")          # laptop A
+beam.receive_project(code="ab3f9c", out="~/work")     # laptop B
+```
+
+`receive_project` also takes `host=` to skip discovery. `send_project` accepts
+`port=0` to bind a free port, and an `on_ready` callback that receives the bound
+host, port and code once it is listening. `beam.find_sender(code)` returns the
+`(host, port, name)` of a sender without transferring anything.
+
+## What it does
+
+- Skips `.venv`, `__pycache__`, `.git`, `node_modules` and similar by default.
+  Copying a virtualenv between machines mostly produces broken paths; rebuild
+  it from `requirements.txt` instead.
+- Hashes every file before sending and re-hashes after extraction, so
+  corruption is reported instead of discovered weeks later.
+- Streams a gzipped tar straight through the socket, so no temporary archive
+  is written on either side.
+- A `.beamignore` file in the project root adds per-project glob patterns, one
+  per line (`#` starts a comment).
+
+## Options
+
+`beam send PATH`
+
+| Flag | Effect |
+| --- | --- |
+| `--code CODE` | choose the code instead of a random one |
+| `--port PORT` | TCP port to listen on (default 8765) |
+| `--exclude GLOB` | extra pattern to skip, repeatable |
+| `--all` | ignore the default exclude list |
+| `--max-size MB` | skip files larger than this |
+| `--no-hash` | size-check only, faster on large datasets |
+| `--fast` | lower compression, starts sooner |
+
+`beam recv CODE`
+
+| Flag | Effect |
+| --- | --- |
+| `--host IP[:PORT]` | connect directly instead of searching the network |
+| `--wait SEC` | how long to search for the sender (default 15) |
+| `--out DIR` | where to write the folder (default: current directory) |
+| `--name NAME` | rename the folder on arrival |
+| `--force` | write into a non-empty destination |
+| `--no-verify` | skip the checksum pass after extraction |
+
+## Troubleshooting
+
+**`no sender with code ... found`**
+
+- Check both laptops are on the same Wi-Fi or wired network. Guest and office
+  networks often isolate devices from each other or drop broadcasts.
+- On Windows, allow Python through the firewall when it asks on the sending
+  laptop. If you dismissed the prompt, allow `python.exe` for private networks
+  in *Windows Defender Firewall → Allow an app*.
+- Skip discovery and connect directly using the address the sender prints:
+  `beam recv ab3f9c --host 192.168.1.42:8765`.
+
+Discovery uses UDP port 8766 and the transfer uses TCP port 8765.
+
+## Limits
+
+The connection is plain TCP with no encryption. The code stops casual grabs on
+a shared network; it is not security. Do not use it on networks you do not
+trust. For repeated syncing rather than a one-time move, `rsync -av
+--exclude=.venv` or a private Git remote is a better fit.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+python -m build
+```
+
+## License
+
+MIT

beam_lan-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+beam/__init__.py,sha256=AdrY0aofFucPBQu3CQJUF2OeK0tbhe8qu5KoGw_My4k,604
+beam/__main__.py,sha256=sb1IUiXLoJIijr7a5yvn-WneuOFJwMabUYWdRZ_w01k,110
+beam/_files.py,sha256=lOCCSumTWKvZOI6mwL8LDsPclc8z1HMJy4RTauDbRlY,3971
+beam/_protocol.py,sha256=tcTb6MBabOqlfjj0vryuYheHg3R5eKcd_rJaaEmUcH4,5291
+beam/cli.py,sha256=CRaqKSnXt2hzB1nuJZU9Ue8rqgu_t3iK1Y9kollJSt0,3333
+beam/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+beam/receiver.py,sha256=91AVHZFY4iYgFgMsFXoNq9e5eBkjZ_q0y9_mIVFYs3Q,4298
+beam/sender.py,sha256=rE4Mazt5tIEzdlw4VWwEe8pQJ8T6KzKGZnhtpCYa0PA,7309
+beam_lan-0.2.0.dist-info/METADATA,sha256=7VG0W-fg4CSecoSVkTvxqndMj45TilEEUNfVutR2y8s,6647
+beam_lan-0.2.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+beam_lan-0.2.0.dist-info/entry_points.txt,sha256=NirM3NEKoQGPNnhFejnt55vLIWaML_j3jeFRiKxnPZs,39
+beam_lan-0.2.0.dist-info/licenses/LICENSE,sha256=3A8WSslFz-PVcI-VtCHlpm609451pJkCN_YUIpiBQSA,1085
+beam_lan-0.2.0.dist-info/RECORD,,

beam_lan-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

beam_lan-0.2.0.dist-info/entry_points.txt

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

beam_lan-0.2.0.dist-info/licenses/LICENSE

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