pywget 2.0.2__py3-none-any.whl

pywget/errors.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+
+# File: pywget/errors.py
+# Author: Hadi Cahyadi <cumulus13@gmail.com>
+# Date: 2026-10-25
+# Description: Exception hierarchy. Every exception carries a CLI ``exit_code``.
+# License: MIT
+
+"""Exception hierarchy. Every exception carries a CLI ``exit_code``."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+RETRY_STATUS = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+
+class PywgetError(Exception):
+    """Base class for all pywget errors."""
+
+    exit_code = 1
+
+
+class InvalidURLError(PywgetError):
+    exit_code = 2
+
+
+class NetworkError(PywgetError):
+    """Transport-level failure. ``retryable`` tells the engine whether to retry."""
+
+    exit_code = 3
+
+    def __init__(self, message: str, retryable: bool = True) -> None:
+        super().__init__(message)
+        self.retryable = retryable
+        self.retry_after: Optional[float] = None
+
+
+class HTTPStatusError(NetworkError):
+    exit_code = 4
+
+    def __init__(
+        self,
+        status: int,
+        url: str,
+        reason: str = "",
+        retry_after: Optional[float] = None,
+    ) -> None:
+        text = f"HTTP {status} {reason}".strip()
+        super().__init__(f"{text} for {url}", retryable=status in RETRY_STATUS)
+        self.status = status
+        self.url = url
+        self.retry_after = retry_after
+
+
+class ChecksumError(PywgetError):
+    exit_code = 5
+
+
+class StorageError(PywgetError):
+    exit_code = 6
+
+
+class DownloadCancelled(PywgetError):
+    exit_code = 130

pywget/progress.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+
+# File: pywget/progress.py
+# Author: Hadi Cahyadi <cumulus13@gmail.com>
+# Date: 2026-10-25
+# Description: Progress tracking and terminal rendering.
+# License: MIT
+
+"""Progress tracking and terminal rendering."""
+
+from __future__ import annotations
+
+import collections
+import shutil
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from typing import Deque, Optional, TextIO, Tuple
+
+from .utils import format_duration, format_size
+
+
+@dataclass(frozen=True)
+class ProgressInfo:
+    url: str
+    filename: str
+    downloaded: int
+    total: Optional[int]
+    speed: float
+    eta: Optional[float]
+    elapsed: float
+    finished: bool = False
+
+    @property
+    def percent(self) -> Optional[float]:
+        if self.total is None:
+            return None
+        if self.total == 0:
+            return 100.0
+        return min(100.0, self.downloaded * 100.0 / self.total)
+
+
+class Tracker:
+    """Thread-safe byte counter producing speed/ETA snapshots."""
+
+    WINDOW = 5.0
+
+    def __init__(self, url: str, filename: str, total: Optional[int]) -> None:
+        self.url = url
+        self.filename = filename
+        self.total = total
+        self._lock = threading.Lock()
+        self._downloaded = 0
+        self._start = time.monotonic()
+        self._samples: Deque[Tuple[float, int]] = collections.deque()
+        self._samples.append((self._start, 0))
+
+    def add(self, nbytes: int) -> None:
+        with self._lock:
+            self._downloaded += nbytes
+
+    def set(self, nbytes: int) -> None:
+        with self._lock:
+            self._downloaded = nbytes
+            self._samples.clear()
+            self._samples.append((time.monotonic(), nbytes))
+
+    def reset(self) -> None:
+        self.set(0)
+
+    @property
+    def downloaded(self) -> int:
+        with self._lock:
+            return self._downloaded
+
+    def snapshot(self, finished: bool = False) -> ProgressInfo:
+        now = time.monotonic()
+        with self._lock:
+            done = self._downloaded
+            self._samples.append((now, done))
+            while len(self._samples) > 2 and now - self._samples[0][0] > self.WINDOW:
+                self._samples.popleft()
+            t0, b0 = self._samples[0]
+        speed = max((done - b0) / (now - t0), 0.0) if now > t0 else 0.0
+        eta = None
+        if self.total is not None and speed > 0:
+            eta = max(self.total - done, 0) / speed
+        return ProgressInfo(
+            self.url, self.filename, done, self.total, speed, eta, now - self._start, finished
+        )
+
+
+def _truncate(text: str, width: int) -> str:
+    return text if len(text) <= width else text[: max(width - 2, 1)] + ".."
+
+
+class ProgressBar:
+    """Single-line ASCII progress bar; silent when the stream is not a TTY."""
+
+    def __init__(
+        self,
+        stream: Optional[TextIO] = None,
+        enabled: bool = True,
+        min_interval: float = 0.1,
+    ) -> None:
+        self.stream = stream if stream is not None else sys.stderr
+        self.enabled = enabled
+        self.min_interval = min_interval
+        isatty = getattr(self.stream, "isatty", None)
+        self._tty = bool(isatty and isatty())
+        self._last = 0.0
+        self._last_len = 0
+        self._dirty = False
+
+    def __call__(self, info: ProgressInfo) -> None:
+        self.update(info)
+
+    def update(self, info: ProgressInfo) -> None:
+        if not (self.enabled and self._tty):
+            return
+        now = time.monotonic()
+        if not info.finished and now - self._last < self.min_interval:
+            return
+        self._last = now
+        line = self._format(info)
+        pad = " " * max(0, self._last_len - len(line))
+        self.stream.write("\r" + line + pad)
+        self.stream.flush()
+        self._last_len = len(line)
+        self._dirty = True
+        if info.finished:
+            self.close()
+
+    def close(self) -> None:
+        if self._dirty:
+            self.stream.write("\n")
+            self.stream.flush()
+        self._dirty = False
+        self._last_len = 0
+
+    @staticmethod
+    def _format(info: ProgressInfo) -> str:
+        cols = shutil.get_terminal_size((80, 24)).columns - 1
+        pct = f"{info.percent:5.1f}%" if info.percent is not None else "   --%"
+        size = format_size(info.downloaded)
+        if info.total is not None:
+            size += f"/{format_size(info.total)}"
+        tail = f"{pct} {size} {format_size(info.speed)}/s ETA {format_duration(info.eta)}"
+        name_w = max(8, min(28, cols // 4))
+        name = _truncate(info.filename, name_w).ljust(name_w)
+        room = cols - len(name) - len(tail) - 4
+        if info.percent is not None and room >= 12:
+            inner_w = room - 2
+            filled = int(inner_w * info.percent / 100)
+            inner = ("=" * filled + (">" if filled < inner_w else "")).ljust(inner_w)[:inner_w]
+            return f"{name} [{inner}] {tail}"
+        return f"{name} {tail}"[:cols]

pywget/utils.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+
+# File: pywget/utils.py
+# Author: Hadi Cahyadi <cumulus13@gmail.com>
+# Date: 2026-10-25
+# Description: Pure helpers: parsing, formatting, filenames, hashing, rate limiting.
+# License: MIT
+
+"""Pure helpers: parsing, formatting, filenames, hashing, rate limiting."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import threading
+import time
+import unicodedata
+from email.message import Message
+from pathlib import Path
+from typing import Optional, Tuple, Union
+from urllib.parse import quote, unquote, urlsplit, urlunsplit
+
+from .errors import InvalidURLError
+
+_SIZE_RE = re.compile(r"^\s*(\d+(?:\.\d+)?)\s*([kmgt]?)(i?b)?\s*$", re.I)
+_UNITS = {"": 1, "k": 1024, "m": 1024**2, "g": 1024**3, "t": 1024**4}
+_BAD_CHARS = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+_RESERVED = {"con", "prn", "aux", "nul"} | {f"com{i}" for i in range(1, 10)} | {
+    f"lpt{i}" for i in range(1, 10)
+}
+_HEX = re.compile(r"^[0-9a-f]+$")
+_GUESS_ALGO = {32: "md5", 40: "sha1", 64: "sha256", 128: "sha512"}
+
+
+def parse_size(value: Union[str, int, float]) -> int:
+    """Parse ``500k`` / ``2MiB`` / ``1.5G`` into bytes."""
+    if isinstance(value, (int, float)):
+        return int(value)
+    match = _SIZE_RE.match(str(value))
+    if not match:
+        raise ValueError(f"invalid size: {value!r}")
+    return int(float(match.group(1)) * _UNITS[match.group(2).lower()])
+
+
+def format_size(num: float) -> str:
+    num = float(num)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if abs(num) < 1024 or unit == "TiB":
+            return f"{int(num)} B" if unit == "B" else f"{num:.1f} {unit}"
+        num /= 1024
+    return f"{num:.1f} TiB"  # pragma: no cover
+
+
+def format_duration(seconds: Optional[float]) -> str:
+    if seconds is None or seconds != seconds or seconds < 0 or seconds > 99 * 3600:
+        return "--:--"
+    seconds = int(seconds)
+    hours, rest = divmod(seconds, 3600)
+    minutes, secs = divmod(rest, 60)
+    return f"{hours:d}:{minutes:02d}:{secs:02d}" if hours else f"{minutes:02d}:{secs:02d}"
+
+
+def sanitize_filename(name: Optional[str], default: str = "index.html") -> str:
+    """Return a safe single path component (no traversal, no reserved names)."""
+    name = unicodedata.normalize("NFC", name or "")
+    name = name.replace("\\", "/").rsplit("/", 1)[-1]
+    name = _BAD_CHARS.sub("_", name).strip().rstrip(" .")
+    if not name:
+        return default
+    if name.split(".")[0].lower() in _RESERVED:
+        name = "_" + name
+    if len(name.encode("utf-8")) > 200:
+        root, ext = os.path.splitext(name)
+        ext = ext[:20]
+        budget = 200 - len(ext.encode("utf-8"))
+        name = root.encode("utf-8")[:budget].decode("utf-8", "ignore") + ext
+    return name
+
+
+def filename_from_content_disposition(value: Optional[str]) -> Optional[str]:
+    if not value:
+        return None
+    msg = Message()
+    msg["Content-Disposition"] = value
+    try:
+        filename = msg.get_filename()
+    except Exception:  # malformed header
+        return None
+    return filename or None
+
+
+def filename_from_url(url: str) -> Optional[str]:
+    return unquote(urlsplit(url).path.rsplit("/", 1)[-1]) or None
+
+
+def unique_path(path: Path) -> Path:
+    """``file.txt`` -> ``file.txt.1`` -> ``file.txt.2`` (wget style)."""
+    if not path.exists():
+        return path
+    for index in range(1, 10_000):
+        candidate = path.with_name(f"{path.name}.{index}")
+        if not candidate.exists() and not Path(f"{candidate}.part").exists():
+            return candidate
+    raise FileExistsError(f"cannot find a free name for {path}")
+
+
+def parse_checksum(spec: str) -> Tuple[str, str]:
+    """``sha256:<hex>`` or a bare hex digest (algorithm guessed by length)."""
+    algo, sep, digest = spec.strip().partition(":")
+    if not sep:
+        digest = algo
+        guessed = _GUESS_ALGO.get(len(digest))
+        if not guessed:
+            raise ValueError("cannot guess hash algorithm; use ALGO:HEX")
+        algo = guessed
+    algo = algo.lower().replace("-", "")
+    digest = digest.strip().lower()
+    if algo not in hashlib.algorithms_guaranteed or algo.startswith("shake"):
+        raise ValueError(f"unsupported hash algorithm: {algo}")
+    if not digest or not _HEX.match(digest):
+        raise ValueError("checksum digest must be hexadecimal")
+    return algo, digest
+
+
+def hash_file(path: Union[str, Path], algo: str) -> str:
+    digest = hashlib.new(algo)
+    with open(path, "rb") as handle:
+        for block in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def normalize_url(url: str) -> Tuple[str, Optional[str], Optional[str]]:
+    """Validate an http(s) URL; return (clean_url, username, password)."""
+    url = (url or "").strip()
+    try:
+        parts = urlsplit(url)
+        host = parts.hostname
+        port = parts.port
+    except ValueError as exc:
+        raise InvalidURLError(f"invalid URL {url!r}: {exc}") from None
+    if parts.scheme.lower() not in ("http", "https") or not host:
+        raise InvalidURLError(f"unsupported or malformed URL: {url!r} (only http/https)")
+    try:
+        host = host.encode("idna").decode("ascii")
+    except UnicodeError:
+        raise InvalidURLError(f"invalid host name in URL: {url!r}") from None
+    if ":" in host:
+        host = f"[{host}]"
+    netloc = host + (f":{port}" if port else "")
+    path = quote(parts.path or "/", safe="/%:@!$&'()*+,;=~")
+    query = quote(parts.query, safe="=&%+/?:@!$'()*,;~[]")
+    clean = urlunsplit((parts.scheme.lower(), netloc, path, query, ""))
+    user = unquote(parts.username) if parts.username is not None else None
+    password = unquote(parts.password) if parts.password is not None else None
+    return clean, user, password
+
+
+class RateLimiter:
+    """Thread-safe global bandwidth limiter (bytes/second, 0 = unlimited)."""
+
+    def __init__(self, rate: int = 0) -> None:
+        self.rate = max(0, int(rate))
+        self._lock = threading.Lock()
+        self._next = 0.0
+
+    def acquire(self, nbytes: int, cancel: Optional[threading.Event] = None) -> None:
+        if not self.rate:
+            return
+        with self._lock:
+            now = time.monotonic()
+            start = max(now, self._next)
+            self._next = start + nbytes / self.rate
+        delay = start - now
+        if delay > 0.001:
+            if cancel is not None:
+                cancel.wait(delay)
+            else:
+                time.sleep(delay)

pywget/wget.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+
+# File: pywget/wget.py
+# Author: Hadi Cahyadi <cumulus13@gmail.com>
+# Date: 2026-10-25
+# Description: Backward-compatible API: ``from pywget import wget; wget.download(url, dir)``.
+# License: MIT
+
+"""Backward-compatible API: ``from pywget import wget; wget.download(url, dir)``."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, List, Optional
+
+from .core import Downloader, Options
+from .progress import ProgressBar
+
+
+def download(
+    url: str,
+    path: Optional[str] = None,
+    filename: Optional[str] = None,
+    bar: bool = True,
+    **options: Any,
+) -> str:
+    """Download *url* into directory *path* and return the saved file path as ``str``."""
+    progress = ProgressBar() if bar else None
+    opts = Options(output_dir=path or ".", progress=progress, **options)
+    try:
+        return str(Downloader(opts).download(url, filename=filename))
+    finally:
+        if progress is not None:
+            progress.close()
+
+
+def usage(argv: Optional[List[str]] = None) -> int:
+    """Legacy console entry point (kept so old installs/scripts keep working)."""
+    from .cli import main
+
+    return main(argv if argv is not None else sys.argv[1:])