machyon 1.0.0__py3-none-any.whl

machyon/__init__.py

@@ -0,0 +1,35 @@
+"""Machyon - download any number of images, fast, and account for every one.
+
+    import machyon
+    report = machyon.download("urls.csv", "images/")
+    print(report)
+
+Docs: https://divyanshusingh96.github.io/machyon/
+"""
+from __future__ import annotations
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("machyon")
+except importlib.metadata.PackageNotFoundError:  # running from a source checkout
+    __version__ = "1.0.0.dev0"
+
+from .compat import ImageDownloader, download_images
+from .config import Config, DownloadConfig
+from .downloader import Downloader, adownload, download
+from .errors import FatalDiskError, MachyonError
+from .limiter import AdaptiveLimiter
+from .metrics import Report
+from .naming import ImageRenamer, NameTemplate, generate_hashed_name
+from .sources import read_rows
+from .utils import run, setup_logging
+
+__all__ = [
+    "download", "adownload", "Downloader", "DownloadConfig", "Report",
+    "NameTemplate", "read_rows", "run", "setup_logging",
+    "MachyonError", "FatalDiskError", "AdaptiveLimiter",
+    # class-based API
+    "ImageDownloader", "ImageRenamer", "generate_hashed_name", "download_images", "Config",
+    "__version__",
+]

machyon/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

machyon/cli.py

@@ -0,0 +1,182 @@
+"""Command line:  machyon urls.csv -o images/   (see `machyon --help`)."""
+from __future__ import annotations
+
+import argparse
+import csv
+import itertools
+import sys
+
+from . import __version__
+from .config import DownloadConfig
+from .downloader import Downloader
+from .naming import DEFAULT_TEMPLATE, as_namer
+from .sources import iter_pairs, read_rows
+from .utils import run, setup_logging
+
+COMMANDS = ("download", "retry", "names", "doctor")
+
+
+def _tuning(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("tuning (defaults are fine for almost everyone)")
+    g.add_argument("--concurrency", type=int, help="starting in-flight requests (adapts automatically)")
+    g.add_argument("--max-concurrency", type=int, help="ceiling for in-flight requests")
+    g.add_argument("--retries", type=int, help="retries per image after the first attempt")
+    g.add_argument("--timeout", type=float, help="connect / read-stall timeout in seconds")
+    g.add_argument("--no-adaptive", action="store_true", help="fixed concurrency")
+    g.add_argument("--no-hedge", action="store_true", help="don't race duplicate requests against stragglers")
+    g.add_argument("--header", action="append", default=[], metavar="'Name: value'", help="extra request header")
+    g.add_argument("--referer", help="Referer header to send")
+    g.add_argument("--verify-existing", action="store_true", help="check files already on disk are real images")
+    g.add_argument("--tls-trust", choices=("native", "certifi", "python"),
+                   help="CA source for HTTPS: native = OS store, like your browser (default)")
+    g.add_argument("--insecure", action="store_true",
+                   help="do NOT verify HTTPS certificates (only for hosts you trust; see `machyon doctor`)")
+    g.add_argument("--no-validate", action="store_true", help="keep non-image responses too")
+    g.add_argument("--no-progress", action="store_true", help="no progress bar")
+    g.add_argument("--metrics", metavar="DIR", help="append a run summary to DIR/metrics_json_info.json")
+    g.add_argument("--log", metavar="DIR", help="write DIR/machyon.log")
+    g.add_argument("--config", metavar="INI", help="load settings from an INI file ([SETTINGS] section)")
+    g.add_argument("--strict", action="store_true", help="exit with status 1 if anything failed")
+
+
+def _source_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("source", help="CSV, TSV, TXT, JSON, JSONL or Parquet file of image URLs")
+    p.add_argument("--url-col", help="column with the URLs (auto-detected if omitted)")
+    p.add_argument("--name-col", help="column with ready-made filenames")
+    p.add_argument("--names", default=DEFAULT_TEMPLATE,
+                   help="filename template, e.g. '{index}_{hash}{ext}'. Keys: index, hash, stem, ext, host, "
+                        "and any column name. Default: %(default)s")
+
+
+def _config(a) -> DownloadConfig:
+    cfg = DownloadConfig.from_ini(a.config) if a.config else DownloadConfig()
+    headers = dict(cfg.headers)
+    for h in a.header:
+        k, _, v = h.partition(":")
+        if k.strip():
+            headers[k.strip()] = v.strip()
+    changes = {k: v for k, v in {
+        "concurrency": a.concurrency, "max_concurrency": a.max_concurrency, "max_retries": a.retries,
+        "timeout": a.timeout, "referer": a.referer, "metrics_dir": a.metrics, "log_dir": a.log,
+        "tls_trust": a.tls_trust,
+    }.items() if v is not None}
+    if a.insecure:
+        changes["verify_ssl"] = False
+        print("⚠ --insecure: HTTPS certificates are NOT verified for this run.", file=sys.stderr)
+    if a.max_concurrency is not None and a.concurrency is None:
+        changes["concurrency"] = min(cfg.concurrency, a.max_concurrency)
+    flags = {"adaptive": not a.no_adaptive, "hedge": not a.no_hedge, "validate": not a.no_validate,
+             "progress": not a.no_progress}
+    changes.update({k: v for k, v in flags.items() if v is False})
+    if a.verify_existing:
+        changes["verify_existing"] = True
+    return cfg.replace(headers=headers, **changes)
+
+
+async def _download(a) -> int:
+    cfg = _config(a)
+    async with Downloader(a.output, cfg) as dl:
+        r = await dl.download(a.source, a.names, url_col=a.url_col, name_col=a.name_col, start=a.start, end=a.end)
+        print(f"\n{'✔' if r.ok else '⚠'} {r}")
+        _explain(r)
+        if dl.failures:
+            print(f"  Failures: {dl.save_dir / 'failed_downloads.jsonl'}  (retry with: machyon retry -o {a.output})")
+        return 1 if (a.strict and r.failed) else 0
+
+
+def _explain(r) -> None:
+    for reason, ex in (r.failure_examples or {}).items():
+        print(f"  {reason} ({r.failure_reasons.get(reason, 0)}x): {ex.get('error') or '-'}")
+        if ex.get("url"):
+            print(f"      e.g. {ex['url']}")
+        if ex.get("hint"):
+            print(f"      -> {ex['hint']}")
+
+
+async def _retry(a) -> int:
+    async with Downloader(a.output, _config(a)) as dl:
+        r = await dl.retry_failed(include_permanent=a.all)
+        left = len(dl.failures)
+        print(f"\n{'✔' if r.ok else '⚠'} {r}" if r else "\nNothing to retry.")
+        if r:
+            _explain(r)
+        if left:
+            print(f"  Still failing: {left} (see {dl.save_dir / 'failed_downloads.jsonl'})")
+        return 1 if (a.strict and left) else 0
+
+
+def _names(a) -> int:
+    pairs = iter_pairs(read_rows(a.source, a.url_col), as_namer(a.names), a.name_col)
+    if not a.output and a.limit is not None:      # --limit previews on screen; --output writes every row
+        pairs = itertools.islice(pairs, a.limit)
+    out = open(a.output, "w", newline="", encoding="utf-8") if a.output else sys.stdout
+    try:
+        w = csv.writer(out, lineterminator="\n")   # "\r\n" would become "\r\r\n" on a Windows console
+        w.writerow(["url", "filename"])
+        w.writerows(pairs)
+    finally:
+        if a.output:
+            out.close()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] not in COMMANDS and argv[0] not in ("-h", "--help", "--version"):
+        argv.insert(0, "download")  # `machyon urls.csv -o images/` and `machyon -o images/ urls.csv`
+    for stream in (sys.stdout, sys.stderr):  # ✔/⚠ must never crash a redirected Windows console
+        try:
+            stream.reconfigure(errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+    parser = argparse.ArgumentParser(prog="machyon",
+                                     description="Download any number of images, fast, without losing a single file.")
+    parser.add_argument("--version", action="version", version=f"machyon {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    p = sub.add_parser("download", help="download every URL in a file (default command)")
+    _source_args(p)
+    p.add_argument("-o", "--output", default="images", help="folder to save into (default: %(default)s)")
+    p.add_argument("--start", type=int, default=0, help="first row to download")
+    p.add_argument("--end", type=int, default=None, help="stop before this row")
+    _tuning(p)
+
+    p = sub.add_parser("retry", help="retry the failures recorded in a folder")
+    p.add_argument("-o", "--output", default="images", help="folder that was downloaded into")
+    p.add_argument("--all", action="store_true", help="also retry permanent failures (404, not an image, ...)")
+    _tuning(p)
+
+    p = sub.add_parser("names", help="preview the url -> filename mapping without downloading")
+    _source_args(p)
+    p.add_argument("--limit", type=int, default=20, help="rows to show (default: %(default)s)")
+    p.add_argument("--output", help="write the full mapping to this CSV instead")
+
+    p = sub.add_parser("doctor", help="diagnose why a URL fails: DNS, proxy, TLS trust, HTTP response")
+    p.add_argument("url", help="one image URL from your list")
+    p.add_argument("--referer", help="Referer header to send")
+    p.add_argument("--header", action="append", default=[], metavar="'Name: value'", help="extra request header")
+
+    a = parser.parse_args(argv)
+    if a.command == "doctor":
+        from .diagnostics import doctor
+
+        headers = {}
+        for h in a.header:
+            k, _, v = h.partition(":")
+            if k.strip():
+                headers[k.strip()] = v.strip()
+        return run(doctor(a.url, headers, a.referer))
+    if a.command == "names":
+        if a.output:
+            a.limit = None
+        return _names(a)
+    if a.command in ("download", "retry"):
+        setup_logging(a.log)
+        return run(_download(a) if a.command == "download" else _retry(a))
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

machyon/compat.py

@@ -0,0 +1,186 @@
+"""Class-based API: ``ImageDownloader`` with explicit lists, step-by-step methods and a JSON run log."""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+import os
+
+from .config import Config, DownloadConfig
+from .disk import write_atomic_sync
+from .downloader import Downloader
+from .jobs import Job
+from .metrics import MetricsEngine, Report
+from .utils import setup_logging, split_host, url_path_parts
+
+logger = logging.getLogger("machyon")
+
+
+class ImageDownloader(Downloader):
+    """Class-based downloader on top of :class:`machyon.Downloader`: explicit (links, names) lists,
+    INI configuration, and step-by-step methods (``metrics_json``, ``retry_failed_downloads``, ...)."""
+
+    def __init__(self, save_dir=None, cache_dir=None, concurrent_limit=None, max_connections=None,
+                 max_retries=None, backoff_factor=None, timeout=None, config_path=None,
+                 memory_cache_size=None, prefetch_dns=True, use_compression=True, metrics_dir=None,
+                 tuning_profile_path=None, *, log_dir=None, adaptive=None, use_warm_start=True, **options):
+        ini = Config(config_path)
+        S = "SETTINGS"
+
+        def pick(value, getter, key):
+            return value if value is not None else getter(S, key)
+
+        log_dir = log_dir if log_dir is not None else (ini.get(S, "LOG_DIR") or None)
+        cfg = DownloadConfig(
+            concurrency=pick(concurrent_limit, ini.get_int, "CONCURRENT_LIMIT"),
+            max_concurrency=pick(max_connections, ini.get_int, "MAX_CONNECTIONS"),
+            max_retries=pick(max_retries, ini.get_int, "MAX_RETRIES"),
+            backoff=pick(backoff_factor, ini.get_float, "BACKOFF_FACTOR"),
+            timeout=pick(timeout, ini.get_float, "TIMEOUT"),
+            max_request_time=pick(options.pop("max_request_time", None), ini.get_float, "MAX_REQUEST_TIME"),
+            adaptive=pick(adaptive, ini.get_bool, "ADAPTIVE"),
+            use_compression=use_compression,
+            metrics_dir=metrics_dir or ini.get(S, "METRICS_DIR") or "metrics",
+            profile_path=tuning_profile_path,
+            warm_start=use_warm_start,
+            log_dir=log_dir,
+            **options,
+        )
+        setup_logging(log_dir)  # the class-based API logs to the console
+        super().__init__(save_dir or ini.get(S, "SAVE_DIR"), cfg)
+        self._auto_metrics = False  # here metrics are written by metrics_json()
+        self.cache_dir = cache_dir            # accepted, unused (the filesystem is the cache)
+        self.memory_cache_size = memory_cache_size
+        self.prefetch_dns = prefetch_dns
+        self.save_image_dir = self.save_dir
+        self.metrics_dir = cfg.metrics_dir
+
+    # ------------------------------------------------------------------ attributes
+
+    @property
+    def concurrent_limit(self) -> int:
+        return self.limiter.limit
+
+    @property
+    def max_connections(self) -> int:
+        return self.config.max_concurrency
+
+    @property
+    def failed_downloads(self) -> list[str]:
+        """URLs currently failed."""
+        return self.ledger.urls()
+
+    @property
+    def _failed(self) -> dict:
+        return self.ledger.failed
+
+    def _mark_failed(self, name, url, reason):
+        if self.ledger.mark_failed(name, url, reason):
+            self.metrics.c["failed"] += 1
+
+    async def get_session(self):
+        return await self.sessions.get()
+
+    async def _set_referer(self, referer):
+        if referer and referer != self.config.referer:
+            self.config.referer = referer
+            await self.sessions.reset()
+
+    # ------------------------------------------------------------------ calls
+
+    async def download(self, image_links, image_names=None, start=0, end=None, referer=None,
+                       final_sweep=True, **kw) -> Report:
+        await self._set_referer(referer)
+        return await super().download(image_links, image_names, start=start, end=end,
+                                      retry_failures=final_sweep, **kw)
+
+    async def download_all_images(self, image_links, image_names, start=0, end=None, referer=None) -> Report:
+        await self._set_referer(referer)
+        return await self._pass(*self._pairs(image_links, image_names, None, None, start, end))
+
+    async def retry_failed_downloads(self, start=0, end=None, referer=None, include_permanent=False, only=None):
+        await self._set_referer(referer)
+        return await self.retry_failed(include_permanent=include_permanent, only=only, start=start, end=end)
+
+    async def metrics_json(self, image_links, image_names, start=0, end=None, referer=None) -> dict:
+        r = await self.download(image_links, image_names, start, end, referer=referer)
+        entry = MetricsEngine.entry(r)
+        if r.total > 0:
+            MetricsEngine.append_json(self.metrics_dir, entry)
+        return entry
+
+    async def log_session_metrics(self) -> dict:
+        zero = dict.fromkeys(self.metrics.c, 0)
+        r = self.metrics.report(zero, self.metrics.created_at, 0, len(self.ledger.counted),
+                                self.ledger.reasons(), self.limiter.limit)
+        entry = MetricsEngine.entry(r, scope="whole session (since instance creation)")
+        MetricsEngine.append_json(self.metrics_dir, entry)
+        return entry
+
+    async def auto_tune_concurrency(self, image_links, image_names=None, sample_size=None, candidates=None,
+                                    use_warm_start=True, host=None):
+        """Concurrency now tunes itself during the download; this only applies the warm-start
+        profile. Returns (concurrency, max_concurrency, consumed=0)."""
+        if use_warm_start and not self._warm_started:
+            urls = [str(u) for u in list(image_links)[:50]]
+            jobs = [Job(u, "", "", host or split_host(u) or "") for u in urls if host or split_host(u)]
+            if jobs:
+                await self._warm_start(jobs)
+        return self.limiter.limit, self.config.max_concurrency, 0
+
+    async def prefetch_urls(self, urls, port=443, batch_size=100) -> int:
+        """Resolve each distinct host once ahead of time (warms the OS DNS cache)."""
+        if not self.prefetch_dns:
+            return 0
+        hosts = {split_host(str(u)) for u in urls} - {None}
+        loop = asyncio.get_running_loop()
+
+        async def resolve(h):
+            try:
+                await asyncio.wait_for(loop.getaddrinfo(h, port), 5)
+            except Exception as e:
+                logger.debug(f"DNS prefetch failed for {h}: {e}")
+
+        await asyncio.gather(*(resolve(h) for h in hosts))
+        return len(hosts)
+
+    def get_metrics(self) -> dict:
+        m = dict(self.metrics.c)
+        m.update(concurrency=self.limiter.snapshot(), failure_reasons=dict(self.ledger.reasons()),
+                 peak_concurrency=self.metrics.peak_concurrency)
+        return m
+
+    def clear_cache(self, older_than=None) -> None:
+        """Forget recorded failures (files on disk are the cache)."""
+        self.ledger.clear()
+        self.metrics.c["failed"] = 0
+        self.ledger.write()
+
+    def save_metrics_to_file(self, filename="download_metrics.json") -> None:
+        write_atomic_sync([os.fspath(self.save_dir / filename)],
+                          json.dumps(self.get_metrics(), indent=2, default=str).encode(), False)
+
+    @classmethod
+    def from_config_file(cls, config_path):
+        return cls(config_path=config_path)
+
+    async def download_images_batch(self, image_urls, referer=None, **_ignored):
+        names = []
+        for u in image_urls:
+            _, ext = url_path_parts(u)
+            names.append(hashlib.blake2b(u.encode(), digest_size=16).hexdigest() +
+                         (ext if ext in (".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".tiff", ".avif") else ".jpg"))
+        await self.download_all_images(list(image_urls), names, referer=referer)
+        failed = self.ledger.names()
+        return [(n, n not in failed) for n in names]
+
+
+async def download_images(image_links, image_names=None, save_dir="downloads", **kwargs) -> Report:
+    """One-call helper for the class-based API (names default to the URL's file name)."""
+    links = [str(u) for u in image_links]
+    if image_names is None:
+        image_names = [("".join(url_path_parts(u)) or f"image_{i}") for i, u in enumerate(links)]
+    async with ImageDownloader(save_dir=save_dir, **kwargs) as d:
+        return await d.download(links, list(image_names))
+

machyon/config.py

@@ -0,0 +1,161 @@
+"""All tunables in one typed place, plus INI-file loading."""
+from __future__ import annotations
+
+import configparser
+import dataclasses
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .utils import DEFAULT_USER_AGENT
+
+logger = logging.getLogger("machyon.config")
+
+
+@dataclass
+class DownloadConfig:
+    """Every knob Machyon has. The defaults are tuned for "a big list of image URLs on an
+    ordinary laptop and home connection": you normally change none of them."""
+
+    # --- concurrency ---------------------------------------------------------------
+    concurrency: int = 32
+    """Starting number of in-flight requests. With ``adaptive=True`` this is only a starting point."""
+    max_concurrency: int = 256
+    """Hard ceiling for in-flight requests and the size of the connection pool."""
+    adaptive: bool = True
+    """Tune concurrency live: grow while throughput improves, back off on 429s and errors."""
+    hedge: bool = True
+    """Near the end of a batch, race a duplicate request against stragglers; first one wins."""
+    warm_start: bool = True
+    """Remember the best concurrency per host and start there next time."""
+    profile_path: str | None = None
+    """Where warm-start profiles live. Default: ``~/.machyon/profiles.json``."""
+
+    # --- retries & timeouts -------------------------------------------------------
+    max_retries: int = 5
+    """Retries per URL after the first attempt (timeouts, resets, 408/425/429/5xx)."""
+    backoff: float = 0.5
+    """Base seconds for exponential backoff with jitter."""
+    timeout: float = 15.0
+    """Connect timeout and maximum silence between received bytes, in seconds."""
+    max_request_time: float = 120.0
+    """Hard cap for one attempt; extended automatically in proportion to large bodies."""
+    max_retry_after: float = 120.0
+    """Upper bound on how long a server's ``Retry-After`` may pause a host."""
+
+    # --- HTTP -------------------------------------------------------------------
+    headers: dict[str, str] = field(default_factory=dict)
+    """Extra request headers (auth tokens, cookies, ...)."""
+    referer: str | None = None
+    user_agent: str = DEFAULT_USER_AGENT
+    verify_ssl: bool = True
+    """Verify TLS certificates. Turn off only for hosts you trust (``--insecure``)."""
+    tls_trust: str = "native"
+    """Where trusted CAs come from: "native" (OS store via truststore, like your browser),
+    "certifi" (Mozilla bundle, like requests) or "python" (Python's defaults)."""
+    use_compression: bool = True
+    """``False`` sends ``Accept-Encoding: identity``."""
+
+    # --- files ------------------------------------------------------------------
+    validate: bool = True
+    """Reject bodies that aren't images (HTML "soft 404" pages, JSON errors, ...)."""
+    verify_existing: bool = False
+    """Before skipping a file that already exists, check it really is an image."""
+    fsync: bool = False
+    """Flush every file to physical disk before renaming it into place (slower, power-loss safe)."""
+    stream_threshold: int = 4 * 1024 * 1024
+    """Bodies larger than this (or of unknown size) stream to disk and can resume with Range."""
+    write_threads: int | None = None
+    """Threads for file I/O. Default: min(32, 4 x CPUs)."""
+    shard_size: int = 200_000
+    """Rows planned at a time; keeps memory flat for inputs of any size."""
+
+    # --- reporting --------------------------------------------------------------
+    progress: bool = True
+    log_dir: str | None = None
+    """Write a rotating ``machyon.log`` here. ``None`` = no log file."""
+    metrics_dir: str | None = None
+    """Append a JSON entry per run to ``metrics_json_info.json`` here. ``None`` = off."""
+
+    def __post_init__(self) -> None:
+        self.max_concurrency = max(1, int(self.max_concurrency))
+        self.concurrency = max(1, min(int(self.concurrency), self.max_concurrency))
+        self.max_retries = max(0, int(self.max_retries))
+        self.backoff = max(0.0, float(self.backoff))
+        self.timeout = float(self.timeout)
+        self.max_request_time = float(self.max_request_time)
+        self.shard_size = max(1000, int(self.shard_size))
+        if self.tls_trust not in ("native", "certifi", "python"):
+            raise ValueError(f"tls_trust must be 'native', 'certifi' or 'python', not {self.tls_trust!r}")
+
+    def replace(self, **changes: Any) -> DownloadConfig:
+        """A copy with some fields changed (unknown names raise TypeError)."""
+        return dataclasses.replace(self, **changes)
+
+    @classmethod
+    def from_ini(cls, path: str | os.PathLike, section: str = "SETTINGS") -> DownloadConfig:
+        """Load from an INI file. Keys are field names, case-insensitive (``concurrency = 64``).
+        The aliases CONCURRENT_LIMIT, MAX_CONNECTIONS and BACKOFF_FACTOR are accepted too."""
+        cp = configparser.ConfigParser()
+        if not Path(path).exists():
+            raise FileNotFoundError(path)
+        cp.read(path, encoding="utf-8")
+        if not cp.has_section(section):
+            return cls()
+        aliases = {"concurrent_limit": "concurrency", "max_connections": "max_concurrency",
+                   "backoff_factor": "backoff"}
+        types = {f.name: f.type for f in dataclasses.fields(cls)}
+        values: dict[str, Any] = {}
+        for key, raw in cp.items(section):
+            name = aliases.get(key.lower(), key.lower())
+            if name not in types:
+                continue
+            t = str(types[name])
+            if "bool" in t:
+                values[name] = cp.getboolean(section, key)
+            elif t.startswith("int"):
+                values[name] = int(raw)
+            elif t.startswith("float"):
+                values[name] = float(raw)
+            elif "dict" in t:
+                continue
+            else:
+                values[name] = raw or None
+        return cls(**values)
+
+
+class Config:
+    """Plain INI accessor used by ``ImageDownloader(config_path=...)`` (``Config(path).get("SETTINGS", "SAVE_DIR")``)."""
+
+    DEFAULTS = {"CONCURRENT_LIMIT": "32", "MAX_CONNECTIONS": "256", "MAX_RETRIES": "5",
+                "BACKOFF_FACTOR": "0.5", "TIMEOUT": "15", "MAX_REQUEST_TIME": "120", "ADAPTIVE": "true",
+                "LOG_DIR": "", "SAVE_DIR": "images", "CACHE_DIR": "image_cache", "METRICS_DIR": ""}
+
+    def __init__(self, config_path: str | os.PathLike | None = None) -> None:
+        self.config = configparser.ConfigParser()
+        self.config["SETTINGS"] = dict(self.DEFAULTS)
+        if config_path:
+            if Path(config_path).exists():
+                self.config.read(config_path, encoding="utf-8")
+            else:
+                logger.warning(f"Config file {config_path} not found. Using default values.")
+
+    def get(self, section, option, fallback=None):
+        return self.config.get(section, option, fallback=fallback)
+
+    def get_int(self, section, option, fallback=None):
+        return self.config.getint(section, option, fallback=fallback)
+
+    def get_float(self, section, option, fallback=None):
+        return self.config.getfloat(section, option, fallback=fallback)
+
+    def get_bool(self, section, option, fallback=None):
+        return self.config.getboolean(section, option, fallback=fallback)
+
+    def save(self, config_path):
+        config_path = Path(config_path)
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(config_path, "w", encoding="utf-8") as f:
+            self.config.write(f)