devart-dl 4.3.0__tar.gz → 4.3.2__tar.gz

{devart_dl-4.3.0/devart_dl.egg-info → devart_dl-4.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devart-dl
-Version: 4.3.0
+Version: 4.3.2
 Summary: 专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features
 Author: DeviantArt Downloader Team
 License-Expression: MIT
@@ -34,9 +34,11 @@ Dynamic: license-file
 
 # DeviantArt Downloader
 
-一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。
+**语言 / Language:** 中文 · [English](README.en.md)
 
-**语言 / Language:** 中文 · [English](README.en.md) · [完整文档](https://redtidev1918.github.io/deviantart-downloader/) · [更新日志](CHANGELOG.md)
+> **一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。**
+
+[完整文档](https://redtidev1918.github.io/deviantart-downloader/) · [更新日志](CHANGELOG.md)
 
 [![CI](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/devart-dl.svg)](https://pypi.org/project/devart-dl/)
@@ -93,9 +95,18 @@ devart-dl login browser   # 打开你的 Chrome 登录，自动保存 Cookie，
 - **代理与降级**：支持 `--proxy`；未登录 OAuth 时自动回退 Cookie。
 - **Resolve 模式**：`devart-dl resolve URL` 输出 `ResolvedDeviation`/`MediaAsset` 的 JSON 契约，不写文件。
 
-完整的安装、登录认证、下载模式、配置参数、命令速查、Python 调用与常见问题，请看**文档站点**：
+## 文档
+
+| 你想做什么 | 文档 |
+| --- | --- |
+| 下载安装包 | [下载页](https://redtidev1918.github.io/deviantart-downloader/download.md) |
+| 登录与认证 | [登录与认证](docs/LOGIN.md) |
+| 命令、配置与 Python 调用 | [文档站](https://redtidev1918.github.io/deviantart-downloader/) |
+
+## 致谢
 
-https://redtidev1918.github.io/deviantart-downloader/
+- [requests](https://github.com/psf/requests)：HTTP 客户端。
+- 登录与归档目录的实现与 [gallery-dl](https://github.com/mikf/gallery-dl) 交叉核对过。
 
 ## 许可证与免责声明
 

devart_dl-4.3.2/README.en.md

@@ -0,0 +1,87 @@
+# DeviantArt Downloader
+
+**Language / 语言:** [中文](README.md) · English
+
+> **A reliable, focused DeviantArt downloader and archival CLI.**
+
+📖 [Full documentation](https://redtidev1918.github.io/deviantart-downloader/) · [Changelog](CHANGELOG.md)
+
+[![CI](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![Python](https://img.shields.io/pypi/pyversions/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![Downloads](https://img.shields.io/pypi/dm/devart-dl.svg)](https://pypi.org/project/devart-dl/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+---
+
+## Core Features
+
+- **Official API first (OAuth)** — log in once to download originals; no cookie export, no anti-ban delays.
+- **URL-first** — `devart-dl URL` downloads artworks / galleries / favourites / tags / fav.me links directly.
+- **Reliable downloads** — HTTP Range resume, automatic retry, 429 backoff, HTML/empty-file validation, atomic finalize.
+- **Download archive** — `--archive` remembers what you've downloaded in SQLite, skipping it across sessions.
+- **Path templates** — `--directory` / `--filename` support `{id}` `{title}` `{author}` `{published}` `{ext}` and more, with safe sanitization.
+- **Metadata sidecars** — `--write-info-json` writes a `.json` next to each file.
+- **Proxy & fallback** — `--proxy` or proxy environment variables; falls back to cookies when not logged in via OAuth.
+
+---
+
+## Quick Start
+
+### Installation
+
+Requires Python 3.10 or newer.
+
+```bash
+pip install devart-dl
+```
+
+### Basic Usage (URL-first)
+
+```bash
+# Single artwork (also fav.me links and bare artwork ids)
+devart-dl https://www.deviantart.com/username/art/title-123456
+
+# Gallery / all works by an artist
+devart-dl https://www.deviantart.com/username/gallery
+
+# Favourites
+devart-dl https://www.deviantart.com/username/favourites
+
+# Tag
+devart-dl https://www.deviantart.com/tag/landscape
+
+# Resolve to JSON descriptors (download nothing)
+devart-dl resolve https://www.deviantart.com/username/art/title-123456
+```
+
+### Login (OAuth recommended)
+
+```bash
+devart-dl login oauth --client-id YOUR_PUBLIC_CLIENT_ID
+devart-dl whoami     # verify login
+devart-dl logout     # revoke the token
+```
+
+Register a **Public** OAuth app at [deviantart.com/developers](https://www.deviantart.com/developers/) and whitelist `http://127.0.0.1:8765/callback`. Login happens in the browser — no password or `client_secret` is ever given to the CLI.
+
+---
+
+## Documentation
+
+The full install, sign-in, download modes, configuration, command reference, Python API and FAQ live on the [docs site](https://redtidev1918.github.io/deviantart-downloader/).
+
+## Acknowledgements
+
+- [requests](https://github.com/psf/requests) — the HTTP client.
+- DevTools-free login and archive layout were cross-checked against [gallery-dl](https://github.com/mikf/gallery-dl).
+
+## License
+
+MIT License — see [LICENSE](LICENSE).
+
+**Important disclaimer:** this tool is for personal learning and research only.
+Respect DeviantArt's terms of service and copyright. Do not use it commercially
+or to overload their servers. The author is not responsible for any misuse.

{devart_dl-4.3.0 → devart_dl-4.3.2}/README.md

@@ -1,8 +1,10 @@
 # DeviantArt Downloader
 
-一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。
+**语言 / Language:** 中文 · [English](README.en.md)
 
-**语言 / Language:** 中文 · [English](README.en.md) · [完整文档](https://redtidev1918.github.io/deviantart-downloader/) · [更新日志](CHANGELOG.md)
+> **一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。**
+
+[完整文档](https://redtidev1918.github.io/deviantart-downloader/) · [更新日志](CHANGELOG.md)
 
 [![CI](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/devart-dl.svg)](https://pypi.org/project/devart-dl/)
@@ -59,9 +61,18 @@ devart-dl login browser   # 打开你的 Chrome 登录，自动保存 Cookie，
 - **代理与降级**：支持 `--proxy`；未登录 OAuth 时自动回退 Cookie。
 - **Resolve 模式**：`devart-dl resolve URL` 输出 `ResolvedDeviation`/`MediaAsset` 的 JSON 契约，不写文件。
 
-完整的安装、登录认证、下载模式、配置参数、命令速查、Python 调用与常见问题，请看**文档站点**：
+## 文档
+
+| 你想做什么 | 文档 |
+| --- | --- |
+| 下载安装包 | [下载页](https://redtidev1918.github.io/deviantart-downloader/download.md) |
+| 登录与认证 | [登录与认证](docs/LOGIN.md) |
+| 命令、配置与 Python 调用 | [文档站](https://redtidev1918.github.io/deviantart-downloader/) |
+
+## 致谢
 
-https://redtidev1918.github.io/deviantart-downloader/
+- [requests](https://github.com/psf/requests)：HTTP 客户端。
+- 登录与归档目录的实现与 [gallery-dl](https://github.com/mikf/gallery-dl) 交叉核对过。
 
 ## 许可证与免责声明
 

{devart_dl-4.3.0 → devart_dl-4.3.2}/da_downloader/cli.py

@@ -76,7 +76,7 @@ def _version() -> str:
     try:
         return version("devart-dl")
     except PackageNotFoundError:
-        return "4.0.1"
+        return "4.3.0"
 
 
 def _looks_like_target(value: str) -> bool:

{devart_dl-4.3.0 → devart_dl-4.3.2}/da_downloader/official_api.py

@@ -319,27 +319,67 @@ def deviation_uuid(init_data: dict) -> str:
 def additional_media_urls(init_data: dict) -> list:
     """Original-file URLs of a multimedia deviation's extra pages
     (``deviation.extended.additionalMedia``, each entry nests its Wix
-    descriptor under ``media``). Prefers the raw ``baseUri`` file + token.
+    descriptor under ``media``). Mirrors DeviantDrop's pick order: a playable
+    video ``types[].b`` (best quality) wins over ``baseUri`` — a video page's
+    baseUri is its poster — then the ``baseUri`` file itself, then a
+    fullview template. A page whose only representation is a small preview is
+    skipped rather than saved as a fake original.
+
+    Mature pages the server still returns with a ``blur_`` censored image are
+    skipped individually; one blocked page does not discard the others.
     """
-    extended = init_data.get("deviation", {}).get("extended") or {}
-    entries = extended.get("additionalMedia") or []
     urls: list = []
-    for entry in entries:
-        if not isinstance(entry, dict):
-            continue
-        media = entry.get("media")
+    for entry in (init_data.get("deviation", {}).get("extended") or {}).get(
+        "additionalMedia"
+    ) or []:
+        media = entry.get("media") if isinstance(entry, dict) else None
         if not isinstance(media, dict):
             continue
-        base = media.get("baseUri")
-        if not isinstance(base, str) or not base:
-            continue
-        raw_token = media.get("token")
-        token = raw_token[0] if isinstance(raw_token, list) and raw_token else raw_token
-        if token:
-            urls.append(f"{base}{'&' if '?' in base else '?'}token={token}")
-        else:
-            urls.append(base)
+        url = _descriptor_media_url(media)
+        if url and "blur_" not in url:
+            urls.append(url)
     return urls
 
 
+_FILE_EXT_RE = re.compile(
+    r"\.(?:png|jpe?g|gif|webp|avif|mp4|m4v|webm|mov|mkv)$", re.IGNORECASE
+)
+_VIDEO_QUALITY_RANK = {"1080p": 4, "720p": 3, "480p": 2, "360p": 1}
+
+
+def _descriptor_media_url(media: dict) -> Optional[str]:
+    types = media.get("types")
+    types = types if isinstance(types, list) else []
+    videos = [
+        item
+        for item in types
+        if isinstance(item, dict) and item.get("t") == "video" and item.get("b")
+    ]
+    if videos:
+        best = max(videos, key=lambda item: _VIDEO_QUALITY_RANK.get(item.get("q"), 0))
+        return _append_token(str(best["b"]), media.get("token"))
+    base = media.get("baseUri")
+    if isinstance(base, str) and base and _FILE_EXT_RE.search(base.split("?", 1)[0]):
+        return _append_token(base, media.get("token"))
+    fullview = next(
+        (item for item in types if isinstance(item, dict) and item.get("t") == "fullview"),
+        None,
+    )
+    if fullview:
+        if fullview.get("b"):
+            return _append_token(str(fullview["b"]), media.get("token"))
+        if fullview.get("c") and isinstance(base, str) and base:
+            pretty = media.get("prettyName") or "image"
+            url = base + str(fullview["c"]).replace("<prettyName>", pretty)
+            return _append_token(url, media.get("token"))
+    return None
+
+
+def _append_token(url: str, raw_token: Any) -> str:
+    token = raw_token[0] if isinstance(raw_token, list) and raw_token else raw_token
+    if not token:
+        return url
+    return f"{url}{'&' if '?' in url else '?'}token={token}"
+
+
 __all__ = ["OfficialApiClient", "OriginalDownload", "resolve_uuid", "deviation_init", "deviation_uuid", "additional_media_urls"]

{devart_dl-4.3.0 → devart_dl-4.3.2}/da_downloader/provider.py

@@ -13,6 +13,7 @@ from typing import Any, Callable, Iterator, Optional, Protocol
 
 from .api import ActionType, DeviantArtAPI
 from .errors import MediaUnavailableError, ParseError
+from .errors import AuthenticationError, NetworkError
 from .models import Deviation, DownloadItem
 from .official_api import (
     OfficialApiClient,
@@ -262,6 +263,13 @@ class OfficialProvider:
             ext = _ext_from_url(original.filename)
             return original.url, ext
         content = deviation.get("content") or {}
+        # `content.src` is a poster for video works; only videos[].src is playable.
+        videos = deviation.get("videos") or []
+        if isinstance(videos, list):
+            for video in videos:
+                src = video.get("src") if isinstance(video, dict) else None
+                if src:
+                    return str(src), _ext_from_url(str(src))
         if content.get("src"):
             return str(content["src"]), _ext_from_url(str(content["src"]))
         preview = deviation.get("preview") or {}
@@ -337,7 +345,7 @@ class CompositeProvider:
         if self.official is not None:
             try:
                 yield from self.official.resolve(target)
-            except MediaUnavailableError:
+            except (MediaUnavailableError, NetworkError, AuthenticationError):
                 if self.web is not None:
                     yield from self.web.resolve(target)
                     return

{devart_dl-4.3.0 → devart_dl-4.3.2/devart_dl.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devart-dl
-Version: 4.3.0
+Version: 4.3.2
 Summary: 专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features
 Author: DeviantArt Downloader Team
 License-Expression: MIT
@@ -34,9 +34,11 @@ Dynamic: license-file
 
 # DeviantArt Downloader
 
-一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。
+**语言 / Language:** 中文 · [English](README.en.md)
 
-**语言 / Language:** 中文 · [English](README.en.md) · [完整文档](https://redtidev1918.github.io/deviantart-downloader/) · [更新日志](CHANGELOG.md)
+> **一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。**
+
+[完整文档](https://redtidev1918.github.io/deviantart-downloader/) · [更新日志](CHANGELOG.md)
 
 [![CI](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/devart-dl.svg)](https://pypi.org/project/devart-dl/)
@@ -93,9 +95,18 @@ devart-dl login browser   # 打开你的 Chrome 登录，自动保存 Cookie，
 - **代理与降级**：支持 `--proxy`；未登录 OAuth 时自动回退 Cookie。
 - **Resolve 模式**：`devart-dl resolve URL` 输出 `ResolvedDeviation`/`MediaAsset` 的 JSON 契约，不写文件。
 
-完整的安装、登录认证、下载模式、配置参数、命令速查、Python 调用与常见问题，请看**文档站点**：
+## 文档
+
+| 你想做什么 | 文档 |
+| --- | --- |
+| 下载安装包 | [下载页](https://redtidev1918.github.io/deviantart-downloader/download.md) |
+| 登录与认证 | [登录与认证](docs/LOGIN.md) |
+| 命令、配置与 Python 调用 | [文档站](https://redtidev1918.github.io/deviantart-downloader/) |
+
+## 致谢
 
-https://redtidev1918.github.io/deviantart-downloader/
+- [requests](https://github.com/psf/requests)：HTTP 客户端。
+- 登录与归档目录的实现与 [gallery-dl](https://github.com/mikf/gallery-dl) 交叉核对过。
 
 ## 许可证与免责声明
 

{devart_dl-4.3.0 → devart_dl-4.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devart-dl"
-version = "4.3.0"
+version = "4.3.2"
 description = "专业的 DeviantArt 作品批量下载工具 - Professional DeviantArt batch downloader with anti-ban features"
 readme = "README.md"
 requires-python = ">=3.10"

{devart_dl-4.3.0 → devart_dl-4.3.2}/tests/test_official_provider.py

@@ -104,6 +104,113 @@ def test_artwork_multimedia_yields_every_file(monkeypatch) -> None:
     assert items[2].extension == "png"
 
 
+def test_mature_blurred_extra_pages_are_skipped(monkeypatch) -> None:
+    init = {
+        "deviation": {
+            "extended": {
+                "deviationUuid": "uuid-1",
+                "additionalMedia": [
+                    {"media": {"baseUri": "https://media.test/blur_page2.jpg", "token": "t"}},
+                    {"media": {"baseUri": "https://media.test/page3.png", "token": "t"}},
+                ],
+            }
+        }
+    }
+    monkeypatch.setattr(provider_mod, "deviation_init", lambda identifier, username=None, **_: init)
+    client = FakeClient()
+    client.deviations["uuid-1"] = make_deviation()
+    provider = OfficialProvider(client, quality="f")
+
+    items = list(provider.resolve(TargetParser.parse("123456")))
+
+    assert [item.media_url for item in items] == [
+        "https://images.test/full.jpg",
+        "https://media.test/page3.png?token=t",
+    ]
+
+
+def test_extra_video_page_uses_playable_source_not_poster(monkeypatch) -> None:
+    init = {
+        "deviation": {
+            "extended": {
+                "deviationUuid": "uuid-1",
+                "additionalMedia": [
+                    {"media": {
+                        "baseUri": "https://media.test/page2.jpg",
+                        "types": [
+                            {"t": "video", "q": "480p", "b": "https://videos.test/p2-480.mp4"},
+                            {"t": "video", "q": "1080p", "b": "https://videos.test/p2-1080.mp4"},
+                        ],
+                        "token": "t",
+                    }},
+                ],
+            }
+        }
+    }
+    monkeypatch.setattr(provider_mod, "deviation_init", lambda identifier, username=None, **_: init)
+    client = FakeClient()
+    client.deviations["uuid-1"] = make_deviation()
+    provider = OfficialProvider(client, quality="f")
+
+    items = list(provider.resolve(TargetParser.parse("123456")))
+
+    assert items[1].media_url == "https://videos.test/p2-1080.mp4?token=t"
+    assert items[1].extension == "mp4"
+
+
+def test_extra_page_uses_fullview_template_when_baseuri_is_not_a_file(monkeypatch) -> None:
+    init = {
+        "deviation": {
+            "extended": {
+                "deviationUuid": "uuid-1",
+                "additionalMedia": [
+                    {"media": {
+                        "baseUri": "https://wixmp.test/hashed",
+                        "fullview": True,
+                        "types": [{"t": "fullview", "c": "/f/<prettyName>.jpg"}],
+                        "prettyName": "page2",
+                        "token": "t",
+                    }},
+                ],
+            }
+        }
+    }
+    monkeypatch.setattr(provider_mod, "deviation_init", lambda identifier, username=None, **_: init)
+    client = FakeClient()
+    client.deviations["uuid-1"] = make_deviation()
+    provider = OfficialProvider(client, quality="f")
+
+    items = list(provider.resolve(TargetParser.parse("123456")))
+
+    assert items[1].media_url == "https://wixmp.test/hashed/f/page2.jpg?token=t"
+
+
+def test_preview_only_extra_page_is_skipped_not_downgraded(monkeypatch) -> None:
+    init = {
+        "deviation": {
+            "extended": {
+                "deviationUuid": "uuid-1",
+                "additionalMedia": [
+                    {"media": {
+                        "baseUri": "https://wixmp.test/hashed",
+                        "types": [{"t": "preview", "c": "/f/<prettyName>.jpg"}],
+                        "prettyName": "page2",
+                        "token": "t",
+                    }},
+                ],
+            }
+        }
+    }
+    monkeypatch.setattr(provider_mod, "deviation_init", lambda identifier, username=None, **_: init)
+    client = FakeClient()
+    client.deviations["uuid-1"] = make_deviation()
+    provider = OfficialProvider(client, quality="f")
+
+    items = list(provider.resolve(TargetParser.parse("123456")))
+
+    assert [item.media_url for item in items] == ["https://images.test/full.jpg"]
+
+
 def test_artwork_best_uses_content(monkeypatch) -> None:
     monkeypatch.setattr(provider_mod, "deviation_init", lambda identifier, username=None, **_: {"deviation": {"extended": {"deviationUuid": "uuid-1", "additionalMedia": []}}})
     client = FakeClient()
@@ -116,6 +223,21 @@ def test_artwork_best_uses_content(monkeypatch) -> None:
     assert client.originals == {}  # never called the download endpoint
 
 
+def test_artwork_video_uses_playable_source_not_poster(monkeypatch) -> None:
+    monkeypatch.setattr(provider_mod, "deviation_init", lambda identifier, username=None, **_: {"deviation": {"extended": {"deviationUuid": "uuid-1", "additionalMedia": []}}})
+    client = FakeClient()
+    client.deviations["uuid-1"] = {
+        **make_deviation(content_src="https://images.test/poster.jpg"),
+        "videos": [{"src": "https://videos.test/full.mp4"}],
+    }
+    provider = OfficialProvider(client, quality="f")
+
+    items = list(provider.resolve(TargetParser.parse("123456")))
+
+    assert items[0].media_url == "https://videos.test/full.mp4"
+    assert items[0].extension == "mp4"
+
+
 def test_gallery_paginates(monkeypatch) -> None:
     client = FakeClient()
     client.pages[("gallery_all", "alice", 0)] = {

{devart_dl-4.3.0 → devart_dl-4.3.2}/tests/test_provider.py

@@ -6,6 +6,7 @@ import pytest
 
 from da_downloader.api import ActionType
 from da_downloader.errors import MediaUnavailableError
+from da_downloader.errors import NetworkError
 from da_downloader.models import Deviation, DownloadItem
 from da_downloader.provider import CompositeProvider, WebProvider
 from da_downloader.targets import TargetParser
@@ -193,6 +194,19 @@ def test_composite_gallery_falls_back_to_web_when_official_unavailable() -> None
     assert len(web.api.build_calls) == 1
 
 
+def test_composite_gallery_falls_back_to_web_when_official_network_fails() -> None:
+    web = make_provider(
+        pages=[([make_deviation()], False, 1, "")],
+        media_urls={"123": "https://images.test/123.jpg"},
+    )
+    official = RecordingProvider(error=NetworkError("API down"))
+    router = CompositeProvider(official=official, web=web)
+
+    items = list(router.resolve(TargetParser.parse("https://www.deviantart.com/alice/gallery")))
+
+    assert items[0].artwork_id == "123"
+
+
 def test_composite_gallery_with_only_web_uses_web() -> None:
     web = make_provider(
         pages=[([make_deviation()], False, 1, "")],

devart_dl-4.3.0/README.en.md

@@ -1,289 +0,0 @@
-# DeviantArt Downloader
-
-A reliable, focused DeviantArt downloader and archival CLI.
-
-**Language / 语言:** [中文](README.md) · English · [Full documentation](https://redtidev1918.github.io/deviantart-downloader/) · [Changelog](CHANGELOG.md)
-
-[![CI](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/redtidev1918/deviantart-downloader/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/devart-dl.svg)](https://pypi.org/project/devart-dl/)
-[![Python](https://img.shields.io/pypi/pyversions/devart-dl.svg)](https://pypi.org/project/devart-dl/)
-[![Downloads](https://img.shields.io/pypi/dm/devart-dl.svg)](https://pypi.org/project/devart-dl/)
-[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-
-See [CHANGELOG.md](CHANGELOG.md) for release notes.
-
----
-
-## Core Features
-
-- **Official API first (OAuth)** — log in once to download originals; no cookie export, no anti-ban delays.
-- **URL-first** — `devart-dl URL` downloads artworks / galleries / favourites / tags / fav.me links directly.
-- **Reliable downloads** — HTTP Range resume, automatic retry, 429 backoff, HTML/empty-file validation, atomic finalize.
-- **Download archive** — `--archive` remembers what you've downloaded in SQLite, skipping it across sessions.
-- **Path templates** — `--directory` / `--filename` support `{id}` `{title}` `{author}` `{published}` `{ext}` and more, with safe sanitization.
-- **Metadata sidecars** — `--write-info-json` writes a `.json` next to each file.
-- **Proxy & fallback** — `--proxy` or proxy environment variables; falls back to cookies when not logged in via OAuth.
-
----
-
-## Quick Start
-
-### Installation
-
-Requires Python 3.10 or newer.
-
-```bash
-pip install devart-dl
-```
-
-### Basic Usage (URL-first)
-
-```bash
-# Single artwork (also fav.me links and bare artwork ids)
-devart-dl https://www.deviantart.com/username/art/title-123456
-
-# Gallery / all works by an artist
-devart-dl https://www.deviantart.com/username/gallery
-
-# Favourites
-devart-dl https://www.deviantart.com/username/favourites
-
-# Tag
-devart-dl https://www.deviantart.com/tag/landscape
-
-# Resolve to JSON descriptors (download nothing)
-devart-dl resolve https://www.deviantart.com/username/art/title-123456
-```
-
-### Login (OAuth recommended)
-
-```bash
-devart-dl login oauth --client-id YOUR_PUBLIC_CLIENT_ID
-devart-dl whoami     # verify login
-devart-dl logout     # revoke the token
-```
-
-Register a **Public** OAuth app at [deviantart.com/developers](https://www.deviantart.com/developers/) and whitelist `http://127.0.0.1:8765/callback`. Login happens in the browser — no password or `client_secret` is ever given to the CLI.
-
----
-
-## Main Features
-
-### Resolve Mode
-
-`devart-dl resolve URL` emits a machine-consumable `ResolvedDeviation` + `MediaAsset[]` JSON contract without writing any file.
-
-### Download Modes
-
-URL-first is the simplest entry; explicit subcommands are also kept:
-
-```bash
-# URL-first
-devart-dl https://www.deviantart.com/username/art/title-123456
-devart-dl https://www.deviantart.com/username/gallery
-devart-dl https://www.deviantart.com/username/gallery/12345   # specific folder
-devart-dl https://www.deviantart.com/username/favourites
-devart-dl https://www.deviantart.com/tag/landscape
-
-# Explicit subcommands
-devart-dl url https://www.deviantart.com/username/art/title-123456
-devart-dl artist username
-devart-dl gallery username [gallery_id]
-devart-dl search all "digital art"
-devart-dl fav username folder_id
-```
-
-> Note: explicit subcommands keep the old usage for compatibility. The official API has no search endpoint, so `search` always uses the web/cookie path. OAuth and cookies are capabilities that compose — OAuth gives the official API and cookie gives search — instead of one global "login mode".
-
-### Authentication
-
-**Official API (OAuth) first**, cookies as the fallback.
-
-1. **OAuth login (recommended)**
-
-   ```bash
-   devart-dl login oauth --client-id YOUR_PUBLIC_CLIENT_ID
-   ```
-
-   - Register a **Public** OAuth app and whitelist `http://127.0.0.1:8765/callback` exactly.
-   - Login completes in the browser; tokens are stored at `~/.deviantart_dl/oauth.json` (0600) and auto-refresh.
-   - Download commands then use the official API automatically; originals come from the official download endpoint.
-
-2. **Cookie login — one-click browser (recommended for cookies)**
-
-   ```bash
-   devart-dl login browser
-   ```
-
-   A Chrome window opens to the DeviantArt login page; just log in there. The
-   helper drives your **real** Chrome via the DevTools Protocol and captures the
-   web cookies (`auth` / `auth_secure` / `userinfo`) automatically — no F12 copy.
-   It needs Node.js (>= 22) and Chrome, and saves the session to
-   `~/.deviantart_dl/session.json` (0600). Logging in on the real domain is
-   required because the DeviantArt login page is behind an AWS WAF bot check that
-   blocks headless/proxied browsers; this is also the only way to capture the
-   HttpOnly `auth_secure` cookie.
-
-3. **Cookie login — manual paste (fallback)**
-
-   ```bash
-   devart-dl login interactive   # paste a cookie interactively
-   ```
-
-   Or create a `cookies.txt`, or set the `DEVIANTART_COOKIES` environment variable. The session is saved at `~/.deviantart_dl/session.json`.
-
-### Download Archive & Resume
-
-```bash
-# SQLite archive: skip already-downloaded items across sessions and directories
-devart-dl https://www.deviantart.com/username/gallery --archive ~/.devart-dl/archive.sqlite
-
-# Interrupted downloads resume from the .part file — no full re-download
-```
-
-### Filename / Directory Templates
-
-```bash
-devart-dl URL \
-  --directory "{author}/{published:%Y-%m}" \
-  --filename "{id}_{title}.{ext}"
-```
-
-Fields: `{id}` `{title}` `{author}` `{username}` `{published}` `{filename}` `{ext}` `{index}`. Paths are sanitized (illegal characters, Windows reserved names, `..` traversal, overly long names) so results always stay inside the download root.
-
-### Metadata Sidecar
-
-```bash
-devart-dl URL --write-info-json
-# produces artwork.jpg plus artwork.json (title, author, URL, published, mature, media URL, …)
-```
-
----
-
-## Configuration Options
-
-### Common Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-d, --dest` | Download root directory | `./Downloads` |
-| `--directory` | Directory template (e.g. `{author}/{published:%Y}`) | `{author}` |
-| `--filename` | Filename template (e.g. `{id}_{title}.{ext}`) | `{id}_{title}.{ext}` |
-| `--quality` | `original` (login) / `best` (default) / `preview`; legacy `o/f/p` still accepted | `best` |
-| `--archive` | SQLite download archive path | none |
-| `--write-info-json` | Write a metadata sidecar | off |
-| `--dry-run` | Plan only: resolve and report what would be downloaded, write nothing | off |
-| `--overwrite` | Replace existing files | off (skip) |
-| `--cookies` | Cookie file path | auto-load session |
-| `--proxy` | Proxy URL | auto from environment |
-| `--timeout` | Request timeout (seconds) | `60` |
-| `--retries` | Max retries | `3` |
-| `--limit` | Items per page | `24` |
-
-### Output Options
-
-- `-v, --verbose`: show details (including skip reasons).
-- `-q, --quiet`: only the summary and errors.
-
----
-
-## Command Reference
-
-```bash
-# URL-first (recommended)
-devart-dl <URL>
-
-# Explicit subcommands
-devart-dl url <artwork_url>
-devart-dl artist <username>
-devart-dl gallery <username> [gallery_id]
-devart-dl search <username|all> <query>
-devart-dl fav <username> <folder_id>
-
-# Login / session
-devart-dl login oauth --client-id <ID>   # OAuth login (recommended)
-devart-dl login browser                 # one-click cookie via your Chrome
-devart-dl login interactive             # cookie login (manual paste)
-devart-dl whoami                        # show login status
-devart-dl logout                        # revoke token and clear local session
-
-# Other
-devart-dl version
-```
-
----
-
-## Advanced Usage
-
-### Proxy
-
-```bash
-# Command-line
-devart-dl URL --proxy http://127.0.0.1:7890
-
-# Environment variables (HTTP/HTTPS)
-export HTTP_PROXY=http://127.0.0.1:7890
-export HTTPS_PROXY=http://127.0.0.1:7890
-export ALL_PROXY=http://127.0.0.1:7890
-```
-
-### Python API
-
-```python
-from pathlib import Path
-from da_downloader import Downloader
-from da_downloader.download import build_downloader
-
-downloader = build_downloader(
-    destination=Path('downloads'),
-    archive=Path('archive.sqlite'),   # optional: skip already-downloaded
-    quality='best',                   # original / best / preview
-    write_info_json=True,             # write a metadata .json next to each file
-)
-
-results = downloader.download('https://www.deviantart.com/username/gallery')
-for r in results:
-    print(r.status, r.path)
-```
-
-When logged in via `devart-dl login oauth`, the official API is used automatically; otherwise it falls back to cookies.
-
----
-
-## FAQ
-
-**Q: Downloads are incomplete / skip some artworks?**
-**A:** Upgrade to **v3.4.0+**. Older versions fetched only the Featured folder;
-v3.3.1 walks all gallery folders, and v3.4.0 reports parsing/network failures
-loudly and resumes interrupted downloads via Range.
-
-**Q: ModuleNotFoundError after pip install?**
-**A:** Upgrade to **v3.4.0+** (`pip install -U devart-dl`); the console entry point is fixed.
-
-**Q: Got a 403 Forbidden error?**
-**A:** Usually not logged in or an expired cookie. Prefer `devart-dl login oauth`
-(official API); otherwise `devart-dl login browser` for a one-click cookie
-(`devart-dl login interactive` to paste one manually).
-
-**Q: Got a 429 Too Many Requests?**
-**A:** The official API (OAuth) usually avoids this; the cookie path retries with
-backoff. If it persists, pause for a while.
-
-**Q: Downloads are slow?**
-**A:** Use a proxy (`--proxy`), or lower the quality (`--quality preview`).
-
-**Q: How do I export a cookie?**
-**A:** Easiest is `devart-dl login browser` — it opens your own Chrome and
-captures the cookie automatically. Otherwise open Chrome/Edge DevTools (F12) →
-Application → Cookies, copy the `auth` and `auth_secure` fields, and paste them
-via `devart-dl login interactive`.
-
----
-
-## License
-
-MIT License — see [LICENSE](LICENSE).
-
-**Important disclaimer:** this tool is for personal learning and research only.
-Respect DeviantArt's terms of service and copyright. Do not use it commercially
-or to overload their servers. The author is not responsible for any misuse.