dycw-restic 0.2.22__py3-none-any.whl

dycw_restic-0.2.22.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.3
+Name: dycw-restic
+Version: 0.2.22
+Summary: Library to operate `restic`
+Author: Derek Wan
+Author-email: Derek Wan <d.wan@icloud.com>
+Requires-Dist: click>=8.3.1,<9
+Requires-Dist: dycw-utilities>=0.172.5,<1
+Requires-Dist: typed-settings[attrs,click]>=25.3.0,<26
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# `restic`
+
+Library to operate `restic`

dycw_restic-0.2.22.dist-info/RECORD

@@ -0,0 +1,15 @@
+restic/__init__.py,sha256=yhMJ-0LPYMf--j6qVDnbLfF1nV_AHSSJISPpIr9pFm8,59
+restic/cli.py,sha256=YVrgIwCkAMI9BmbjAC1M4aFZ2WjNk1f8YqfauwfLwG8,5432
+restic/click.py,sha256=cuqKKXlErXsb_vNkWHKyo_xnrTgo8qhscaEWqsT7Nl8,1525
+restic/constants.py,sha256=uu2dXIlx3vyMNgJUs1lrCMOYBPGGUviVJ5qvxqOx6Tw,911
+restic/lib.py,sha256=-d3dPReAJikNdLWHNC7QjJiAHYG6vj435KTCc0A09Xc,10454
+restic/logging.py,sha256=tzoiz1F2T-AavxahNduXxfnFvhmcBh6JHskDgUhcNVU,119
+restic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+restic/repo.py,sha256=uDOEzkSWz0vJR-SFFraYtVSD-bl7C6FWlPtfAdDy9KI,3544
+restic/settings.py,sha256=a2WPOeB_VwvbZJ-uxuJpJB1RE5TH1S-BD0IeIIf1v_8,12988
+restic/types.py,sha256=lCchCT7Y7yo0PMBGHgYjpuTDf9z2orPjKiPuje1vfmE,229
+restic/utilities.py,sha256=uXq5Jl_FFjVNCLYG9si4KNiiCJWG2nk0Yr49c4TgA1Q,3215
+dycw_restic-0.2.22.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
+dycw_restic-0.2.22.dist-info/entry_points.txt,sha256=6byn-7KAIlNAdTjaNQ3DjylzzazsZB8SLFvvrqv641o,48
+dycw_restic-0.2.22.dist-info/METADATA,sha256=PHpIDO2qcLXFznHv-ujYWYzW6byripPVLxTqOVyjzfA,387
+dycw_restic-0.2.22.dist-info/RECORD,,

dycw_restic-0.2.22.dist-info/WHEEL

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

dycw_restic-0.2.22.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+py-restic = restic.cli:_main
+

restic/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__version__ = "0.2.22"

restic/cli.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+from click import argument, group
+from typed_settings import click_options
+from utilities.click import CONTEXT_SETTINGS
+from utilities.logging import basic_config
+from utilities.os import is_pytest
+
+import restic.click
+import restic.repo
+from restic.lib import backup, copy, forget, init, restore, snapshots
+from restic.logging import LOGGER
+from restic.settings import (
+    LOADERS,
+    BackupSettings,
+    CopySettings,
+    ForgetSettings,
+    InitSettings,
+    RestoreSettings,
+    SnapshotsSettings,
+)
+
+if TYPE_CHECKING:
+    from utilities.types import PathLike
+
+
+@group(**CONTEXT_SETTINGS)
+def _main() -> None: ...
+
+
+@_main.command(name="init", **CONTEXT_SETTINGS)
+@argument("repo", type=restic.click.Repo())
+@click_options(InitSettings, LOADERS, show_envvars_in_help=True)
+def init_sub_cmd(settings: InitSettings, /, *, repo: restic.repo.Repo) -> None:
+    if is_pytest():
+        return
+    init(repo, password=settings.password)
+
+
+@_main.command(name="backup", **CONTEXT_SETTINGS)
+@argument("path", type=click.Path(path_type=Path))
+@argument("repo", type=restic.click.Repo())
+@click_options(BackupSettings, LOADERS, show_envvars_in_help=True)
+def backup_sub_cmd(
+    settings: BackupSettings, /, *, path: PathLike, repo: restic.repo.Repo
+) -> None:
+    if is_pytest():
+        return
+    backup(
+        path,
+        repo,
+        chmod=settings.chmod,
+        chown=settings.chown,
+        password=settings.password,
+        dry_run=settings.dry_run,
+        exclude=settings.exclude,
+        exclude_i=settings.exclude_i,
+        read_concurrency=settings.read_concurrency,
+        tag_backup=settings.tag_backup,
+        run_forget=settings.run_forget,
+        keep_last=settings.keep_last,
+        keep_hourly=settings.keep_hourly,
+        keep_daily=settings.keep_daily,
+        keep_weekly=settings.keep_weekly,
+        keep_monthly=settings.keep_monthly,
+        keep_yearly=settings.keep_yearly,
+        keep_within=settings.keep_within,
+        keep_within_hourly=settings.keep_within_hourly,
+        keep_within_daily=settings.keep_within_daily,
+        keep_within_weekly=settings.keep_within_weekly,
+        keep_within_monthly=settings.keep_within_monthly,
+        keep_within_yearly=settings.keep_within_yearly,
+        prune=settings.prune,
+        repack_cacheable_only=settings.repack_cacheable_only,
+        repack_small=settings.repack_small,
+        repack_uncompressed=settings.repack_uncompressed,
+        tag_forget=settings.tag_forget,
+        sleep=settings.sleep,
+    )
+
+
+@_main.command(name="copy", **CONTEXT_SETTINGS)
+@argument("src", type=restic.click.Repo())
+@argument("dest", type=restic.click.Repo())
+@click_options(CopySettings, LOADERS, show_envvars_in_help=True)
+def copy_sub_cmd(
+    settings: CopySettings, /, *, src: restic.repo.Repo, dest: restic.repo.Repo
+) -> None:
+    if is_pytest():
+        return
+    copy(
+        src,
+        dest,
+        src_password=settings.src_password,
+        dest_password=settings.dest_password,
+        tag=settings.tag,
+    )
+
+
+@_main.command(name="forget", **CONTEXT_SETTINGS)
+@argument("repo", type=restic.click.Repo())
+@click_options(ForgetSettings, LOADERS, show_envvars_in_help=True)
+def forget_sub_cmd(settings: ForgetSettings, /, *, repo: restic.repo.Repo) -> None:
+    if is_pytest():
+        return
+    forget(
+        repo,
+        password=settings.password,
+        dry_run=settings.dry_run,
+        keep_last=settings.keep_last,
+        keep_hourly=settings.keep_hourly,
+        keep_daily=settings.keep_daily,
+        keep_weekly=settings.keep_weekly,
+        keep_monthly=settings.keep_monthly,
+        keep_yearly=settings.keep_yearly,
+        keep_within=settings.keep_within,
+        keep_within_hourly=settings.keep_within_hourly,
+        keep_within_daily=settings.keep_within_daily,
+        keep_within_weekly=settings.keep_within_weekly,
+        keep_within_monthly=settings.keep_within_monthly,
+        keep_within_yearly=settings.keep_within_yearly,
+        prune=settings.prune,
+        repack_cacheable_only=settings.repack_cacheable_only,
+        repack_small=settings.repack_small,
+        repack_uncompressed=settings.repack_uncompressed,
+        tag=settings.tag,
+    )
+
+
+@_main.command(name="restore", **CONTEXT_SETTINGS)
+@argument("repo", type=restic.click.Repo())
+@argument("target", type=click.Path(path_type=Path))
+@click_options(RestoreSettings, LOADERS, show_envvars_in_help=True)
+def restore_sub_cmd(
+    settings: RestoreSettings, /, *, repo: restic.repo.Repo, target: PathLike
+) -> None:
+    if is_pytest():
+        return
+    restore(
+        repo,
+        target,
+        password=settings.password,
+        delete=settings.delete,
+        dry_run=settings.dry_run,
+        exclude=settings.exclude,
+        exclude_i=settings.exclude_i,
+        include=settings.include,
+        include_i=settings.include_i,
+        tag=settings.tag,
+        snapshot=settings.snapshot,
+    )
+
+
+@_main.command(name="snapshots", **CONTEXT_SETTINGS)
+@argument("repo", type=restic.click.Repo())
+@click_options(SnapshotsSettings, LOADERS, show_envvars_in_help=True)
+def snapshots_sub_cmd(
+    settings: SnapshotsSettings, /, *, repo: restic.repo.Repo
+) -> None:
+    if is_pytest():
+        return
+    snapshots(repo, password=settings.password)
+
+
+if __name__ == "__main__":
+    basic_config(obj=LOGGER)
+    _main()

restic/click.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from contextlib import suppress
+from pathlib import Path
+from re import search
+from typing import TYPE_CHECKING, assert_never, override
+
+from click import Context, Parameter, ParamType
+from utilities.re import ExtractGroupError, ExtractGroupsError
+
+from restic.repo import SFTP, Backblaze, Local
+
+if TYPE_CHECKING:
+    import restic.repo
+
+
+class Repo(ParamType):
+    name = "repo"
+
+    @override
+    def __repr__(self) -> str:
+        return self.name.upper()
+
+    @override
+    def convert(
+        self,
+        value: restic.repo.Repo | str,
+        param: Parameter | None,
+        ctx: Context | None,
+    ) -> restic.repo.Repo:
+        match value:
+            case Backblaze() | Local() | SFTP():
+                return value
+            case str():
+                try:
+                    return Backblaze.parse(value)
+                except ValueError, ExtractGroupsError:
+                    if search("b2", value):
+                        message = f"For a Backblaze repository {value!r}, the environment varaibles 'BACKBLAZE_KEY_ID' and 'BACKBLAZE_APPLICATION_KEY' must be defined"
+                        return self.fail(message, param, ctx)
+                with suppress(ExtractGroupsError):
+                    return SFTP.parse(value)
+                try:
+                    return Local.parse(value)
+                except ExtractGroupError:
+                    return Local(Path(value))
+            case never:
+                assert_never(never)
+
+
+__all__ = ["Repo"]

restic/constants.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import NotRequired, TypedDict
+
+
+class KeepKwargs(TypedDict):
+    keep_last: NotRequired[int]
+    keep_hourly: NotRequired[int]
+    keep_daily: NotRequired[int]
+    keep_weekly: NotRequired[int]
+    keep_monthly: NotRequired[int]
+    keep_yearly: NotRequired[int]
+    keep_within: NotRequired[str]
+    keep_within_hourly: NotRequired[str]
+    keep_within_daily: NotRequired[str]
+    keep_within_weekly: NotRequired[str]
+    keep_within_monthly: NotRequired[str]
+    keep_within_yearly: NotRequired[str]
+
+
+DEFAULT_KEEP_KWARGS = KeepKwargs(
+    keep_last=100,
+    keep_hourly=24 * 7,
+    keep_daily=30,
+    keep_weekly=52,
+    keep_monthly=5 * 12,
+    keep_yearly=10,
+    keep_within_hourly="7d",
+    keep_within_daily="1m",
+    keep_within_weekly="1y",
+    keep_within_monthly="5y",
+    keep_within_yearly="10y",
+)
+
+
+__all__ = ["DEFAULT_KEEP_KWARGS", "KeepKwargs"]

restic/lib.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import time
+from re import MULTILINE, search
+from subprocess import CalledProcessError
+from typing import TYPE_CHECKING
+
+from utilities.subprocess import run
+from whenever import TimeDelta
+
+from restic.logging import LOGGER
+from restic.repo import yield_repo_env
+from restic.settings import SETTINGS
+from restic.utilities import (
+    expand_bool,
+    expand_dry_run,
+    expand_exclude,
+    expand_exclude_i,
+    expand_include,
+    expand_include_i,
+    expand_keep,
+    expand_keep_within,
+    expand_tag,
+    run_chmod,
+    yield_password,
+)
+
+if TYPE_CHECKING:
+    from utilities.types import PathLike
+
+    from restic.repo import Repo
+    from restic.types import PasswordLike
+
+
+def backup(
+    path: PathLike,
+    repo: Repo,
+    /,
+    *,
+    chmod: bool = SETTINGS.chmod,
+    chown: str | None = SETTINGS.chown,
+    password: PasswordLike = SETTINGS.password,
+    dry_run: bool = SETTINGS.dry_run,
+    exclude: list[str] | None = SETTINGS.exclude_backup,
+    exclude_i: list[str] | None = SETTINGS.exclude_i_backup,
+    read_concurrency: int = SETTINGS.read_concurrency,
+    tag_backup: list[str] | None = SETTINGS.tag_backup,
+    run_forget: bool = SETTINGS.run_forget,
+    keep_last: int | None = SETTINGS.keep_last,
+    keep_hourly: int | None = SETTINGS.keep_hourly,
+    keep_daily: int | None = SETTINGS.keep_daily,
+    keep_weekly: int | None = SETTINGS.keep_weekly,
+    keep_monthly: int | None = SETTINGS.keep_monthly,
+    keep_yearly: int | None = SETTINGS.keep_yearly,
+    keep_within: str | None = SETTINGS.keep_within,
+    keep_within_hourly: str | None = SETTINGS.keep_within_hourly,
+    keep_within_daily: str | None = SETTINGS.keep_within_daily,
+    keep_within_weekly: str | None = SETTINGS.keep_within_weekly,
+    keep_within_monthly: str | None = SETTINGS.keep_within_monthly,
+    keep_within_yearly: str | None = SETTINGS.keep_within_yearly,
+    prune: bool = SETTINGS.prune,
+    repack_cacheable_only: bool = SETTINGS.repack_cacheable_only,
+    repack_small: bool = SETTINGS.repack_small,
+    repack_uncompressed: bool = SETTINGS.repack_uncompressed,
+    tag_forget: list[str] | None = SETTINGS.tag_forget,
+    sleep: int | None = SETTINGS.sleep,
+) -> None:
+    LOGGER.info("Backing up '%s' to '%s'...", path, repo)
+    if chmod:
+        run_chmod(path, "d", "u=rwx,g=rx,o=rx")
+        run_chmod(path, "f", "u=rw,g=r,o=r")
+    if chown is not None:
+        run("sudo", "chown", "-R", f"{chown}:{chown}", str(path))
+    try:
+        _backup_core(
+            path,
+            repo,
+            password=password,
+            dry_run=dry_run,
+            exclude=exclude,
+            exclude_i=exclude_i,
+            read_concurrency=read_concurrency,
+            tag=tag_backup,
+        )
+    except CalledProcessError as error:
+        if search(
+            "Is there a repository at the following location?",
+            error.stderr,
+            flags=MULTILINE,
+        ):
+            LOGGER.info("Auto-initializing repo...")
+            init(repo, password=password)
+            _backup_core(
+                path,
+                repo,
+                password=password,
+                dry_run=dry_run,
+                exclude=exclude,
+                exclude_i=exclude_i,
+                read_concurrency=read_concurrency,
+                tag=tag_backup,
+            )
+        else:
+            raise
+    if run_forget:
+        forget(
+            repo,
+            password=password,
+            keep_last=keep_last,
+            keep_hourly=keep_hourly,
+            keep_daily=keep_daily,
+            keep_weekly=keep_weekly,
+            keep_monthly=keep_monthly,
+            keep_yearly=keep_yearly,
+            keep_within=keep_within,
+            keep_within_hourly=keep_within_hourly,
+            keep_within_daily=keep_within_daily,
+            keep_within_weekly=keep_within_weekly,
+            keep_within_monthly=keep_within_monthly,
+            keep_within_yearly=keep_within_yearly,
+            prune=prune,
+            repack_cacheable_only=repack_cacheable_only,
+            repack_small=repack_small,
+            repack_uncompressed=repack_uncompressed,
+            tag=tag_forget,
+        )
+    if sleep is None:
+        LOGGER.info("Finished backing up '%s' to '%s'", path, repo)
+    else:
+        delta = TimeDelta(seconds=sleep)
+        LOGGER.info(
+            "Finished backing up '%s' to '%s'; sleeping for %s...", path, repo, delta
+        )
+        time.sleep(sleep)
+        LOGGER.info("Finishing sleeping for %s", delta)
+
+
+def _backup_core(
+    path: PathLike,
+    repo: Repo,
+    /,
+    *,
+    password: PasswordLike = SETTINGS.password,
+    dry_run: bool = SETTINGS.dry_run,
+    exclude: list[str] | None = SETTINGS.exclude_backup,
+    exclude_i: list[str] | None = SETTINGS.exclude_i_backup,
+    read_concurrency: int = SETTINGS.read_concurrency,
+    tag: list[str] | None = SETTINGS.tag_backup,
+) -> None:
+    with yield_repo_env(repo), yield_password(password=password):
+        run(
+            "restic",
+            "backup",
+            *expand_dry_run(dry_run=dry_run),
+            *expand_exclude(exclude=exclude),
+            *expand_exclude_i(exclude_i=exclude_i),
+            "--read-concurrency",
+            str(read_concurrency),
+            *expand_tag(tag=tag),
+            str(path),
+            print=True,
+        )
+
+
+def init(repo: Repo, /, *, password: PasswordLike = SETTINGS.password) -> None:
+    LOGGER.info("Initializing '%s'", repo)
+    with yield_repo_env(repo), yield_password(password=password):
+        run("restic", "init", print=True)
+    LOGGER.info("Finished initializing '%s'", repo)
+
+
+def copy(
+    src: Repo,
+    dest: Repo,
+    /,
+    *,
+    src_password: PasswordLike = SETTINGS.password,
+    dest_password: PasswordLike = SETTINGS.password,
+    tag: list[str] | None = SETTINGS.tag_copy,
+) -> None:
+    LOGGER.info("Copying snapshots from '%s' to '%s'...", src, dest)
+    with (
+        yield_repo_env(src, env_var="RESTIC_FROM_REPOSITORY"),
+        yield_repo_env(dest),
+        yield_password(password=src_password, env_var="RESTIC_FROM_PASSWORD_FILE"),
+        yield_password(password=dest_password),
+    ):
+        run("restic", "copy", *expand_tag(tag=tag), print=True)
+    LOGGER.info("Finished copying snapshots from '%s' to '%s'", src, dest)
+
+
+def forget(
+    repo: Repo,
+    /,
+    *,
+    password: PasswordLike = SETTINGS.password,
+    dry_run: bool = SETTINGS.dry_run,
+    keep_last: int | None = SETTINGS.keep_last,
+    keep_hourly: int | None = SETTINGS.keep_hourly,
+    keep_daily: int | None = SETTINGS.keep_daily,
+    keep_weekly: int | None = SETTINGS.keep_weekly,
+    keep_monthly: int | None = SETTINGS.keep_monthly,
+    keep_yearly: int | None = SETTINGS.keep_yearly,
+    keep_within: str | None = SETTINGS.keep_within,
+    keep_within_hourly: str | None = SETTINGS.keep_within_hourly,
+    keep_within_daily: str | None = SETTINGS.keep_within_daily,
+    keep_within_weekly: str | None = SETTINGS.keep_within_weekly,
+    keep_within_monthly: str | None = SETTINGS.keep_within_monthly,
+    keep_within_yearly: str | None = SETTINGS.keep_within_yearly,
+    prune: bool = SETTINGS.prune,
+    repack_cacheable_only: bool = SETTINGS.repack_cacheable_only,
+    repack_small: bool = SETTINGS.repack_small,
+    repack_uncompressed: bool = SETTINGS.repack_uncompressed,
+    tag: list[str] | None = SETTINGS.tag_forget,
+) -> None:
+    LOGGER.info("Forgetting snapshots in '%s'...", repo)
+    with yield_repo_env(repo), yield_password(password=password):
+        run(
+            "restic",
+            "forget",
+            *expand_dry_run(dry_run=dry_run),
+            *expand_keep("last", n=keep_last),
+            *expand_keep("hourly", n=keep_hourly),
+            *expand_keep("daily", n=keep_daily),
+            *expand_keep("weekly", n=keep_weekly),
+            *expand_keep("monthly", n=keep_monthly),
+            *expand_keep("yearly", n=keep_yearly),
+            *expand_keep_within("within", duration=keep_within),
+            *expand_keep_within("within-hourly", duration=keep_within_hourly),
+            *expand_keep_within("within-daily", duration=keep_within_daily),
+            *expand_keep_within("within-weekly", duration=keep_within_weekly),
+            *expand_keep_within("within-monthly", duration=keep_within_monthly),
+            *expand_keep_within("within-yearly", duration=keep_within_yearly),
+            *expand_bool("prune", bool_=prune),
+            *expand_bool("repack-cacheable-only", bool_=repack_cacheable_only),
+            *expand_bool("repack-small", bool_=repack_small),
+            *expand_bool("repack-uncompressed", bool_=repack_uncompressed),
+            *expand_tag(tag=tag),
+            print=True,
+        )
+    LOGGER.info("Finished forgetting snapshots in '%s'", repo)
+
+
+def restore(
+    repo: Repo,
+    target: PathLike,
+    /,
+    *,
+    password: PasswordLike = SETTINGS.password,
+    delete: bool = SETTINGS.delete,
+    dry_run: bool = SETTINGS.dry_run,
+    exclude: list[str] | None = SETTINGS.exclude_restore,
+    exclude_i: list[str] | None = SETTINGS.exclude_i_restore,
+    include: list[str] | None = SETTINGS.include_restore,
+    include_i: list[str] | None = SETTINGS.include_i_restore,
+    tag: list[str] | None = SETTINGS.tag_restore,
+    snapshot: str = SETTINGS.snapshot,
+) -> None:
+    LOGGER.info("Restoring snapshot '%s' of '%s' to '%s'...", snapshot, repo, target)
+    with yield_repo_env(repo), yield_password(password=password):
+        run(
+            "restic",
+            "restore",
+            *expand_bool("delete", bool_=delete),
+            *expand_dry_run(dry_run=dry_run),
+            *expand_exclude(exclude=exclude),
+            *expand_exclude_i(exclude_i=exclude_i),
+            *expand_include(include=include),
+            *expand_include_i(include_i=include_i),
+            *expand_tag(tag=tag),
+            "--target",
+            str(target),
+            "--verify",
+            snapshot,
+            print=True,
+        )
+    LOGGER.info(
+        "Finished restoring snapshot '%s' of '%s' to '%s'", snapshot, repo, target
+    )
+
+
+def snapshots(repo: Repo, /, *, password: PasswordLike = SETTINGS.password) -> None:
+    LOGGER.info("Listing snapshots in '%s'...", repo)
+    with yield_repo_env(repo), yield_password(password=password):
+        run("restic", "snapshots", print=True)
+    LOGGER.info("Finished listing snapshots in '%s'", repo)
+
+
+__all__ = ["backup", "copy", "forget", "init", "restore", "snapshots"]

restic/logging.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from logging import getLogger
+
+LOGGER = getLogger("restic")
+
+
+__all__ = ["LOGGER"]

restic/repo.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Self, assert_never
+
+from typed_settings import Secret, load_settings
+from utilities.os import temp_environ
+from utilities.re import extract_group, extract_groups
+
+from restic.settings import LOADERS, SETTINGS, Settings
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from restic.types import SecretLike
+
+
+type Repo = Backblaze | Local | SFTP
+
+
+@dataclass(order=True, unsafe_hash=True, slots=True)
+class Backblaze:
+    key_id: Secret[str]
+    application_key: Secret[str]
+    bucket: str
+    path: Path
+
+    @classmethod
+    def parse(
+        cls,
+        text: str,
+        /,
+        *,
+        key_id: SecretLike | None = SETTINGS.backblaze_key_id,
+        application_key: SecretLike | None = SETTINGS.backblaze_application_key,
+    ) -> Self:
+        settings = load_settings(Settings, LOADERS)
+        match key_id, settings.backblaze_key_id:
+            case Secret() as key_id_use, _:
+                ...
+            case str(), _:
+                key_id_use = Secret(key_id)
+            case None, Secret() as key_id_use:
+                ...
+            case None, None:
+                msg = "'BACKBLAZE_KEY_ID' is missing"
+                raise ValueError(msg)
+            case never:
+                assert_never(never)
+        match application_key, settings.backblaze_application_key:
+            case Secret() as application_key_use, _:
+                ...
+            case str(), _:
+                application_key_use = Secret(application_key)
+            case None, Secret() as application_key_use:
+                ...
+            case None, None:
+                msg = "'BACKBLAZE_APPLICATION_KEY' is missing"
+                raise ValueError(msg)
+            case never:
+                assert_never(never)
+        bucket, path = extract_groups(r"^b2:([^@:]+):([^@+]+)$", text)
+        return cls(key_id_use, application_key_use, bucket, Path(path))
+
+    @property
+    def repository(self) -> str:
+        return f"b2:{self.bucket}:{self.path}"
+
+
+@dataclass(order=True, unsafe_hash=True, slots=True)
+class Local:
+    path: Path
+
+    @classmethod
+    def parse(cls, text: str, /) -> Self:
+        path = extract_group(r"^local:([^@:]+)$", text)
+        return cls(Path(path))
+
+    @property
+    def repository(self) -> str:
+        return f"local:{self.path}"
+
+
+@dataclass(order=True, unsafe_hash=True, slots=True)
+class SFTP:
+    user: str
+    hostname: str
+    path: Path
+
+    @classmethod
+    def parse(cls, text: str, /) -> Self:
+        user, hostname, path = extract_groups(
+            r"^sftp:([^@:]+)@([^@:]+):([^@:]+)$", text
+        )
+        return cls(user, hostname, Path(path))
+
+    @property
+    def repository(self) -> str:
+        return f"sftp:{self.user}@{self.hostname}:{self.path}"
+
+
+@contextmanager
+def yield_repo_env(
+    repo: Repo, /, *, env_var: str = "RESTIC_REPOSITORY"
+) -> Iterator[None]:
+    match repo:
+        case Backblaze():
+            with temp_environ(
+                {env_var: repo.repository},
+                B2_ACCOUNT_ID=repo.key_id.get_secret_value(),
+                B2_ACCOUNT_KEY=repo.application_key.get_secret_value(),
+            ):
+                yield
+        case Local() | SFTP():
+            with temp_environ({env_var: repo.repository}):
+                yield
+        case never:
+            assert_never(never)
+
+
+__all__ = ["SFTP", "Backblaze", "Local", "Repo", "yield_repo_env"]

restic/settings.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+from os import getenv
+from typing import Any
+
+from attrs import fields_dict
+from typed_settings import (
+    EnvLoader,
+    FileLoader,
+    Secret,
+    TomlFormat,
+    find,
+    load_settings,
+    option,
+    secret,
+    settings,
+)
+from utilities.os import CPU_COUNT
+
+CONFIG_FILE = getenv("RESTIC_CONFIG_FILE", "config.toml")
+SECRETS_FILE = getenv("RESTIC_SECRETS_FILE", "secrets.toml")
+LOADERS = [
+    FileLoader({"*.toml": TomlFormat(None)}, [find(CONFIG_FILE), find(SECRETS_FILE)]),
+    EnvLoader(""),
+]
+
+
+@settings(kw_only=True)
+class Settings:
+    # global
+    dry_run: bool = option(default=False, help="Just print what would have been done")
+    password: Secret[str] = secret(
+        default=Secret("password"), help="Repository password or password file"
+    )
+    # backblaze
+    backblaze_key_id: Secret[str] | None = secret(default=None, help="Backblaze key ID")
+    backblaze_application_key: Secret[str] | None = secret(
+        default=None, help="Backblaze application key"
+    )
+    # backup
+    chmod: bool = option(default=False, help="Change permissions of the directory/file")
+    chown: str | None = option(
+        default=None, help="Change ownership of the directory/file"
+    )
+    exclude_backup: list[str] | None = option(default=None, help="Exclude a pattern")
+    exclude_i_backup: list[str] | None = option(
+        default=None, help="Exclude a pattern but ignores the casing of filenames"
+    )
+    read_concurrency: int = option(
+        default=max(round(CPU_COUNT / 2), 2), help="Read `n` files concurrency"
+    )
+    tag_backup: list[str] | None = option(
+        default=None, help="Add tags for the snapshot in the format `tag[,tag,...]`"
+    )
+    run_forget: bool = option(
+        default=True, help="Automatically run the 'forget' command"
+    )
+    sleep: int | None = option(default=None, help="Sleep after a successful backup")
+    # copy
+    tag_copy: list[str] | None = option(
+        default=None, help="Only consider snapshots including `tag[,tag,...]`"
+    )
+    # forget
+    keep_last: int | None = option(default=None, help="Keep the last n snapshots")
+    keep_hourly: int | None = option(
+        default=None, help="Keep the last n hourly snapshots"
+    )
+    keep_daily: int | None = option(
+        default=None, help="Keep the last n daily snapshots"
+    )
+    keep_weekly: int | None = option(
+        default=None, help="Keep the last n weekly snapshots"
+    )
+    keep_monthly: int | None = option(
+        default=None, help="Keep the last n monthly snapshots"
+    )
+    keep_yearly: int | None = option(
+        default=None, help="Keep the last n yearly snapshots"
+    )
+    keep_within: str | None = option(
+        default=None,
+        help="Keep snapshots that are newer than duration relative to the latest snapshot",
+    )
+    keep_within_hourly: str | None = option(
+        default=None,
+        help="Keep hourly snapshots that are newer than duration relative to the latest snapshot",
+    )
+    keep_within_daily: str | None = option(
+        default=None,
+        help="Keep daily snapshots that are newer than duration relative to the latest snapshot",
+    )
+    keep_within_weekly: str | None = option(
+        default=None,
+        help="Keep weekly snapshots that are newer than duration relative to the latest snapshot",
+    )
+    keep_within_monthly: str | None = option(
+        default=None,
+        help="Keep monthly snapshots that are newer than duration relative to the latest snapshot",
+    )
+    keep_within_yearly: str | None = option(
+        default=None,
+        help="Keep yearly snapshots that are newer than duration relative to the latest snapshot",
+    )
+    prune: bool = option(
+        default=True,
+        help="Automatically run the 'prune' command if snapshots have been removed",
+    )
+    repack_cacheable_only: bool = option(
+        default=False, help="Only repack packs which are cacheable"
+    )
+    repack_small: bool = option(
+        default=True, help="Repack pack files below 80% of target pack size"
+    )
+    repack_uncompressed: bool = option(
+        default=True, help="Repack all uncompressed data"
+    )
+    tag_forget: list[str] | None = option(
+        default=None, help="Only consider snapshots including tag[,tag,...]"
+    )
+    # restore
+    delete: bool = option(
+        default=False,
+        help="Delete files from target directory if they do not exist in snapshot",
+    )
+    exclude_restore: list[str] | None = option(default=None, help="Exclude a pattern")
+    exclude_i_restore: list[str] | None = option(
+        default=None, help="Exclude a pattern but ignores the casing of filenames"
+    )
+    include_restore: list[str] | None = option(default=None, help="Include a pattern")
+    include_i_restore: list[str] | None = option(
+        default=None, help="Include a pattern but ignores the casing of filenames"
+    )
+    tag_restore: list[str] | None = option(
+        default=None,
+        help='Only consider snapshots including tag[,tag,...], when snapshot ID "latest" is given',
+    )
+    snapshot: str = option(default="latest", help="Snapshot ID to restore")
+
+
+SETTINGS = load_settings(Settings, LOADERS)
+
+
+def _get_help(member_descriptor: Any, /) -> None:
+    return fields_dict(Settings)[member_descriptor.__name__].metadata["typed-settings"][
+        "help"
+    ]
+
+
+@settings(kw_only=True)
+class InitSettings:
+    password: Secret[str] = secret(
+        default=SETTINGS.password, help=_get_help(Settings.password)
+    )
+
+
+@settings(kw_only=True)
+class BackupSettings:
+    chmod: bool = option(default=SETTINGS.chmod, help=_get_help(Settings.chmod))
+    chown: str | None = option(default=SETTINGS.chown, help=_get_help(Settings.chown))
+    password: Secret[str] = secret(
+        default=SETTINGS.password, help=_get_help(Settings.password)
+    )
+    dry_run: bool = option(default=SETTINGS.dry_run, help=_get_help(Settings.dry_run))
+    exclude: list[str] | None = option(
+        default=SETTINGS.exclude_backup, help=_get_help(Settings.exclude_backup)
+    )
+    exclude_i: list[str] | None = option(
+        default=SETTINGS.exclude_i_backup, help=_get_help(Settings.exclude_i_backup)
+    )
+    read_concurrency: int = option(
+        default=SETTINGS.read_concurrency, help=_get_help(Settings.read_concurrency)
+    )
+    tag_backup: list[str] | None = option(
+        default=SETTINGS.tag_backup, help=_get_help(Settings.tag_backup)
+    )
+    run_forget: bool = option(
+        default=SETTINGS.run_forget, help=_get_help(Settings.run_forget)
+    )
+    keep_last: int | None = option(
+        default=SETTINGS.keep_last, help=_get_help(Settings.keep_last)
+    )
+    keep_hourly: int | None = option(
+        default=SETTINGS.keep_hourly, help=_get_help(Settings.keep_hourly)
+    )
+    keep_daily: int | None = option(
+        default=SETTINGS.keep_daily, help=_get_help(Settings.keep_daily)
+    )
+    keep_weekly: int | None = option(
+        default=SETTINGS.keep_weekly, help=_get_help(Settings.keep_weekly)
+    )
+    keep_monthly: int | None = option(
+        default=SETTINGS.keep_monthly, help=_get_help(Settings.keep_monthly)
+    )
+    keep_yearly: int | None = option(
+        default=SETTINGS.keep_yearly, help=_get_help(Settings.keep_yearly)
+    )
+    keep_within: str | None = option(
+        default=SETTINGS.keep_within, help=_get_help(Settings.keep_within)
+    )
+    keep_within_hourly: str | None = option(
+        default=SETTINGS.keep_within_hourly, help=_get_help(Settings.keep_within_hourly)
+    )
+    keep_within_daily: str | None = option(
+        default=SETTINGS.keep_within_daily, help=_get_help(Settings.keep_within_daily)
+    )
+    keep_within_weekly: str | None = option(
+        default=SETTINGS.keep_within_weekly, help=_get_help(Settings.keep_within_weekly)
+    )
+    keep_within_monthly: str | None = option(
+        default=SETTINGS.keep_within_monthly,
+        help=_get_help(Settings.keep_within_monthly),
+    )
+    keep_within_yearly: str | None = option(
+        default=SETTINGS.keep_within_yearly, help=_get_help(Settings.keep_within_yearly)
+    )
+    prune: bool = option(default=SETTINGS.prune, help=_get_help(Settings.prune))
+    repack_cacheable_only: bool = option(
+        default=SETTINGS.repack_cacheable_only,
+        help=_get_help(Settings.repack_cacheable_only),
+    )
+    repack_small: bool = option(
+        default=SETTINGS.repack_small, help=_get_help(Settings.repack_small)
+    )
+    repack_uncompressed: bool = option(
+        default=SETTINGS.repack_uncompressed,
+        help=_get_help(Settings.repack_uncompressed),
+    )
+    tag_forget: list[str] | None = option(
+        default=SETTINGS.tag_forget, help=_get_help(Settings.tag_forget)
+    )
+    sleep: int | None = option(default=SETTINGS.sleep, help=_get_help(Settings.sleep))
+
+
+@settings(kw_only=True)
+class CopySettings:
+    src_password: Secret[str] = secret(
+        default=SETTINGS.password, help=_get_help(Settings.password)
+    )
+    dest_password: Secret[str] = secret(
+        default=SETTINGS.password, help=_get_help(Settings.password)
+    )
+    tag: list[str] | None = option(
+        default=SETTINGS.tag_copy, help=_get_help(Settings.tag_copy)
+    )
+
+
+@settings(kw_only=True)
+class ForgetSettings:
+    password: Secret[str] = secret(
+        default=SETTINGS.password, help=_get_help(Settings.password)
+    )
+    dry_run: bool = option(default=SETTINGS.dry_run, help=_get_help(Settings.dry_run))
+    keep_last: int | None = option(
+        default=SETTINGS.keep_last, help=_get_help(Settings.keep_last)
+    )
+    keep_hourly: int | None = option(
+        default=SETTINGS.keep_hourly, help=_get_help(Settings.keep_hourly)
+    )
+    keep_daily: int | None = option(
+        default=SETTINGS.keep_daily, help=_get_help(Settings.keep_daily)
+    )
+    keep_weekly: int | None = option(
+        default=SETTINGS.keep_weekly, help=_get_help(Settings.keep_weekly)
+    )
+    keep_monthly: int | None = option(
+        default=SETTINGS.keep_monthly, help=_get_help(Settings.keep_monthly)
+    )
+    keep_yearly: int | None = option(
+        default=SETTINGS.keep_yearly, help=_get_help(Settings.keep_yearly)
+    )
+    keep_within: str | None = option(
+        default=SETTINGS.keep_within, help=_get_help(Settings.keep_within)
+    )
+    keep_within_hourly: str | None = option(
+        default=SETTINGS.keep_within_hourly, help=_get_help(Settings.keep_within_hourly)
+    )
+    keep_within_daily: str | None = option(
+        default=SETTINGS.keep_within_daily, help=_get_help(Settings.keep_within_daily)
+    )
+    keep_within_weekly: str | None = option(
+        default=SETTINGS.keep_within_weekly, help=_get_help(Settings.keep_within_weekly)
+    )
+    keep_within_monthly: str | None = option(
+        default=SETTINGS.keep_within_monthly,
+        help=_get_help(Settings.keep_within_monthly),
+    )
+    keep_within_yearly: str | None = option(
+        default=SETTINGS.keep_within_yearly, help=_get_help(Settings.keep_within_yearly)
+    )
+    prune: bool = option(default=SETTINGS.prune, help=_get_help(Settings.prune))
+    repack_cacheable_only: bool = option(
+        default=SETTINGS.repack_cacheable_only,
+        help=_get_help(Settings.repack_cacheable_only),
+    )
+    repack_small: bool = option(
+        default=SETTINGS.repack_small, help=_get_help(Settings.repack_small)
+    )
+    repack_uncompressed: bool = option(
+        default=SETTINGS.repack_uncompressed,
+        help=_get_help(Settings.repack_uncompressed),
+    )
+    tag: list[str] | None = option(
+        default=SETTINGS.tag_forget, help=_get_help(Settings.tag_forget)
+    )
+
+
+@settings(kw_only=True)
+class RestoreSettings:
+    password: Secret[str] = secret(
+        default=SETTINGS.password, help=_get_help(Settings.password)
+    )
+    delete: bool = option(default=SETTINGS.delete, help=_get_help(Settings.delete))
+    dry_run: bool = option(default=SETTINGS.dry_run, help=_get_help(Settings.dry_run))
+    exclude: list[str] | None = option(
+        default=SETTINGS.exclude_restore, help=_get_help(Settings.exclude_restore)
+    )
+    exclude_i: list[str] | None = option(
+        default=SETTINGS.exclude_i_restore, help=_get_help(Settings.exclude_i_restore)
+    )
+    include: list[str] | None = option(
+        default=SETTINGS.include_restore, help=_get_help(Settings.include_restore)
+    )
+    include_i: list[str] | None = option(
+        default=SETTINGS.include_i_restore, help=_get_help(Settings.include_i_restore)
+    )
+    tag: list[str] | None = option(
+        default=SETTINGS.tag_restore, help=_get_help(Settings.tag_restore)
+    )
+    snapshot: str = option(default=SETTINGS.snapshot, help=_get_help(Settings.snapshot))
+
+
+@settings(kw_only=True)
+class SnapshotsSettings:
+    password: Secret[str] = secret(
+        default=SETTINGS.password, help=_get_help(Settings.password)
+    )
+
+
+__all__ = [
+    "LOADERS",
+    "SETTINGS",
+    "BackupSettings",
+    "CopySettings",
+    "ForgetSettings",
+    "InitSettings",
+    "RestoreSettings",
+    "Settings",
+    "SnapshotsSettings",
+]

restic/types.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from typed_settings import Secret
+from utilities.types import PathLike
+
+type PasswordLike = Secret[str] | PathLike
+type SecretLike = Secret[str] | str
+
+__all__ = ["PasswordLike", "SecretLike"]

restic/utilities.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from itertools import chain
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal, assert_never
+
+from typed_settings import Secret
+from utilities.os import temp_environ
+from utilities.subprocess import run
+from utilities.tempfile import TemporaryFile
+
+from restic.settings import SETTINGS
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from utilities.types import PathLike
+
+    from restic.types import PasswordLike
+
+
+def expand_bool(flag: str, /, *, bool_: bool = False) -> list[str]:
+    return [f"--{flag}"] if bool_ else []
+
+
+def expand_dry_run(*, dry_run: bool = False) -> list[str]:
+    return expand_bool("dry-run", bool_=dry_run)
+
+
+def expand_exclude(*, exclude: list[str] | None = None) -> list[str]:
+    return _expand_list("exclude", arg=exclude)
+
+
+def expand_exclude_i(*, exclude_i: list[str] | None = None) -> list[str]:
+    return _expand_list("iexclude", arg=exclude_i)
+
+
+def expand_include(*, include: list[str] | None = None) -> list[str]:
+    return _expand_list("include", arg=include)
+
+
+def expand_include_i(*, include_i: list[str] | None = None) -> list[str]:
+    return _expand_list("iinclude", arg=include_i)
+
+
+def expand_keep(freq: str, /, *, n: int | None = None) -> list[str]:
+    return [] if n is None else [f"--keep-{freq}", str(n)]
+
+
+def expand_keep_within(freq: str, /, *, duration: str | None = None) -> list[str]:
+    return [] if duration is None else [f"--keep-{freq}", duration]
+
+
+def expand_tag(*, tag: list[str] | None = None) -> list[str]:
+    return _expand_list("tag", arg=tag)
+
+
+def run_chmod(path: PathLike, type_: Literal["f", "d"], mode: str, /) -> None:
+    run("sudo", "find", str(path), "-type", type_, "-exec", "chmod", mode, "{}", "+")
+
+
+@contextmanager
+def yield_password(
+    *, password: PasswordLike = SETTINGS.password, env_var: str = "RESTIC_PASSWORD_FILE"
+) -> Iterator[None]:
+    match password:
+        case Secret():
+            value = password.get_secret_value()
+        case Path() | str() as value:
+            ...
+        case never:
+            assert_never(never)
+    match value:
+        case Path():
+            if value.is_file():
+                with temp_environ({env_var: str(value)}):
+                    yield
+            else:
+                msg = f"Password file not found: '{value!s}'"
+                raise FileNotFoundError(msg)
+        case str():
+            if Path(value).is_file():
+                with temp_environ({env_var: value}):
+                    yield
+            else:
+                with TemporaryFile() as temp, temp_environ({env_var: str(temp)}):
+                    _ = temp.write_text(value)
+                    yield
+        case never:
+            assert_never(never)
+
+
+def _expand_list(flag: str, /, *, arg: list[str] | None = None) -> list[str]:
+    return (
+        [] if arg is None else list(chain.from_iterable([f"--{flag}", a] for a in arg))
+    )
+
+
+__all__ = [
+    "expand_bool",
+    "expand_dry_run",
+    "expand_exclude",
+    "expand_exclude_i",
+    "expand_include",
+    "expand_include_i",
+    "expand_keep",
+    "expand_keep_within",
+    "expand_tag",
+    "run_chmod",
+    "yield_password",
+]