beam-lan 0.2.0__tar.gz

beam_lan-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.DS_Store

beam_lan-0.2.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.2.0
+
+- `beam recv CODE` finds the sender on the local network by itself; no IP
+  address is needed. Use `--host IP[:PORT]` to connect directly.
+- New `--wait SEC` option for how long the receiver searches.
+- New `beam.find_sender(code)` library function. `receive_project` takes
+  `host=None` to discover the sender.
+- Fix: sending crashed on Python 3.9–3.11 (the receiver saw an empty stream).
+- Breaking: `beam recv HOST --code CODE` is now `beam recv CODE --host HOST`.
+
+## 0.1.0
+
+- First release: `beam send` / `beam recv` with excludes, `.beamignore`,
+  SHA-256 verification and streamed gzip transfer.

beam_lan-0.2.0/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.

beam_lan-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,130 @@
+# 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/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "beam-lan"
+dynamic = ["version"]
+description = "Move a project folder from one laptop to another over the local network."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Nylonxd", email = "Himanshujha202005@gmail.com" }]
+keywords = ["file-transfer", "lan", "sync", "project", "tar", "cli", "local-network"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+    "Topic :: Communications :: File Sharing",
+    "Topic :: System :: Archiving",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.4", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/NYLONXD/beam"
+Source = "https://github.com/NYLONXD/beam"
+Issues = "https://github.com/NYLONXD/beam/issues"
+Changelog = "https://github.com/NYLONXD/beam/blob/main/CHANGELOG.md"
+
+[project.scripts]
+beam = "beam.cli:main"
+
+[tool.hatch.version]
+path = "src/beam/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/beam"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/beam", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

beam_lan-0.2.0/src/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_lan-0.2.0/src/beam/__main__.py

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

beam_lan-0.2.0/src/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