devbits 1.1.2__tar.gz → 1.2.0__tar.gz

{devbits-1.1.2 → devbits-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devbits
-Version: 1.1.2
+Version: 1.2.0
 Summary: A lightweight CLI toolkit for daily development utilities.
 Author: Bruce Chuang
 License-Expression: MIT
@@ -80,6 +80,12 @@ clipvideo --help
 | `renamefiles` | Batch rename files sequentially. |
 | `samplefiles` | Copy or move the first N files to another folder. |
 
+### Network
+
+| Command | Description |
+|---------|-------------|
+| `netscan` | List devices connected to your local network (Wi-Fi / router) with their IP, MAC, and hostname. `--lookup` adds the manufacturer. |
+
 ## Examples
 
 ```bash
@@ -107,8 +113,22 @@ batchimages ./photos -o ./resized --size 800,600
 
 # Clean Python caches
 clearcache . --all
+
+# List every device on your local network
+netscan
+
+# Also identify each device's manufacturer (online OUI lookup)
+netscan --lookup
+
+# Scan a specific subnet, faster, without hostname lookups
+netscan --network 192.168.1.0/24 --timeout 0.5 --no-resolve
 ```
 
+> `netscan` reports IP, MAC, hostname and (with `--lookup`) the hardware
+> **manufacturer** — a network scan can't read a device's CPU/RAM/OS. Phones and
+> laptops that use a randomized/private MAC show up as `(private)` and can't be
+> attributed to a vendor.
+
 ## Output Defaults
 
 When `-o` / `--output` is omitted, the output filename is derived from the input:

{devbits-1.1.2 → devbits-1.2.0}/README.md

@@ -63,6 +63,12 @@ clipvideo --help
 | `renamefiles` | Batch rename files sequentially. |
 | `samplefiles` | Copy or move the first N files to another folder. |
 
+### Network
+
+| Command | Description |
+|---------|-------------|
+| `netscan` | List devices connected to your local network (Wi-Fi / router) with their IP, MAC, and hostname. `--lookup` adds the manufacturer. |
+
 ## Examples
 
 ```bash
@@ -90,8 +96,22 @@ batchimages ./photos -o ./resized --size 800,600
 
 # Clean Python caches
 clearcache . --all
+
+# List every device on your local network
+netscan
+
+# Also identify each device's manufacturer (online OUI lookup)
+netscan --lookup
+
+# Scan a specific subnet, faster, without hostname lookups
+netscan --network 192.168.1.0/24 --timeout 0.5 --no-resolve
 ```
 
+> `netscan` reports IP, MAC, hostname and (with `--lookup`) the hardware
+> **manufacturer** — a network scan can't read a device's CPU/RAM/OS. Phones and
+> laptops that use a randomized/private MAC show up as `(private)` and can't be
+> attributed to a vendor.
+
 ## Output Defaults
 
 When `-o` / `--output` is omitted, the output filename is derived from the input:

{devbits-1.1.2 → devbits-1.2.0}/devbits/__init__.py

@@ -1,3 +1,3 @@
 """devbits: A lightweight CLI toolkit for daily development utilities."""
 
-__version__ = "1.1.2"
+__version__ = "1.2.0"

{devbits-1.1.2 → devbits-1.2.0}/devbits/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import os
 import sys
 from pathlib import Path
 
@@ -8,10 +9,48 @@ from . import __version__
 from .cache import clear_cache
 from .image import batch_images, check_images, contact_sheet, image_to_ico, recolor_image, resize_image
 from .media import clip_video, images_to_gif, images_to_video, resize_video, video_to_gif, video_to_images
+from .network import scan_network
 from .project import print_tree, rename_files, sample_files, top_sizes
 from .utils import ensure_exists
 
 
+# ---------------------------------------------------------------------------
+# Helper: terminal colors
+# ---------------------------------------------------------------------------
+
+_ANSI = {
+    "dir": "\033[1;34m",
+    "file": "\033[0m",
+    "size": "\033[36m",
+    "header": "\033[1m",
+    "self": "\033[1;32m",
+    "gateway": "\033[1;33m",
+    "mac": "\033[36m",
+    "host": "\033[35m",
+    "vendor": "\033[33m",
+    "reset": "\033[0m",
+}
+
+
+def _use_color(force: bool | None = None) -> bool:
+    """Whether to emit ANSI colors: only on a TTY, unless overridden.
+
+    Honors the ``NO_COLOR`` convention (https://no-color.org). ``force`` of
+    ``True``/``False`` bypasses auto-detection (e.g. from a ``--no-color`` flag).
+    """
+    if force is not None:
+        return force
+    if os.environ.get("NO_COLOR"):
+        return False
+    return sys.stdout.isatty()
+
+
+def _colorize(text: str, kind: str, enabled: bool) -> str:
+    if not enabled:
+        return text
+    return f"{_ANSI[kind]}{text}{_ANSI['reset']}"
+
+
 # ---------------------------------------------------------------------------
 # Helper: derive default output path from input path
 # ---------------------------------------------------------------------------
@@ -344,6 +383,8 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Root folder to display. Default: current directory")
     p.add_argument("--depth", type=int, default=3,
                    help="Maximum depth to traverse. Default: 3")
+    p.add_argument("--no-color", action="store_true",
+                   help="Disable colored output (also honors NO_COLOR).")
     p.set_defaults(func=cmd_tree)
 
     # ── size ───────────────────────────────────────────────────
@@ -362,6 +403,8 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Folder to inspect. Default: current directory")
     p.add_argument("--top", type=int, default=20,
                    help="Number of items to show. Default: 20")
+    p.add_argument("--no-color", action="store_true",
+                   help="Disable colored output (also honors NO_COLOR).")
     p.set_defaults(func=cmd_size)
 
     # ── renamefiles ────────────────────────────────────────────
@@ -410,6 +453,39 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Move files instead of copying.")
     p.set_defaults(func=cmd_samplefiles)
 
+    # ── netscan ────────────────────────────────────────────────
+    p = sub.add_parser(
+        "netscan",
+        help="List devices connected to the local network (Wi-Fi / router).",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=(
+            "Discover hosts on your local subnet with a threaded ping sweep, then\n"
+            "report each device's IP, MAC address, and hostname. This machine and\n"
+            "the router (default gateway) are highlighted.\n\n"
+            "Scan only your own network; probing networks you don't administer may\n"
+            "violate policy or law.\n\n"
+            "Examples:\n"
+            "  devbits netscan\n"
+            "  devbits netscan --lookup                    # also show manufacturer\n"
+            "  devbits netscan --network 192.168.1.0/24\n"
+            "  devbits netscan --timeout 0.5 --workers 128 --no-resolve"
+        ),
+    )
+    p.add_argument("--network", metavar="CIDR", default=None,
+                   help="Subnet to scan in CIDR, e.g. 192.168.1.0/24. Default: auto-detected.")
+    p.add_argument("--timeout", type=float, default=1.0,
+                   help="Per-host ping timeout in seconds. Default: 1.0")
+    p.add_argument("--workers", type=int, default=64,
+                   help="Number of concurrent ping workers. Default: 64")
+    p.add_argument("--no-resolve", action="store_true",
+                   help="Skip reverse-DNS hostname lookups (faster).")
+    p.add_argument("--lookup", action="store_true",
+                   help="Resolve each device's manufacturer online via macvendors.com "
+                        "(sends MAC prefixes to a third-party service).")
+    p.add_argument("--no-color", action="store_true",
+                   help="Disable colored output (also honors NO_COLOR).")
+    p.set_defaults(func=cmd_netscan)
+
     return parser
 
 
@@ -509,13 +585,28 @@ def cmd_contactsheet(args: argparse.Namespace) -> None:
 
 
 def cmd_tree(args: argparse.Namespace) -> None:
+    color = _use_color(False if args.no_color else None)
     for line in print_tree(ensure_exists(args.folder), args.depth):
-        print(line)
+        if not color:
+            print(line)
+            continue
+        # Color only the name, leaving the tree-drawing prefix untouched.
+        marker = "── "
+        idx = line.rfind(marker)
+        split = idx + len(marker) if idx != -1 else 0
+        prefix, name = line[:split], line[split:]
+        kind = "dir" if name.endswith("/") else "file"
+        print(f"{prefix}{_colorize(name, kind, color)}")
 
 
 def cmd_size(args: argparse.Namespace) -> None:
+    color = _use_color(False if args.no_color else None)
     for path, _, size_text in top_sizes(ensure_exists(args.folder), args.top):
-        print(f"{size_text:>10}  {path}")
+        kind = "dir" if path.is_dir() else "file"
+        label = f"{path}{os.sep}" if path.is_dir() else str(path)
+        size_col = _colorize(f"{size_text:>10}", "size", color)
+        name_col = _colorize(label, kind, color)
+        print(f"{size_col}  {name_col}")
 
 
 def cmd_renamefiles(args: argparse.Namespace) -> None:
@@ -530,6 +621,37 @@ def cmd_samplefiles(args: argparse.Namespace) -> None:
     print(f"Saved {len(outputs)} file(s) to {args.output}")
 
 
+def cmd_netscan(args: argparse.Namespace) -> None:
+    import ipaddress
+
+    color = _use_color(False if args.no_color else None)
+    network = ipaddress.ip_network(args.network, strict=False) if args.network else None
+
+    from .network import default_network
+    net = network or default_network()
+    print(f"Scanning {net} ...", file=sys.stderr)
+
+    if args.lookup:
+        print("Looking up device manufacturers online ...", file=sys.stderr)
+    devices = scan_network(
+        net, timeout=args.timeout, workers=args.workers,
+        resolve=not args.no_resolve, lookup=args.lookup,
+    )
+
+    vendor_col_head = f"{'VENDOR':<24}" if args.lookup else ""
+    header = f"{'IP':<16}{'MAC':<20}{vendor_col_head}{'HOSTNAME':<28}NOTE"
+    print(_colorize(header, "header", color))
+    for device in devices:
+        note = "this device" if device.is_self else ("gateway / router" if device.is_gateway else "")
+        kind = "self" if device.is_self else ("gateway" if device.is_gateway else None)
+        ip_col = _colorize(f"{device.ip:<16}", kind, color) if kind else f"{device.ip:<16}"
+        mac_col = _colorize(f"{device.mac or '-':<20}", "mac", color)
+        vendor_col = _colorize(f"{device.vendor or '-':<24}", "vendor", color) if args.lookup else ""
+        host_col = _colorize(f"{device.hostname or '-':<28}", "host", color)
+        print(f"{ip_col}{mac_col}{vendor_col}{host_col}{note}")
+    print(f"Found {len(devices)} device(s).")
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)

devbits-1.2.0/devbits/network.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import concurrent.futures
+import ipaddress
+import platform
+import re
+import socket
+import ssl
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+_MAC_RE = re.compile(r"(?:[0-9a-fA-F]{1,2}[:-]){5}[0-9a-fA-F]{1,2}")
+_IP_RE = re.compile(r"\d{1,3}(?:\.\d{1,3}){3}")
+
+#: Label used for locally-administered (randomized / private) MAC addresses,
+#: which carry no manufacturer information.
+PRIVATE_MAC_LABEL = "(private)"
+
+_vendor_cache: dict[str, str | None] = {}
+
+
+@dataclass
+class Device:
+    """A single host discovered on the local network."""
+
+    ip: str
+    mac: str | None = None
+    hostname: str | None = None
+    vendor: str | None = None
+    is_self: bool = False
+    is_gateway: bool = False
+
+
+def local_ip() -> str:
+    """Best-effort primary IPv4 address of this machine.
+
+    Opens a UDP socket toward a public address to learn which local interface
+    would route outbound traffic. No packets are actually sent, so this works
+    offline as long as a network interface with a route exists (e.g. a LAN with
+    no internet). Falls back to the hostname's address, then loopback.
+    """
+    ip = ""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.connect(("8.8.8.8", 80))
+        ip = sock.getsockname()[0]
+    except OSError:
+        ip = ""
+    finally:
+        sock.close()
+    if not ip or ip.startswith("0."):
+        try:
+            ip = socket.gethostbyname(socket.gethostname())
+        except OSError:
+            ip = "127.0.0.1"
+    return ip
+
+
+def default_network(prefix: int = 24) -> ipaddress.IPv4Network:
+    """The local subnet containing this machine's primary address."""
+    return ipaddress.ip_network(f"{local_ip()}/{prefix}", strict=False)
+
+
+def gateway_ip() -> str | None:
+    """The default-gateway (router) address, or ``None`` if undetermined."""
+    system = platform.system().lower()
+    try:
+        if system == "windows":
+            out = subprocess.run(["route", "print", "0.0.0.0"], capture_output=True, text=True, timeout=5).stdout
+            for line in out.splitlines():
+                if line.strip().startswith("0.0.0.0"):
+                    ips = _IP_RE.findall(line)
+                    if len(ips) >= 3:
+                        return ips[2]  # destination, netmask, gateway
+            return None
+        if system == "darwin":
+            out = subprocess.run(["route", "-n", "get", "default"], capture_output=True, text=True, timeout=5).stdout
+            match = re.search(r"gateway:\s*(" + _IP_RE.pattern + ")", out)
+            return match.group(1) if match else None
+        # Linux and other Unixes
+        out = subprocess.run(["ip", "route"], capture_output=True, text=True, timeout=5).stdout
+        match = re.search(r"default via (" + _IP_RE.pattern + ")", out)
+        return match.group(1) if match else None
+    except Exception:
+        return None
+
+
+def _normalize_mac(mac: str) -> str:
+    parts = re.split(r"[:-]", mac)
+    return ":".join(part.zfill(2).lower() for part in parts)
+
+
+def is_private_mac(mac: str) -> bool:
+    """Whether ``mac`` is locally administered (a randomized / private address).
+
+    Modern phones and laptops rotate a random MAC per network for privacy. The
+    locally-administered bit (``0x02`` of the first octet) is set on these, and
+    they carry no manufacturer information, so an OUI lookup is pointless.
+    """
+    try:
+        return bool(int(mac.split(":")[0], 16) & 0x02)
+    except (ValueError, IndexError):
+        return False
+
+
+def lookup_vendor(mac: str, timeout: float = 3.0, retries: int = 2) -> str | None:
+    """Resolve the manufacturer for ``mac`` via the macvendors.com API (online).
+
+    Results are cached per OUI prefix for the life of the process. Returns
+    ``None`` when the vendor is unknown or the service is unreachable.
+
+    NOTE: this sends the MAC's first three octets to a third-party service; it
+    only runs when the caller explicitly opts in (``scan_network(lookup=True)``).
+    """
+    prefix = ":".join(mac.split(":")[:3])
+    if prefix in _vendor_cache:
+        return _vendor_cache[prefix]
+
+    request = urllib.request.Request(
+        f"https://api.macvendors.com/{mac}",
+        headers={"User-Agent": "devbits-netscan"},
+    )
+    # Fall back to an unverified (still-encrypted) context if the default CA
+    # bundle can't validate the cert — common on macOS Python.framework installs
+    # that never ran "Install Certificates.command". The payload is only a MAC
+    # OUI prefix and a vendor name, so this is acceptable here.
+    contexts = [None, ssl._create_unverified_context()]
+    vendor: str | None = None
+    for context in contexts:
+        for attempt in range(retries + 1):
+            try:
+                with urllib.request.urlopen(request, timeout=timeout, context=context) as response:
+                    vendor = response.read().decode("utf-8", "replace").strip() or None
+                _vendor_cache[prefix] = vendor
+                return vendor
+            except urllib.error.HTTPError as exc:
+                if exc.code == 429 and attempt < retries:  # rate limited: back off and retry
+                    time.sleep(1.2)
+                    continue
+                _vendor_cache[prefix] = None  # 404 / other HTTP error → unknown, don't retry other contexts
+                return None
+            except urllib.error.URLError as exc:
+                if isinstance(exc.reason, ssl.SSLError):
+                    break  # try the next (unverified) context
+                _vendor_cache[prefix] = None
+                return None
+            except Exception:
+                _vendor_cache[prefix] = None
+                return None
+    _vendor_cache[prefix] = vendor
+    return vendor
+
+
+def arp_table() -> dict[str, str]:
+    """Map ``IP -> MAC`` from the system ARP cache (cross-platform).
+
+    Tries each candidate command until one yields entries:
+
+    * Windows: ``arp -a`` (already numeric; it has no ``-n`` flag).
+    * macOS / Linux: ``arp -an`` — the ``-n`` avoids slow per-entry reverse DNS.
+    * Linux without net-tools (no ``arp``): ``ip neigh show`` as a fallback.
+    """
+    if platform.system().lower() == "windows":
+        commands = [["arp", "-a"]]
+    else:
+        commands = [["arp", "-an"], ["ip", "neigh", "show"]]
+
+    for command in commands:
+        try:
+            out = subprocess.run(command, capture_output=True, text=True, timeout=10).stdout
+        except Exception:
+            continue
+        table: dict[str, str] = {}
+        for line in out.splitlines():
+            ip_match = _IP_RE.search(line)
+            mac_match = _MAC_RE.search(line)
+            if ip_match and mac_match:
+                table[ip_match.group()] = _normalize_mac(mac_match.group())
+        if table:
+            return table
+    return {}
+
+
+def _ping(ip: str, timeout: float = 1.0) -> bool:
+    system = platform.system().lower()
+    if system == "windows":
+        cmd = ["ping", "-n", "1", "-w", str(int(timeout * 1000)), ip]
+    elif system == "darwin":
+        cmd = ["ping", "-c", "1", "-W", str(int(timeout * 1000)), ip]  # -W is milliseconds on macOS
+    else:
+        cmd = ["ping", "-c", "1", "-W", str(max(1, int(round(timeout)))), ip]  # -W is seconds on Linux
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout + 2)
+    except Exception:
+        return False
+    if result.returncode != 0:
+        return False
+    if system == "windows":
+        # Windows ping can exit 0 while printing "Destination host unreachable"
+        # (a reply from the gateway, not the target). Require a real echo reply.
+        return "ttl=" in result.stdout.lower()
+    return True
+
+
+def _resolve_hostname(ip: str) -> str | None:
+    try:
+        return socket.gethostbyaddr(ip)[0]
+    except Exception:
+        return None
+
+
+def scan_network(
+    network: ipaddress.IPv4Network | None = None,
+    timeout: float = 1.0,
+    workers: int = 64,
+    resolve: bool = True,
+    lookup: bool = False,
+) -> list[Device]:
+    """Discover live hosts on ``network`` via a threaded ICMP ping sweep.
+
+    After the sweep, the system ARP cache is read for MAC addresses and (unless
+    ``resolve`` is false) reverse DNS is queried for hostnames. This machine and
+    the default gateway are always included even if they don't answer pings.
+
+    When ``lookup`` is true, each MAC's manufacturer is resolved online (private
+    /randomized MACs are labelled instead) — see :func:`lookup_vendor`.
+    """
+    net = network or default_network()
+    self_ip = local_ip()
+    gateway = gateway_ip()
+
+    hosts = [str(host) for host in net.hosts()]
+    alive: set[str] = set()
+    with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, workers)) as executor:
+        futures = {executor.submit(_ping, ip, timeout): ip for ip in hosts}
+        for future in concurrent.futures.as_completed(futures):
+            if future.result():
+                alive.add(futures[future])
+
+    alive.add(self_ip)
+    if gateway and ipaddress.ip_address(gateway) in net:
+        alive.add(gateway)
+
+    arp = arp_table()
+    devices = [
+        Device(
+            ip=ip,
+            mac=arp.get(ip),
+            hostname=_resolve_hostname(ip) if resolve else None,
+            is_self=ip == self_ip,
+            is_gateway=ip == gateway,
+        )
+        for ip in alive
+    ]
+    if lookup:
+        for device in devices:
+            if not device.mac:
+                continue
+            device.vendor = PRIVATE_MAC_LABEL if is_private_mac(device.mac) else lookup_vendor(device.mac)
+
+    devices.sort(key=lambda device: tuple(int(octet) for octet in device.ip.split(".")))
+    return devices

{devbits-1.1.2 → devbits-1.2.0}/devbits/scripts.py

@@ -77,3 +77,7 @@ def renamefiles() -> int:
 
 def samplefiles() -> int:
     return _run("samplefiles")
+
+
+def netscan() -> int:
+    return _run("netscan")

{devbits-1.1.2 → devbits-1.2.0}/devbits/utils.py

@@ -108,5 +108,5 @@ def iter_project_tree(root: Path, ignore: Iterable[str], max_depth: int) -> list
                 walk(child, prefix + extension, depth + 1)
 
     lines.append(f"{root.name}/")
-    walk(root, max_depth=max_depth)
+    walk(root)
     return lines

{devbits-1.1.2 → devbits-1.2.0}/devbits.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devbits
-Version: 1.1.2
+Version: 1.2.0
 Summary: A lightweight CLI toolkit for daily development utilities.
 Author: Bruce Chuang
 License-Expression: MIT
@@ -80,6 +80,12 @@ clipvideo --help
 | `renamefiles` | Batch rename files sequentially. |
 | `samplefiles` | Copy or move the first N files to another folder. |
 
+### Network
+
+| Command | Description |
+|---------|-------------|
+| `netscan` | List devices connected to your local network (Wi-Fi / router) with their IP, MAC, and hostname. `--lookup` adds the manufacturer. |
+
 ## Examples
 
 ```bash
@@ -107,8 +113,22 @@ batchimages ./photos -o ./resized --size 800,600
 
 # Clean Python caches
 clearcache . --all
+
+# List every device on your local network
+netscan
+
+# Also identify each device's manufacturer (online OUI lookup)
+netscan --lookup
+
+# Scan a specific subnet, faster, without hostname lookups
+netscan --network 192.168.1.0/24 --timeout 0.5 --no-resolve
 ```
 
+> `netscan` reports IP, MAC, hostname and (with `--lookup`) the hardware
+> **manufacturer** — a network scan can't read a device's CPU/RAM/OS. Phones and
+> laptops that use a randomized/private MAC show up as `(private)` and can't be
+> attributed to a vendor.
+
 ## Output Defaults
 
 When `-o` / `--output` is omitted, the output filename is derived from the input:

{devbits-1.1.2 → devbits-1.2.0}/devbits.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ devbits/cli.py
 devbits/gui.py
 devbits/image.py
 devbits/media.py
+devbits/network.py
 devbits/project.py
 devbits/scripts.py
 devbits/utils.py

{devbits-1.1.2 → devbits-1.2.0}/devbits.egg-info/entry_points.txt

@@ -8,6 +8,7 @@ devbits = devbits.cli:main
 image2ico = devbits.scripts:image2ico
 images2gif = devbits.scripts:images2gif
 images2video = devbits.scripts:images2video
+netscan = devbits.scripts:netscan
 recolor = devbits.scripts:recolor
 renamefiles = devbits.scripts:renamefiles
 resizeimage = devbits.scripts:resizeimage

{devbits-1.1.2 → devbits-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devbits"
-version = "1.1.2"
+version = "1.2.0"
 description = "A lightweight CLI toolkit for daily development utilities."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -38,6 +38,7 @@ tree = "devbits.scripts:tree"
 size = "devbits.scripts:size"
 renamefiles = "devbits.scripts:renamefiles"
 samplefiles = "devbits.scripts:samplefiles"
+netscan = "devbits.scripts:netscan"
 
 [tool.setuptools.packages.find]
 include = ["devbits*"]

devbits-1.2.0/tests/test_cli.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import pytest
+
+from devbits.cli import main
+
+
+def test_help() -> None:
+    with pytest.raises(SystemExit) as exc:
+        main(["--help"])
+    assert exc.value.code == 0
+
+
+def test_clearcache_dry_run(tmp_path) -> None:
+    cache = tmp_path / "pkg" / "__pycache__"
+    cache.mkdir(parents=True)
+    (cache / "a.pyc").write_bytes(b"test")
+    assert main(["clearcache", str(tmp_path), "--dry-run"]) == 0
+
+
+def test_standalone_wrapper_help() -> None:
+    import pytest
+
+    from devbits.scripts import _run
+
+    with pytest.raises(SystemExit) as exc_info:
+        _run("clearcache", ["--help"])
+    assert exc_info.value.code == 0
+
+
+def test_netscan_help() -> None:
+    with pytest.raises(SystemExit) as exc:
+        main(["netscan", "--help"])
+    assert exc.value.code == 0
+
+
+def test_netscan_lists_devices(capsys, monkeypatch) -> None:
+    import ipaddress
+
+    from devbits.network import Device
+
+    fake = [
+        Device(ip="192.168.0.1", mac="06:f2:67:75:4d:e2", hostname=None, is_gateway=True),
+        Device(ip="192.168.0.50", mac="fc:91:5d:76:58:04", hostname="phone.local"),
+        Device(ip="192.168.0.203", mac="4e:cc:03:6c:47:f9", hostname=None, is_self=True),
+    ]
+    monkeypatch.setattr("devbits.cli.scan_network", lambda *a, **k: fake)
+    monkeypatch.setattr("devbits.network.default_network", lambda *a, **k: ipaddress.ip_network("192.168.0.0/24"))
+
+    assert main(["netscan", "--no-color", "--no-resolve"]) == 0
+    out = capsys.readouterr().out
+    assert "192.168.0.1" in out
+    assert "06:f2:67:75:4d:e2" in out
+    assert "gateway / router" in out
+    assert "this device" in out
+    assert "Found 3 device(s)." in out
+
+
+def test_netscan_arp_parsing() -> None:
+    from devbits.network import _MAC_RE, _normalize_mac
+
+    line = "? (192.168.0.1) at 6:f2:67:75:4d:e2 on en0 ifscope [ethernet]"
+    assert _normalize_mac(_MAC_RE.search(line).group()) == "06:f2:67:75:4d:e2"
+
+
+def test_arp_table_windows_command(monkeypatch) -> None:
+    # Windows arp has no -n flag; arp_table must use "arp -a" there.
+    import devbits.network as net
+
+    calls = []
+
+    class _Result:
+        stdout = "  192.168.0.1           aa-bb-cc-dd-ee-ff     dynamic"
+
+    def fake_run(cmd, **kwargs):
+        calls.append(cmd)
+        return _Result()
+
+    monkeypatch.setattr(net.platform, "system", lambda: "Windows")
+    monkeypatch.setattr(net.subprocess, "run", fake_run)
+    table = net.arp_table()
+    assert calls == [["arp", "-a"]]
+    assert table == {"192.168.0.1": "aa:bb:cc:dd:ee:ff"}
+
+
+def test_arp_table_linux_falls_back_to_ip_neigh(monkeypatch) -> None:
+    # When net-tools `arp` is missing, arp_table must fall back to `ip neigh`.
+    import devbits.network as net
+
+    calls = []
+
+    def fake_run(cmd, **kwargs):
+        calls.append(cmd)
+        if cmd[0] == "arp":
+            raise FileNotFoundError("arp not installed")
+
+        class _Result:
+            stdout = "192.168.0.1 dev eth0 lladdr aa:bb:cc:dd:ee:ff REACHABLE"
+
+        return _Result()
+
+    monkeypatch.setattr(net.platform, "system", lambda: "Linux")
+    monkeypatch.setattr(net.subprocess, "run", fake_run)
+    table = net.arp_table()
+    assert calls == [["arp", "-an"], ["ip", "neigh", "show"]]
+    assert table == {"192.168.0.1": "aa:bb:cc:dd:ee:ff"}
+
+
+def test_private_mac_detection() -> None:
+    from devbits.network import is_private_mac
+
+    assert is_private_mac("4e:cc:03:6c:47:f9")  # locally administered (0x02 bit set)
+    assert is_private_mac("06:f2:67:75:4d:e2")
+    assert not is_private_mac("fc:91:5d:76:58:04")  # globally unique OUI
+    assert not is_private_mac("b8:27:eb:11:22:33")
+
+
+def test_netscan_lookup_column(capsys, monkeypatch) -> None:
+    import ipaddress
+
+    import devbits.network as net
+    from devbits.network import scan_network
+
+    monkeypatch.setattr("devbits.cli.scan_network", scan_network)
+    monkeypatch.setattr(net, "_ping", lambda ip, timeout=1.0: False)
+    monkeypatch.setattr(net, "arp_table", lambda: {
+        "192.168.0.1": "fc:91:5d:76:58:04",
+        "192.168.0.203": "4e:cc:03:6c:47:f9",
+    })
+    monkeypatch.setattr(net, "local_ip", lambda: "192.168.0.203")
+    monkeypatch.setattr(net, "gateway_ip", lambda: "192.168.0.1")
+    monkeypatch.setattr(net, "default_network", lambda *a, **k: ipaddress.ip_network("192.168.0.0/24"))
+    monkeypatch.setattr(net, "lookup_vendor", lambda mac, **k: "Google, Inc.")
+
+    assert main(["netscan", "--no-color", "--no-resolve", "--lookup"]) == 0
+    out = capsys.readouterr().out
+    assert "VENDOR" in out
+    assert "Google, Inc." in out
+    assert "(private)" in out  # randomized MAC of the self device

devbits-1.1.2/tests/test_cli.py

@@ -1,28 +0,0 @@
-from __future__ import annotations
-
-import pytest
-
-from devbits.cli import main
-
-
-def test_help() -> None:
-    with pytest.raises(SystemExit) as exc:
-        main(["--help"])
-    assert exc.value.code == 0
-
-
-def test_clearcache_dry_run(tmp_path) -> None:
-    cache = tmp_path / "pkg" / "__pycache__"
-    cache.mkdir(parents=True)
-    (cache / "a.pyc").write_bytes(b"test")
-    assert main(["clearcache", str(tmp_path), "--dry-run"]) == 0
-
-
-def test_standalone_wrapper_help() -> None:
-    import pytest
-
-    from devbits.scripts import _run
-
-    with pytest.raises(SystemExit) as exc_info:
-        _run("clearcache", ["--help"])
-    assert exc_info.value.code == 0