qshare 0.2.0__py3-none-win_amd64.whl

qshare/__init__.py

@@ -0,0 +1,5 @@
+"""qshare package."""
+
+from .cli import main
+
+__all__ = ["main"]

qshare/__main__.py

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

qshare/_binaries/cloudflared.exe

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: qshare/_binaries/cloudflared.exe
+size: 54976432 bytes
+sha256: 2837888cc0f5d58f15b6dc478376de90b4d3ba5241c7947455d1e0a0df429712

qshare/cli.py

@@ -0,0 +1,464 @@
+import argparse
+import os
+import re
+import signal
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import uuid
+import qrcode
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Iterable, List, Optional, Tuple, Union
+
+DEFAULT_TTL_SECONDS = 2 * 60 * 60
+
+
+def parse_duration(value: Union[str, int, float]) -> int:
+    """Convert duration strings like 30m, 90s, 2h to seconds."""
+    if isinstance(value, (int, float)):
+        seconds = int(value)
+        if seconds <= 0:
+            raise ValueError("Duration must be positive.")
+        return seconds
+
+    text = str(value).strip().lower()
+    if not text:
+        raise ValueError("Duration is required.")
+
+    if text.isdigit():
+        return int(text)
+
+    match = re.fullmatch(r"(?P<number>\d+)(?P<unit>[smhd]?)", text)
+    if not match:
+        raise ValueError(f"Unsupported duration: {value!r}. Use 30m, 90s, 2h, or plain seconds.")
+
+    number = int(match.group("number"))
+    unit = match.group("unit") or "s"
+    multipliers = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+    seconds = number * multipliers[unit]
+    if seconds <= 0:
+        raise ValueError("Duration must be greater than zero.")
+    return seconds
+
+
+def find_available_port(
+    start_port: int = 20000,
+    end_port: int = 65535,
+    used_ports: Optional[Iterable[int]] = None,
+) -> int:
+    """Return a free localhost port, avoiding the given ports."""
+    blacklisted = set(used_ports or [])
+    ports = list(range(start_port, end_port + 1))
+    import random
+
+    random.shuffle(ports)
+    for port in ports:
+        if port in blacklisted:
+            continue
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+    raise OSError(f"No free port found between {start_port} and {end_port}.")
+
+
+def extract_trycloudflare_url(output: str) -> Optional[str]:
+    for match in re.finditer(r"https://(?P<host>[A-Za-z0-9-]+\.trycloudflare\.com)", output, re.IGNORECASE):
+        if match.group("host").lower() != "api.trycloudflare.com":
+            return match.group(0)
+    return None
+
+
+def build_download_url(base_url: str, file_name: str) -> str:
+    cleaned_base = base_url.rstrip("/")
+    cleaned_name = file_name.lstrip("/")
+    return f"{cleaned_base}/{cleaned_name}"
+
+
+def print_qr_code(url: str) -> None:
+    qr = qrcode.QRCode(
+        error_correction=qrcode.constants.ERROR_CORRECT_L,
+        border=1,
+    )
+    qr.add_data(url)
+    qr.make(fit=True)
+    print("Scan this QR code to open the public file URL:")
+    # Two QR rows per terminal row keeps the code compact and scannable.
+    qr.print_ascii(invert=True)
+
+
+class ShareHandler(SimpleHTTPRequestHandler):
+    def log_message(self, format: str, *args: object) -> None:  # noqa: A003
+        return
+
+
+def start_local_http_server(file_path: Path, port: int) -> Tuple[ThreadingHTTPServer, threading.Thread]:
+    if not file_path.exists():
+        raise FileNotFoundError(f"File does not exist: {file_path}")
+    if not file_path.is_file():
+        raise ValueError(f"Path is not a file: {file_path}")
+
+    server = ThreadingHTTPServer(("127.0.0.1", port), partial(ShareHandler, directory=str(file_path.parent)))
+    thread = threading.Thread(target=server.serve_forever, name="qshare-http", daemon=True)
+    thread.start()
+    return server, thread
+
+
+def stop_local_http_server(server: ThreadingHTTPServer) -> None:
+    try:
+        server.shutdown()
+    except Exception:
+        pass
+    try:
+        server.server_close()
+    except Exception:
+        pass
+
+
+def get_bundled_cloudflared_binary() -> Path:
+    name = "cloudflared.exe" if os.name == "nt" else "cloudflared"
+    bundled = Path(__file__).resolve().parent / "_binaries" / name
+    if not bundled.is_file():
+        raise RuntimeError(
+            "This qshare installation has no bundled cloudflared binary for this platform. "
+            "Install qshare from PyPI on a supported platform, or install cloudflared yourself and add it to PATH."
+        )
+    return bundled
+
+
+def install_cloudflared_binary() -> str:
+    target_dir = Path.home() / ".local" / "bin"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / ("cloudflared.exe" if os.name == "nt" else "cloudflared")
+
+    if target.exists():
+        return str(target)
+
+    try:
+        print("cloudflared was not found. Installing the binary bundled with qshare...")
+        shutil.copyfile(str(get_bundled_cloudflared_binary()), str(target))
+        if os.name != "nt":
+            target.chmod(0o755)
+        return str(target)
+    except Exception:
+        if target.exists():
+            target.unlink()
+        raise
+
+
+def ensure_cloudflared() -> str:
+    binary_path = shutil.which("cloudflared")
+    if binary_path:
+        return binary_path
+
+    user_bin = Path.home() / ".local" / "bin" / ("cloudflared.exe" if os.name == "nt" else "cloudflared")
+    if user_bin.exists():
+        return str(user_bin)
+
+    installed = install_cloudflared_binary()
+    os.environ["PATH"] = str(Path(installed).parent) + os.pathsep + os.environ.get("PATH", "")
+    return installed
+
+
+def launch_trycloudflare_tunnel(local_url: str, timeout_seconds: int) -> Tuple[subprocess.Popen, str]:
+    cloudflared_path = ensure_cloudflared()
+    deadline = time.monotonic() + timeout_seconds
+    for attempt in range(3):
+        logfile = Path(tempfile.gettempdir()) / f"qshare-{uuid.uuid4().hex}.log"
+        kwargs = {
+            "stdout": subprocess.PIPE,
+            "stderr": subprocess.STDOUT,
+            "universal_newlines": True,
+            "bufsize": 1,
+        }
+        if os.name == "nt":
+            kwargs["creationflags"] = (
+                getattr(subprocess, "CREATE_NO_WINDOW", 0)
+                | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+                | getattr(subprocess, "DETACHED_PROCESS", 0)
+            )
+        process = subprocess.Popen(
+            [cloudflared_path, "tunnel", "--url", local_url, "--no-autoupdate", "--logfile", str(logfile)],
+            **kwargs,
+        )
+        if process.stdout is None:
+            raise RuntimeError("Unable to capture cloudflared output.")
+
+        attempt_deadline = min(deadline, time.monotonic() + 10)
+        while time.monotonic() < attempt_deadline:
+            line = process.stdout.readline()
+            if line:
+                url = extract_trycloudflare_url(line)
+                if url:
+                    return process, url
+                continue
+            if process.poll() is not None:
+                break
+            time.sleep(0.2)
+
+        stop_tunnel(process)
+        if time.monotonic() < deadline and attempt < 2:
+            print("Cloudflare did not provide a valid public URL; retrying...")
+
+    raise TimeoutError(f"Timed out waiting for a valid public TryCloudflare URL in {timeout_seconds} seconds.")
+
+
+def stop_tunnel(process: subprocess.Popen) -> None:
+    if process.poll() is None:
+        try:
+            process.terminate()
+            process.wait(timeout=5)
+        except Exception:
+            try:
+                process.kill()
+            except Exception:
+                pass
+
+
+class DetachedTunnelProcess:
+    """Minimal Popen-compatible handle for an inherited orphaned tunnel."""
+
+    def __init__(self, pid: int) -> None:
+        self.pid = pid
+
+    def poll(self) -> Optional[int]:
+        try:
+            os.kill(self.pid, 0)
+        except OSError:
+            return 0
+        return None
+
+    def terminate(self) -> None:
+        os.kill(self.pid, signal.SIGTERM)
+
+    def wait(self, timeout: Optional[float] = None) -> int:
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while self.poll() is None:
+            if deadline is not None and time.monotonic() >= deadline:
+                raise subprocess.TimeoutExpired(["cloudflared"], timeout)
+            time.sleep(0.1)
+        return 0
+
+    def kill(self) -> None:
+        os.kill(self.pid, signal.SIGKILL)
+
+
+def run_share(file_path: str, ttl_seconds: int = DEFAULT_TTL_SECONDS, port: Optional[int] = None) -> int:
+    source = Path(file_path).expanduser().resolve()
+    if not source.exists():
+        raise FileNotFoundError(f"File not found: {source}")
+    if not source.is_file():
+        raise ValueError(f"Not a file: {source}")
+
+    resolved_port = port or find_available_port()
+    server, server_thread = start_local_http_server(source, resolved_port)
+    local_url = f"http://127.0.0.1:{resolved_port}/{source.name}"
+
+    print(f"Local file: {source}")
+    print(f"Local HTTP URL: {local_url}")
+    print(f"Waiting for public TryCloudflare URL (ttl={ttl_seconds}s)...")
+
+    tunnel_process = None
+    tunnel_url = None
+    stop_event = threading.Event()
+
+    detached = False
+
+    def stop_all() -> None:
+        stop_event.set()
+        if tunnel_process is not None:
+            stop_tunnel(tunnel_process)
+        stop_local_http_server(server)
+        if server_thread.is_alive():
+            server_thread.join(timeout=2)
+
+    def expire() -> None:
+        if not detached:
+            print("TTL expired; the public share has stopped.", flush=True)
+        stop_all()
+
+    timer = threading.Timer(ttl_seconds, expire)
+    timer.daemon = True
+    timer.start()
+
+    try:
+        tunnel_process, tunnel_url = launch_trycloudflare_tunnel(local_url, timeout_seconds=min(ttl_seconds, 30))
+        public_file_url = build_download_url(tunnel_url, source.name)
+        print("\n" + "=" * 72)
+        print(f"PUBLIC FILE URL: {public_file_url}")
+        print("=" * 72 + "\n", flush=True)
+        print_qr_code(public_file_url)
+        # A detached child is already the background worker.  Prompting it
+        # again (with stdin connected to DEVNULL) makes it take the
+        # foreground path accidentally and, more importantly, used to make
+        # the hand-off look as if the original service had simply died.
+        if os.name != "nt" and os.environ.get("QSHARE_BACKGROUND_CHILD") != "1" and ask_background_mode():
+            handoff = detach_existing_process(server)
+            if handoff is True:
+                # Parent exits, while the child keeps the inherited server
+                # socket and cloudflared process (therefore the same URL).
+                detached = True
+                return 0
+            if handoff is None:
+                # Windows cannot safely detach this interpreter from its
+                # console while retaining the inherited server/tunnel. Keep
+                # this process running instead of launching a replacement
+                # qshare (which would change the tunnel URL).
+                if os.name == "nt":
+                    detached = True
+                    print("Running in background mode; keep this window open to retain the same URL.")
+                    # Fall through to the normal lifetime loop.
+                # Other non-fork platforms retain the independent-worker
+                # fallback.
+                detached = True
+                background_argv = [str(source), "--ttl", str(ttl_seconds)]
+                if port is not None:
+                    background_argv.extend(["--port", str(port)])
+                return start_background_process(background_argv)
+            # Child: the pre-fork timer thread no longer exists, so recreate
+            # it before entering the normal lifetime loop.
+            detached = True
+            tunnel_process = DetachedTunnelProcess(tunnel_process.pid)
+            timer = threading.Timer(ttl_seconds, expire)
+            timer.daemon = True
+            timer.start()
+        while not stop_event.is_set() and tunnel_process.poll() is None:
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        print("\nInterrupted by user.")
+        stop_all()
+        return 0
+    except Exception:
+        stop_all()
+        raise
+    finally:
+        timer.cancel()
+        if not detached:
+            stop_all()
+
+    return 0
+
+
+def should_run_in_background(answer: str) -> bool:
+    return str(answer or "").strip().lower() == "d"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Quickly share a local file over a public TryCloudflare tunnel.",
+        prog="qshare",
+    )
+    parser.add_argument("file", help="Local file to share publicly.")
+    parser.add_argument(
+        "-t",
+        "--ttl",
+        default="2h",
+        help="How long the tunnel remains active. Examples: 2h, 30m, 90s, or 600 (seconds).",
+    )
+    parser.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=None,
+        help="Optional fixed port for the local HTTP server. A random free port is used when omitted.",
+    )
+    return parser
+
+
+def start_background_process(argv: List[str]) -> int:
+    cmd = [sys.executable, "-m", "qshare"] + argv
+    env = os.environ.copy()
+    env["QSHARE_BACKGROUND_CHILD"] = "1"
+    kwargs = {
+        "stdin": subprocess.DEVNULL,
+        # Keep the child's status and (most importantly) its replacement
+        # public URL visible to the user.  The parent URL belongs to the
+        # short-lived process and cannot remain valid after hand-off.
+        "stdout": None,
+        "stderr": None,
+        "env": env,
+    }
+    if os.name == "nt":
+        creationflags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+        kwargs["creationflags"] = creationflags
+    else:
+        kwargs["start_new_session"] = True
+    subprocess.Popen(cmd, **kwargs)
+    print("qshare started in background.")
+    return 0
+
+
+def detach_existing_process(server: ThreadingHTTPServer) -> Optional[bool]:
+    """Detach while retaining the existing HTTP socket and tunnel process.
+
+    Returns True in the short-lived parent, False in the detached child, and
+    None on platforms without fork support.
+    """
+    if os.name == "nt":
+        return None
+    if not hasattr(os, "fork"):
+        return None
+    child_pid = os.fork()
+    if child_pid:
+        return True
+
+    # The serving thread does not survive fork.  Reuse the inherited socket
+    # and start a replacement thread; the cloudflared Popen process is also
+    # inherited, so its public hostname remains unchanged.
+    os.setsid()
+    try:
+        with open(os.devnull, "rb") as null_in, open(os.devnull, "ab") as null_out:
+            os.dup2(null_in.fileno(), sys.stdin.fileno())
+            os.dup2(null_out.fileno(), sys.stdout.fileno())
+            os.dup2(null_out.fileno(), sys.stderr.fileno())
+    except (OSError, ValueError):
+        pass
+    threading.Thread(target=server.serve_forever, name="qshare-http", daemon=True).start()
+    return False
+
+
+def ask_background_mode() -> bool:
+    try:
+        answer = input("Run in background? Press 'd' to detach, or press Enter to keep in the foreground: ")
+    except EOFError:
+        return False
+    return should_run_in_background(answer)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if os.environ.get("QSHARE_BACKGROUND_CHILD") == "1":
+        try:
+            ttl_seconds = parse_duration(args.ttl)
+            return run_share(args.file, ttl_seconds=ttl_seconds, port=args.port)
+        except KeyboardInterrupt:
+            print("\nStopped.")
+            return 130
+        except Exception as exc:  # pragma: no cover - CLI-level output
+            print(f"qshare error: {exc}", file=sys.stderr)
+            return 1
+
+    try:
+        ttl_seconds = parse_duration(args.ttl)
+        return run_share(args.file, ttl_seconds=ttl_seconds, port=args.port)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+        return 130
+    except Exception as exc:  # pragma: no cover - CLI-level output
+        print(f"qshare error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qshare-0.2.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.3
+Name: qshare
+Version: 0.2.0
+Summary: Quickly share local files through a public TryCloudflare tunnel.
+Author: steinvenic
+Author-email: steinvenic <761701732@qq.com>
+Requires-Dist: qrcode==7.3
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+
+# qshare
+
+Quickly share a local file via a public TryCloudflare tunnel.
+
+## Features
+
+- Start a temporary local HTTP server on a random free port
+- Detect and avoid occupied ports automatically
+- Create a public TryCloudflare URL for the file
+- Support a default lifetime of 2 hours, adjustable via CLI arguments
+- Works on Linux, Windows, and macOS with a platform-specific bundled cloudflared binary
+- Ready for uv-managed development and PyPI packaging
+
+## Requirements
+
+- Python 3.6+
+- qshare platform wheels include the matching official `cloudflared` binary. qshare never downloads a binary at runtime; update qshare from PyPI to receive an updated bundled binary.
+
+On a platform without a matching wheel, install `cloudflared` manually and add it to `PATH`.
+
+## Install
+
+Using uv:
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+```
+
+Or install from PyPI after publishing:
+
+```bash
+pip install qshare
+```
+
+## Usage
+
+```bash
+qshare /path/to/file.zip
+qshare /path/to/file.zip --ttl 2h
+qshare /path/to/file.zip --ttl 900
+qshare /path/to/file.zip --port 8000
+```
+
+The command starts a local HTTP server on a random free port, creates a temporary public URL with TryCloudflare, and keeps the tunnel alive for the configured duration. If `cloudflared` is absent from `PATH`, qshare installs the binary bundled in the matching PyPI wheel into `~/.local/bin`. Platform wheels are available for Cloudflare's Linux (x86, x86_64, ARM, ARMHF, ARM64), Windows (x86, x86_64), and macOS (Intel, Apple Silicon) releases.
+
+After the public URL is printed prominently, qshare displays a terminal QR code for the same link. qshare accepts only a valid share hostname such as `https://department-specialists-excellence-savings.trycloudflare.com`; Cloudflare API URLs are rejected and the tunnel is retried. On Unix-like systems it then prompts: `Run in background? Press 'd' to detach, or press Enter to keep in the foreground.` Windows always runs in the foreground. When the TTL expires in foreground mode, qshare prints a notification and stops the share.
+
+## Build for PyPI
+
+```bash
+uv build
+python scripts/build_platform_wheels.py --assets-dir /path/to/cloudflared-assets
+```
+
+Then upload the resulting artifacts from the `dist/` directory to PyPI.
+
+## Notes
+
+- The default lifetime is 2 hours.
+- If a port is occupied, qshare automatically selects another free port.
+- `--ttl` accepts values like `30m`, `90s`, `2h`, or a plain number in seconds.
+- Background mode is triggered by entering `d` at the interactive prompt after the public URL appears.

qshare-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+qshare-0.2.0.dist-info/,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qshare-0.2.0.dist-info/METADATA,sha256=qJD28ujsZV8UZ7euyDrHgJwMUO1Zt4L0e4WqQCmZ1Ik,2836
+qshare-0.2.0.dist-info/WHEEL,sha256=UwKY2Z8fbdPcg13t7_TnpAXl2n8eG4G4JQJLC4nARyk,88
+qshare-0.2.0.dist-info/entry_points.txt,sha256=4CVmwudLjYg8tF-MFd_5pl8jfvYjtwaDOtVkT8SkkM8,44
+qshare/,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qshare/__init__.py,sha256=37TXLwS35XmGk5BxwSjeitivOpazoHmUEs3b61kwSrU,65
+qshare/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+qshare/_binaries/cloudflared.exe,sha256=KDeIjMD11Y8VttxHg3bekLTTulJBx5R0VdHgoN9ClxI,54976432
+qshare/cli.py,sha256=XNMMybQ961LGsSZk0KOidK4F8JYxHCCKe8W_0XM9DPs,16108
+qshare-0.2.0.dist-info/RECORD,,

qshare-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.18
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

qshare-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+qshare = qshare.cli:main
+