behance-dl 0.1.0__py3-none-any.whl

behance_dl/__init__.py

@@ -0,0 +1,18 @@
+"""Download the images of a public Behance project gallery.
+
+Behance inlines the whole project into the gallery page: every module plus every CDN
+variant of each image with its pixel width. The downloader reads that payload, picks one
+variant per image, and fetches the files concurrently. The payload itself is kept in
+project.json, embeds such as prototypes and videos go to embeds.json because they are not
+images, and manifest.json records which variant produced each saved file so a re-run only
+fetches what is missing.
+
+Files are meant for offline viewing of published work. Respect the creator's licence and
+Behance's terms before redistributing anything.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

behance_dl/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for python -m behance_dl."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

behance_dl/cli.py

@@ -0,0 +1,170 @@
+"""Command line interface for the Behance gallery downloader."""
+
+from __future__ import annotations
+
+import argparse
+import http.client
+import io
+import sys
+import urllib.error
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .client import BehanceClient
+from .errors import BehanceError
+from .models import GalleryPlan
+from .selection import plan_gallery
+from .storage import load_saved, save_gallery
+
+
+def print_plan_summary(plan: GalleryPlan) -> None:
+    """Report what a gallery will produce."""
+    project = plan.project
+    print(f"{project.name or project.id} (id {project.id})")
+    print(f"{len(plan.images)} images, {len(plan.embeds)} embeds, target {plan.destination}")
+    missing = plan.expected_images - len(plan.images)
+    if missing > 0:
+        print(f"note: {missing} images carry no usable CDN variant")
+    for embed in plan.embeds:
+        if not embed.source_url:
+            print(f"note: module {embed.position} is an embed without a link")
+
+
+def print_plan_assets(plan: GalleryPlan) -> None:
+    """List the planned images and embeds with their sources."""
+    for asset in plan.images:
+        print(f"  {asset.file_name} ({asset.width}px) <- {asset.url}")
+    for embed in plan.embeds:
+        print(f"  {embed.position:03d} embed <- {embed.source_url}")
+
+
+def parse_args(argv: Sequence[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="behance-dl",
+        description="Download the images of a public Behance project gallery.",
+    )
+    parser.add_argument(
+        "galleries",
+        nargs="+",
+        metavar="URL",
+        help="Behance gallery URL or bare project id",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=Path(),
+        help="folder that receives one subfolder per gallery (default: current folder)",
+    )
+    parser.add_argument(
+        "-W",
+        "--max-width",
+        type=positive_int,
+        default=None,
+        metavar="PX",
+        help="largest image at or below this width in pixels, else the smallest available "
+        "(default: the largest available)",
+    )
+    parser.add_argument(
+        "-j",
+        "--workers",
+        type=positive_int,
+        default=4,
+        help="parallel downloads (default: 4)",
+    )
+    parser.add_argument(
+        "--attempts",
+        type=positive_int,
+        default=3,
+        help="attempts per request before giving up (default: 3)",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=positive_float,
+        default=30.0,
+        help="per-request timeout in seconds (default: 30)",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="ignore the recorded downloads and fetch every image again",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="list what would be downloaded without writing files",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser.parse_args(argv)
+
+
+def positive_int(value: str) -> int:
+    try:
+        number = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(f"{value!r} is not a whole number") from error
+    if number < 1:
+        raise argparse.ArgumentTypeError(f"{value!r} must be at least 1")
+    return number
+
+
+def positive_float(value: str) -> float:
+    try:
+        number = float(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(f"{value!r} is not a number") from error
+    if number <= 0:
+        raise argparse.ArgumentTypeError(f"{value!r} must be greater than 0")
+    return number
+
+
+def relax_console_encoding() -> None:
+    """Keep non-Latin project names printable on consoles with a narrow encoding."""
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(errors="replace")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the downloads and return the process exit code."""
+    args = parse_args(argv)
+    relax_console_encoding()
+    client = BehanceClient(timeout=args.timeout, attempts=args.attempts)
+    exit_code = 0
+    try:
+        for gallery in args.galleries:
+            try:
+                plan = plan_gallery(client, gallery, args.max_width, args.output)
+                print_plan_summary(plan)
+                if args.dry_run:
+                    print_plan_assets(plan)
+                    continue
+                saved = {} if args.force else load_saved(plan.destination)
+                failed = save_gallery(client, plan, saved, workers=args.workers)
+                status = 1 if failed else 0
+            except BehanceError as error:
+                print(f"error: {error}", file=sys.stderr)
+                status = 1
+            except urllib.error.HTTPError as error:
+                print(
+                    f"error: {gallery}: Behance answered {error.code} {error.reason}",
+                    file=sys.stderr,
+                )
+                status = 1
+            except (OSError, http.client.HTTPException) as error:
+                print(f"error: {gallery}: {error}", file=sys.stderr)
+                status = 1
+            exit_code = max(exit_code, status)
+    except KeyboardInterrupt:
+        print("interrupted", file=sys.stderr)
+        return 130
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

behance_dl/client.py

@@ -0,0 +1,204 @@
+"""HTTP access to Behance, including its bot challenge and transient-failure retries."""
+
+from __future__ import annotations
+
+import http.client
+import http.cookiejar
+import re
+import shutil
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from pathlib import Path
+from typing import TypeVar
+
+from .errors import DownloadError, GalleryError
+
+CHALLENGE_COOKIE = "js_challenge_value"
+USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
+)
+RETRYABLE_STATUS = frozenset({408, 425, 429, 500, 502, 503, 504})
+TRANSFER_BLOCK_SIZE = 64 * 1024
+MAX_BACKOFF_SECONDS = 30.0
+
+_CHALLENGE_VALUE = re.compile(r"js_challenge_value=([0-9a-fA-F]{16,})")
+_MAGIC_SUFFIXES = (
+    (b"\x89PNG\r\n\x1a\n", ".png"),
+    (b"\xff\xd8\xff", ".jpg"),
+    (b"GIF87a", ".gif"),
+    (b"GIF89a", ".gif"),
+)
+
+T = TypeVar("T")
+
+
+class BehanceClient:
+    """HTTP session that satisfies Behance's cookie challenge and retries transient failures."""
+
+    def __init__(
+        self,
+        *,
+        timeout: float = 30.0,
+        attempts: int = 3,
+        user_agent: str = USER_AGENT,
+    ) -> None:
+        if attempts < 1:
+            raise ValueError("attempts must be at least 1")
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than 0")
+        self._timeout = timeout
+        self._attempts = attempts
+        self._user_agent = user_agent
+        self._jar = http.cookiejar.CookieJar()
+        self._opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(self._jar))
+
+    def get_text(self, url: str) -> str:
+        """Return the decoded body of a text resource."""
+        return self._retry(lambda: self._read_text(url))
+
+    def download(self, url: str, destination: Path) -> Path:
+        """Save a remote image and return where it landed, named after its real format."""
+        return self._retry(lambda: self._transfer(url, destination))
+
+    def _read_text(self, url: str) -> str:
+        with self._open(url) as response:
+            charset = response.headers.get_content_charset() or "utf-8"
+            return response.read().decode(charset, "replace")
+
+    def _transfer(self, url: str, destination: Path) -> Path:
+        partial = destination.with_name(destination.name + ".part")
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            return self._store_image(url, partial, destination)
+        except BaseException:
+            partial.unlink(missing_ok=True)
+            raise
+
+    def _store_image(self, url: str, partial: Path, destination: Path) -> Path:
+        expected_size, content_type = self._copy_body(url, partial)
+        if not content_type.startswith("image/"):
+            raise DownloadError(f"{url} answered {content_type} instead of an image")
+        suffix = detected_suffix(partial)
+        if suffix is None:
+            raise DownloadError(f"{url} did not return a recognised image format")
+        received_size = partial.stat().st_size
+        if expected_size and expected_size.isdecimal() and received_size != int(expected_size):
+            raise DownloadError(f"{url} stopped after {received_size} of {expected_size} bytes")
+        final_name = destination.with_suffix(suffix)
+        partial.replace(final_name)
+        return final_name
+
+    def _copy_body(self, url: str, partial: Path) -> tuple[str | None, str]:
+        """Stream a response body into the partial file and report its length and media type."""
+        with self._open(url) as response:
+            expected_size = response.headers.get("Content-Length")
+            content_type = response.headers.get_content_type()
+            with partial.open("wb") as handle:
+                shutil.copyfileobj(response, handle, TRANSFER_BLOCK_SIZE)
+            return expected_size, content_type
+
+    def _open(self, url: str) -> http.client.HTTPResponse:
+        host = urllib.parse.urlsplit(url).hostname or ""
+        try:
+            return self._opener.open(self._request(url), timeout=self._timeout)
+        except urllib.error.HTTPError as error:
+            if error.code != 403 or not self._solve_challenge(error, host):
+                raise
+        try:
+            return self._opener.open(self._request(url), timeout=self._timeout)
+        except urllib.error.HTTPError as error:
+            if error.code == 403 and self._solve_challenge(error, host):
+                raise GalleryError(f"{url} keeps answering Behance's bot challenge") from error
+            raise
+
+    def _request(self, url: str) -> urllib.request.Request:
+        return urllib.request.Request(url, headers=self._headers())
+
+    def _retry(self, action: Callable[[], T]) -> T:
+        for attempt in range(1, self._attempts):
+            try:
+                return action()
+            except urllib.error.HTTPError as error:
+                if error.code not in RETRYABLE_STATUS:
+                    raise
+                retry_after = error.headers.get("Retry-After")
+                error.close()
+                self._pause(attempt, retry_after)
+            except (
+                urllib.error.URLError,
+                http.client.HTTPException,
+                TimeoutError,
+                ConnectionError,
+                ssl.SSLError,
+                DownloadError,
+            ):
+                self._pause(attempt, None)
+        return action()
+
+    def _pause(self, attempt: int, retry_after: str | None) -> None:
+        requested = parse_retry_after(retry_after)
+        if requested is not None:
+            time.sleep(min(requested, MAX_BACKOFF_SECONDS))
+        else:
+            time.sleep(min(2**attempt, MAX_BACKOFF_SECONDS))
+
+    def _solve_challenge(self, error: urllib.error.HTTPError, host: str) -> bool:
+        with error:
+            body = error.read().decode("utf-8", "replace")
+        match = _CHALLENGE_VALUE.search(body)
+        if match is None:
+            return False
+        self._jar.set_cookie(challenge_cookie(match.group(1), host))
+        return True
+
+    def _headers(self) -> dict[str, str]:
+        return {"User-Agent": self._user_agent, "Accept-Language": "en-US,en;q=0.9"}
+
+
+def challenge_cookie(value: str, host: str) -> http.cookiejar.Cookie:
+    """Build the cookie Behance's challenge page asks the browser to set."""
+    return http.cookiejar.Cookie(
+        version=0,
+        name=CHALLENGE_COOKIE,
+        value=value,
+        port=None,
+        port_specified=False,
+        domain=host,
+        domain_specified=True,
+        domain_initial_dot=False,
+        path="/",
+        path_specified=True,
+        secure=True,
+        expires=None,
+        discard=True,
+        comment=None,
+        comment_url=None,
+        rest={},
+        rfc2109=False,
+    )
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    """Read a Retry-After delay in seconds, ignoring dates and negative values."""
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError):
+        return None
+    return seconds if seconds >= 0 else None
+
+
+def detected_suffix(path: Path) -> str | None:
+    """Return the extension matching the file's magic bytes, if it is an image we know."""
+    with path.open("rb") as handle:
+        head = handle.read(16)
+    if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        return ".webp"
+    for magic, suffix in _MAGIC_SUFFIXES:
+        if head.startswith(magic):
+            return suffix
+    return None

behance_dl/errors.py

@@ -0,0 +1,15 @@
+"""Errors the downloader raises on purpose."""
+
+from __future__ import annotations
+
+
+class BehanceError(RuntimeError):
+    """Base class for every failure the downloader reports to the caller."""
+
+
+class GalleryError(BehanceError):
+    """Raised when a Behance page cannot be read or resolved into downloadable content."""
+
+
+class DownloadError(BehanceError):
+    """Raised when a remote image cannot be saved as a complete, genuine file."""

behance_dl/gallery.py

@@ -0,0 +1,115 @@
+"""Reading a gallery page and the project data Behance inlines in it."""
+
+from __future__ import annotations
+
+import html
+import json
+import re
+import urllib.parse
+from collections.abc import Iterator
+from typing import Any
+
+from .client import BehanceClient
+from .errors import GalleryError
+from .models import EmbedAsset, GalleryProject
+
+BEHANCE_ORIGIN = "https://www.behance.net"
+
+_STORE_STATE = re.compile(
+    r'<script type="application/json" id="beconfig-store_state">(.*?)</script>',
+    re.DOTALL,
+)
+_GALLERY_PATH = re.compile(r"/gallery/(\d+)")
+_IFRAME_SOURCE = re.compile(r'<iframe[^>]+src="([^"]+)"', re.IGNORECASE)
+_EMBED_MODULE_TYPES = frozenset({"EmbedModule", "VideoModule"})
+
+
+def is_behance_host(host: str) -> bool:
+    """Report whether a host belongs to Behance or one of its subdomains."""
+    return host == "behance.net" or host.endswith(".behance.net")
+
+
+def is_behance_url(url: str) -> bool:
+    """Report whether a payload URL points at Behance over https."""
+    parts = urllib.parse.urlsplit(url)
+    return parts.scheme == "https" and is_behance_host(parts.hostname or "")
+
+
+def parse_gallery_id(gallery: str) -> int:
+    """Return the numeric project id of a Behance gallery URL or bare id."""
+    candidate = gallery.strip()
+    if candidate.isdecimal():
+        return int(candidate)
+    parts = urllib.parse.urlsplit(candidate)
+    host = parts.hostname or ""
+    if host and not is_behance_host(host):
+        raise GalleryError(f"{gallery!r} is not a Behance gallery URL")
+    match = _GALLERY_PATH.search(parts.path)
+    if match is None:
+        raise GalleryError(f"{gallery!r} is not a Behance gallery URL")
+    return int(match.group(1))
+
+
+def fetch_project(client: BehanceClient, gallery_id: int) -> GalleryProject:
+    """Load the project payload embedded in a gallery page."""
+    # Behance answers 404 for /gallery/{id} alone and ignores whatever slug follows it.
+    page = client.get_text(f"{BEHANCE_ORIGIN}/gallery/{gallery_id}/gallery")
+    match = _STORE_STATE.search(page)
+    project_state: Any = None
+    if match is not None:
+        try:
+            state = json.loads(match.group(1))
+        except (ValueError, RecursionError) as error:
+            raise GalleryError(f"gallery {gallery_id}: unreadable project data") from error
+        project_state = state.get("project") if isinstance(state, dict) else None
+    payload = project_state.get("project") if isinstance(project_state, dict) else None
+    if not isinstance(payload, dict) or not payload:
+        raise GalleryError(
+            f"gallery {gallery_id}: the page carries no public project data "
+            "(removed, private, or behind a login)"
+        )
+    modules = payload.get("modules") or payload.get("allModules") or []
+    if not isinstance(modules, list) or not all(isinstance(module, dict) for module in modules):
+        raise GalleryError(f"gallery {gallery_id}: unexpected project data")
+    return GalleryProject(
+        id=gallery_id,
+        name=str(payload.get("name") or ""),
+        slug=str(payload.get("slug") or ""),
+        modules=tuple(modules),
+        payload=payload,
+    )
+
+
+def image_sources(project: GalleryProject) -> Iterator[tuple[str, dict[str, Any]]]:
+    """Yield the file prefix and image payload of every image in the project."""
+    for position, module in enumerate(project.modules, start=1):
+        kind = module.get("__typename")
+        if kind == "ImageModule":
+            yield f"{position:03d}", module
+        elif kind == "MediaCollectionModule":
+            components = module.get("components") or []
+            for index, component in enumerate(components, start=1):
+                yield f"{position:03d}_{index:02d}", component
+
+
+def embed_assets(project: GalleryProject) -> list[EmbedAsset]:
+    """Collect the modules that point at external media instead of hosting an image."""
+    assets: list[EmbedAsset] = []
+    for position, module in enumerate(project.modules, start=1):
+        if module.get("__typename") not in _EMBED_MODULE_TYPES:
+            continue
+        markup = str(
+            module.get("fluidEmbed") or module.get("originalEmbed") or module.get("embed") or ""
+        )
+        match = _IFRAME_SOURCE.search(markup)
+        assets.append(
+            EmbedAsset(
+                position=position,
+                module_id=int(module.get("id") or 0),
+                caption=str(module.get("caption") or ""),
+                source_url=html.unescape(match.group(1)) if match else "",
+                width=int(module.get("originalWidth") or module.get("width") or 0),
+                height=int(module.get("originalHeight") or module.get("height") or 0),
+            )
+        )
+    return assets

behance_dl/models.py

@@ -0,0 +1,79 @@
+"""Values that describe a gallery, its assets, and what a run has already saved."""
+
+from __future__ import annotations
+
+import urllib.parse
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .naming import safe_name
+
+
+@dataclass(frozen=True)
+class GalleryProject:
+    """A Behance project reduced to what downloading it needs."""
+
+    id: int
+    name: str
+    slug: str
+    modules: tuple[dict[str, Any], ...]
+    payload: dict[str, Any]
+
+    @property
+    def folder_name(self) -> str:
+        slug = safe_name(self.slug, "")
+        return f"{self.id}_{slug}" if slug else str(self.id)
+
+
+@dataclass(frozen=True)
+class ImageAsset:
+    """One downloadable image and the CDN variant chosen for it."""
+
+    file_prefix: str
+    url: str
+    width: int
+
+    @property
+    def file_name(self) -> str:
+        cdn_name = Path(urllib.parse.urlsplit(self.url).path).name
+        return f"{self.file_prefix}_{safe_name(cdn_name, 'image')}"
+
+
+@dataclass(frozen=True)
+class EmbedAsset:
+    """A module that is saved as a link instead of a file: an embed, a video, or a prototype."""
+
+    position: int
+    module_id: int
+    caption: str
+    source_url: str
+    width: int
+    height: int
+
+
+@dataclass(frozen=True)
+class GalleryPlan:
+    """What one gallery will produce before anything is written."""
+
+    project: GalleryProject
+    images: tuple[ImageAsset, ...]
+    embeds: tuple[EmbedAsset, ...]
+    destination: Path
+    expected_images: int
+
+
+@dataclass(frozen=True)
+class SavedImage:
+    """An image recorded in a gallery folder, and the CDN URL it came from."""
+
+    url: str
+    path: str
+
+
+@dataclass(frozen=True)
+class StoredImage:
+    """Where an image ended up and whether this run wrote it."""
+
+    path: Path
+    written: bool

behance_dl/naming.py

@@ -0,0 +1,17 @@
+"""Turning remote and user-supplied text into safe file names."""
+
+from __future__ import annotations
+
+import re
+
+UNSAFE_CHARACTERS = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def safe_name(value: str, fallback: str) -> str:
+    """Reduce arbitrary text to one file name component that cannot escape a folder."""
+    return UNSAFE_CHARACTERS.sub("-", value).strip(".-") or fallback
+
+
+def is_plain_file_name(value: str) -> bool:
+    """Report whether text is a single safe file name rather than a path."""
+    return bool(value) and value not in {".", ".."} and UNSAFE_CHARACTERS.search(value) is None

behance_dl/selection.py

@@ -0,0 +1,114 @@
+"""Choosing which CDN variant of each image to download."""
+
+from __future__ import annotations
+
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+from .client import BehanceClient
+from .errors import GalleryError
+from .gallery import embed_assets, fetch_project, image_sources, is_behance_url, parse_gallery_id
+from .models import GalleryPlan, ImageAsset
+
+_SOURCE_BUCKET = "source"
+_STILL_BUCKET_SUFFIX = "_still"
+_OPTIMISED_BUCKET = "_opt_"
+
+
+def bucket(url: str) -> str:
+    """Return the CDN bucket a project image URL was built from."""
+    segments = urllib.parse.urlsplit(url).path.split("/")
+    if "project_modules" in segments:
+        index = segments.index("project_modules") + 1
+        if index < len(segments):
+            return segments[index]
+    return ""
+
+
+def bucket_rank(bucket_name: str) -> int:
+    """Rank equally wide variants, preferring the least processed copy."""
+    if bucket_name == _SOURCE_BUCKET:
+        return 3
+    if _OPTIMISED_BUCKET in bucket_name:
+        return 1
+    return 2
+
+
+def candidate_sizes(image_source: dict[str, Any]) -> list[tuple[int, int, str]]:
+    """Collect (width, bucket rank, URL) for the variants worth downloading.
+
+    Stills are dropped when an animated variant exists, because a still bucket holds only
+    the first frame of an animated image.
+    """
+    sizes = image_source.get("imageSizes") or {}
+    variants: list[tuple[int, str, str]] = []
+    for variant in sizes.get("allAvailable") or []:
+        url = str(variant.get("url") or "")
+        if not is_behance_url(url):
+            continue
+        if variant.get("type") == "WEBP" or "_webp" in url:
+            continue
+        variants.append((int(variant.get("width") or 0), bucket(url), url))
+    animated = [entry for entry in variants if not entry[1].endswith(_STILL_BUCKET_SUFFIX)]
+    chosen = animated or variants
+    if chosen:
+        return [(width, bucket_rank(name), url) for width, name, url in chosen]
+    preview = str((sizes.get("size_disp") or {}).get("url") or image_source.get("src") or "")
+    if not is_behance_url(preview):
+        return []
+    return [(int(image_source.get("width") or 0), 0, preview)]
+
+
+def select_image_url(image_source: dict[str, Any], max_width: int | None) -> tuple[int, str] | None:
+    """Pick the widest variant at or below max_width, else the smallest available.
+
+    Without max_width the widest variant wins.
+    """
+    ordered = sorted(candidate_sizes(image_source), reverse=True)
+    if not ordered:
+        return None
+    if max_width is None:
+        width, _rank, url = ordered[0]
+        return width, url
+    within_limit = [entry for entry in ordered if entry[0] <= max_width]
+    width, _rank, url = (
+        within_limit[0] if within_limit else min(ordered, key=lambda entry: (entry[0], -entry[1]))
+    )
+    return width, url
+
+
+def image_asset(
+    image_source: dict[str, Any], file_prefix: str, max_width: int | None
+) -> ImageAsset | None:
+    """Build the asset for one image, or return None when it offers no usable variant."""
+    selected = select_image_url(image_source, max_width)
+    if selected is None:
+        return None
+    width, url = selected
+    return ImageAsset(file_prefix=file_prefix, url=url, width=width)
+
+
+def plan_gallery(
+    client: BehanceClient, gallery: str, max_width: int | None, output_root: Path
+) -> GalleryPlan:
+    """Fetch one gallery and resolve every asset it will produce."""
+    gallery_id = parse_gallery_id(gallery)
+    project = fetch_project(client, gallery_id)
+    try:
+        sources = list(image_sources(project))
+        images: list[ImageAsset] = []
+        for file_prefix, image_source in sources:
+            asset = image_asset(image_source, file_prefix, max_width)
+            if asset is not None:
+                images.append(asset)
+        embeds = embed_assets(project)
+    except (TypeError, ValueError, OverflowError, AttributeError) as error:
+        raise GalleryError(f"gallery {gallery_id}: unexpected project data") from error
+    return GalleryPlan(
+        project=project,
+        images=tuple(images),
+        embeds=tuple(embeds),
+        destination=output_root / project.folder_name,
+        expected_images=len(sources),
+    )

behance_dl/storage.py

@@ -0,0 +1,184 @@
+"""Writing gallery files and recording which variant produced each saved image."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable, Sequence
+from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from .client import BehanceClient
+from .models import GalleryPlan, ImageAsset, SavedImage, StoredImage
+from .naming import is_plain_file_name
+
+MANIFEST_NAME = "manifest.json"
+
+
+def load_saved(destination: Path) -> dict[str, SavedImage]:
+    """Read the record of files already written to a gallery folder."""
+    manifest = destination / MANIFEST_NAME
+    try:
+        entries = json.loads(manifest.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError) as error:
+        print(f"warning: ignoring unreadable {manifest}: {error}", file=sys.stderr)
+        return {}
+    if not isinstance(entries, dict):
+        print(f"warning: ignoring {manifest}: it does not hold an object", file=sys.stderr)
+        return {}
+    saved: dict[str, SavedImage] = {}
+    for name, entry in entries.items():
+        if not isinstance(entry, dict):
+            continue
+        url, path = entry.get("url"), entry.get("path")
+        if isinstance(url, str) and isinstance(path, str) and is_recorded_name(name, path):
+            saved[name] = SavedImage(url=url, path=path)
+    return saved
+
+
+def is_recorded_name(name: str, path: str) -> bool:
+    """Report whether a recorded file is a plain file name sharing the planned stem."""
+    return (
+        is_plain_file_name(name) and is_plain_file_name(path) and Path(path).stem == Path(name).stem
+    )
+
+
+def save_gallery(
+    client: BehanceClient,
+    plan: GalleryPlan,
+    saved: dict[str, SavedImage],
+    *,
+    workers: int,
+) -> int:
+    """Write one gallery's metadata and images, returning how many images failed."""
+    destination = plan.destination
+    destination.mkdir(parents=True, exist_ok=True)
+    write_json(destination / "project.json", plan.project.payload)
+    if plan.embeds:
+        write_json(destination / "embeds.json", [asdict(embed) for embed in plan.embeds])
+
+    record = dict(saved)
+
+    def remember(name: str, entry: SavedImage) -> None:
+        previous = record.get(name)
+        if previous is not None and previous.path != entry.path:
+            remove_superseded(destination / previous.path)
+        record[name] = entry
+        try:
+            write_json(
+                destination / MANIFEST_NAME,
+                {key: asdict(value) for key, value in record.items()},
+            )
+        except OSError as error:
+            print(f"warning: could not record {name} in {MANIFEST_NAME}: {error}", file=sys.stderr)
+
+    failed = download_images(
+        client,
+        plan.images,
+        destination,
+        saved,
+        workers=workers,
+        on_saved=remember,
+    )
+    if failed:
+        print(f"{failed} of {len(plan.images)} images failed", file=sys.stderr)
+    else:
+        print(f"done: {len(plan.images)} images in {destination}")
+    return failed
+
+
+def download_images(
+    client: BehanceClient,
+    assets: Sequence[ImageAsset],
+    destination: Path,
+    saved: dict[str, SavedImage],
+    *,
+    workers: int,
+    on_saved: Callable[[str, SavedImage], None],
+) -> int:
+    """Download the assets that are missing, reporting each result and returning failures."""
+    total = len(assets)
+    failed = 0
+    reported: set[str] = set()
+    pool = ThreadPoolExecutor(max_workers=workers)
+    pending: dict[Future[StoredImage], ImageAsset] = {}
+    try:
+        pending = {
+            pool.submit(save_image, client, asset, destination, saved.get(asset.file_name)): asset
+            for asset in assets
+        }
+        for completed, future in enumerate(as_completed(pending), start=1):
+            asset = pending[future]
+            name = asset.file_name
+            try:
+                stored = future.result()
+            # A single failed image must not abort the remaining ones.
+            except Exception as error:
+                failed += 1
+                print(f"[{completed}/{total}] failed {name}: {error}", file=sys.stderr)
+                continue
+            on_saved(name, SavedImage(url=asset.url, path=stored.path.name))
+            reported.add(name)
+            status = "saved " if stored.written else "exists"
+            print(f"[{completed}/{total}] {status} {stored.path.name}")
+    except BaseException:
+        pool.shutdown(wait=False, cancel_futures=True)
+        raise
+    finally:
+        pool.shutdown(wait=True)
+        report_finished(pending, reported, on_saved)
+    return failed
+
+
+def report_finished(
+    pending: dict[Future[StoredImage], ImageAsset],
+    reported: set[str],
+    on_saved: Callable[[str, SavedImage], None],
+) -> None:
+    """Record downloads that finished without being reported, such as after an interrupt."""
+    for future, asset in pending.items():
+        name = asset.file_name
+        if name in reported or future.cancelled() or not future.done():
+            continue
+        if future.exception() is not None:
+            continue
+        stored = future.result()
+        on_saved(name, SavedImage(url=asset.url, path=stored.path.name))
+        reported.add(name)
+
+
+def save_image(
+    client: BehanceClient,
+    asset: ImageAsset,
+    directory: Path,
+    recorded: SavedImage | None,
+) -> StoredImage:
+    """Reuse a recorded download or fetch the asset again."""
+    if recorded is not None and recorded.url == asset.url:
+        existing = directory / recorded.path
+        if existing.is_file() and existing.stat().st_size > 0:
+            return StoredImage(path=existing, written=False)
+    return StoredImage(path=client.download(asset.url, directory / asset.file_name), written=True)
+
+
+def remove_superseded(path: Path) -> None:
+    """Drop a file a new download replaced, warning instead of failing that download."""
+    try:
+        path.unlink(missing_ok=True)
+    except OSError as error:
+        print(f"warning: could not remove {path}: {error}", file=sys.stderr)
+
+
+def write_json(path: Path, data: Any) -> None:
+    """Write JSON so a reader never sees a half-written file."""
+    temporary = path.with_name(path.name + ".part")
+    try:
+        temporary.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        temporary.replace(path)
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        raise

behance_dl-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: behance-dl
+Version: 0.1.0
+Summary: Download the images of public Behance project galleries.
+Project-URL: Homepage, https://github.com/kevinkwee/behance-dl
+Project-URL: Repository, https://github.com/kevinkwee/behance-dl
+Project-URL: Issues, https://github.com/kevinkwee/behance-dl/issues
+Project-URL: Releases, https://github.com/kevinkwee/behance-dl/releases
+Author-email: Michael Elian Kevin <19345886+kevinkwee@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: behance,cli,downloader,gallery,portfolio
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Topic :: Multimedia :: Graphics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# behance-dl
+
+Download the images of a public [Behance](https://www.behance.net) project gallery.
+
+`behance-dl` reads the project data Behance inlines in the gallery page, picks the best CDN
+variant of every image, and downloads them in parallel with resume support. It keeps the
+gallery order, records which variant produced each file, and logs the content it cannot
+download as files (prototypes, video players) so nothing is silently lost.
+
+No API key, account, or browser automation is required.
+
+> Not affiliated with Behance or Adobe. Use it for offline viewing of published work, and
+> respect each creator's licence before redistributing anything.
+
+## Install
+
+```console
+pip install behance-dl
+```
+
+Requires Python 3.9 or newer. No third-party runtime dependencies.
+
+## Usage
+
+```console
+behance-dl "https://www.behance.net/gallery/123456789/Sample-Gallery"
+```
+
+Every gallery argument can be a full Behance URL, with or without query parameters, or a
+bare project id:
+
+```console
+behance-dl 123456789
+behance-dl "https://www.behance.net/gallery/123456789/Sample-Gallery?l=22"
+behance-dl 123456789 234567890 345678901 -o downloads
+```
+
+### Options
+
+| Option | Meaning |
+| --- | --- |
+| `-o`, `--output DIR` | Folder that receives one subfolder per gallery. Default: current folder. |
+| `-W`, `--max-width PX` | Largest image at or below this width, else the smallest available. Default: the largest available. |
+| `-j`, `--workers N` | Parallel downloads. Default: 4. |
+| `--attempts N` | Attempts per request before giving up. Default: 3. |
+| `--timeout SECONDS` | Per-request timeout. Default: 30. |
+| `--force` | Ignore the saved record and fetch every image again. |
+| `--dry-run` | List what would be downloaded without writing anything. |
+| `--version` | Print the version and exit. |
+
+### What a gallery folder contains
+
+```text
+123456789_Sample-Gallery/
+  001_0a1b2c3123456789.5f6d7e8f9a0b1.png
+  002_4d5e6f7123456789.5f6d7e9a1c2d3.png
+  003_8a9b0c1123456789.5f6d7eab2e3f4.jpg
+  embeds.json      # prototypes and video players that are links, not files
+  manifest.json    # which CDN variant produced each saved file
+  project.json     # the full project payload Behance served
+```
+
+Files are prefixed with their position in the gallery, so a plain alphabetical listing
+follows the project order. The extension is taken from the file's magic bytes, because
+Behance's CDN sometimes serves JPEG data under a `.png` name.
+
+`embeds.json` records modules that cannot be downloaded as images, such as Figma prototypes
+and Adobe video players, with their source URL, caption and dimensions.
+
+## Re-running, resume and width changes
+
+`manifest.json` records the URL each file came from. A re-run only fetches what is missing,
+and a run with a different `-W` re-fetches the affected images instead of leaving files at
+the old size. An interrupted run keeps whatever already landed, so `Ctrl+C` followed by the
+same command continues where it stopped.
+
+Delete `manifest.json` (or pass `--force`) to fetch everything again.
+
+## How it works
+
+1. `GET https://www.behance.net/gallery/{id}/gallery`. Behance answers 404 for an id with no
+   trailing slug and ignores the slug itself, so any slug works.
+2. Behance answers 403 with a cookie challenge
+   (`document.cookie = "js_challenge_value=..."; location.reload()`). The client sets the
+   cookie and retries once. This is not a CAPTCHA and needs no credentials.
+3. The project payload is read from `<script id="beconfig-store_state">`. It lists every
+   module and every CDN variant of each image with its pixel width.
+4. Variants are filtered and ranked: WebP copies are skipped so the saved file matches the
+   original format, `_still` buckets are dropped when an animated variant exists (a still
+   bucket holds only the first frame of a GIF), and equal widths prefer `source` over a
+   plain bucket over an `_opt_` copy.
+5. Images are downloaded in a thread pool, each to a `.part` file that is verified against
+   `Content-Length`, checked for an image content type and real magic bytes, then renamed
+   into place.
+
+`MediaCollectionModule` carousels are expanded into one file per component. Only URLs on
+`https://*.behance.net` are ever requested, so a tampered payload cannot point the tool at
+a local file or a third-party host.
+
+## Limitations
+
+- Only public projects. Private, removed, or login-gated projects report a clear error.
+- Images only. Prototypes and video modules are recorded as links in `embeds.json`.
+- Behance can change its page format at any time; the payload shape is checked and a
+  mismatch is reported as an error instead of producing an empty folder.
+
+## Development
+
+```console
+python -m venv .venv
+.venv\Scripts\activate        # Windows
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

behance_dl-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+behance_dl/__init__.py,sha256=oobH2KSoxxZrjied3ta9ZcWmhB9aCMXo5VnWVGcs0bA,771
+behance_dl/__main__.py,sha256=1-88gMWIaNhyN5zHQsOfgezG0kNgu_xc6GF7bfh-8j4,174
+behance_dl/cli.py,sha256=RD_BEcgIq7VJS6iuJWS8427xqohnhoPs8qWhScFw3BA,5679
+behance_dl/client.py,sha256=0m4KPoFNJL7kKN3aIOILgbnyAFSZDGJQpk457mvzYE4,7718
+behance_dl/errors.py,sha256=qZlMBPXVTp4mQewLnORYRh1rfiH-YT8G8K6GabNDWWQ,457
+behance_dl/gallery.py,sha256=MtsGFjzpWnDSxvX0-Xp8GBq8wgY14XV49COLWXKSw7w,4817
+behance_dl/models.py,sha256=_8NJ2GgoBp3Kdw6uCuNoDEIDaFm4fM-U5F6kbUJfo8Y,1851
+behance_dl/naming.py,sha256=xOCZuMllpvaEKw0LHK1jELd0wuwdRnAz0UXwsiVfS6E,610
+behance_dl/selection.py,sha256=y6tITBdxdeCpwQLONb2xHTKTUr1R9tKt7gN8QpyGOLQ,4336
+behance_dl/storage.py,sha256=cVGBVX4REyzBtDnoMqhEKd8Xf6KFLlfHepPnbRxiYJQ,6699
+behance_dl-0.1.0.dist-info/METADATA,sha256=5P1aq-D8xqD7x0Fj3pHaYf_zBHTthx-Ad3v3PLYiWX0,6249
+behance_dl-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+behance_dl-0.1.0.dist-info/entry_points.txt,sha256=QaV2VxcCV6VXqxDNZQmDWOHReS72kVFZnLR5MC2nWKQ,51
+behance_dl-0.1.0.dist-info/licenses/LICENSE,sha256=1uqWHBlCFIMf2cb2LszZXaK4lOmLbJjDRpqZGOFhnvQ,1097
+behance_dl-0.1.0.dist-info/RECORD,,

behance_dl-0.1.0.dist-info/WHEEL

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

behance_dl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+behance-dl = behance_dl.cli:main

behance_dl-0.1.0.dist-info/licenses/LICENSE

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