yd-cli 0.3__py3-none-any.whl

yd/types.py

@@ -0,0 +1,159 @@
+# SPDX-FileCopyrightText: Christian Heinze
+#
+# SPDX-License-Identifier: MIT
+"""Shared data structures."""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+from typing import TYPE_CHECKING, Annotated
+
+import msgspec
+
+if TYPE_CHECKING:
+    import datetime as dt
+    from pathlib import Path
+
+
+class SyfError(RuntimeError): ...
+
+
+class ConfigLoadError(SyfError):
+    """Exception raised when loading a configuration fails."""
+
+
+class EnvCaptureError(SyfError):
+    """Exception raised when capturing the environment fails."""
+
+
+class CommandBuildError(SyfError):
+    """Exception raised when building the rsync command fails."""
+
+
+class OutputParseError(SyfError):
+    """Exception raised when parsing output of other CLI apps fails."""
+
+
+class OutputConsumeError(SyfError):
+    """Exception raised when the consumption of parsed output fails."""
+
+
+@dataclasses.dataclass(slots=True, kw_only=True)
+class Environment:
+    current_time: dt.datetime
+    log_level: int | None
+
+    home_dir: Path
+    config_dir: Path
+
+    rsync_bin: str
+    echo_bin: str
+    editor_bin: str | None
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class AvailableConfig:
+    name: str
+    description: str | None
+
+
+type _NonemptyStr = Annotated[str, msgspec.Meta(min_length=1)]
+
+
+# Does not explicitly omit default values as not used for serialization.
+class CommandGroup(msgspec.Struct, kw_only=True, forbid_unknown_fields=True):
+    """Configuration for a group of rsync commands.
+
+    Parameters
+    ----------
+    src_home/target_home
+        Absolute path used to turn relative src/target path in individual commands into
+        absolute paths.
+
+        The `target_home` is passed to `datetime.strftime` via the `format` parameter,
+        that is, placeholders for date/time components like `%Y`, `%m`, etc., are
+        replaced with the actual values at runtime.
+    mtp_target
+        Set True if communication with the target works with MTP. Due to
+        technical limitations of that protocol, synchronization needs to be done
+        in-place (rather than copying to a temporary file and renaming once
+        done). This may lead to corrupted files if the process is interrupted;
+        don't set unless necessary.
+    backup
+        Path to backup directory. Added to each command and if relative, then taken
+        as relative to target home. If None, a default relative path is used.
+
+        The `target` is passed to `datetime.strftime` via the `format` parameter, that
+        is, placeholders for date/time components like `%Y`, `%m`, etc., are replaced
+        with the actual values at runtime.
+    exclude
+        Exclude pattern joined to each command's individual exclude patterns.
+
+        Patterns are matched against every file/directory to be transferred.
+        - If not `/` or `**` is included in the pattern, then matches against full path.
+        - Otherwise matches against filename.
+        - Trailing `/` only matches directories.
+        - `*` matches any number of non-`/` characters; `**` any number of any chars.
+        - If pattern starts with `/` it's anchored at the start of the path.
+        - `?` matches a single character; `[123]` matches one of 1, 2, or 3.
+    """
+
+    src_home: _NonemptyStr | None = None
+    target_home: _NonemptyStr | None = None
+
+    mtp_target: bool = False
+    backup: _NonemptyStr | None = None
+    exclude: list[_NonemptyStr] = msgspec.field(default_factory=list)
+
+    commands: Annotated[list[Command], msgspec.Meta(min_length=1)]
+
+
+class Command(msgspec.Struct, kw_only=True, forbid_unknown_fields=True):
+    """Individual rsync command specification.
+
+    Parameters
+    ----------
+    src, target
+        Source/target directory. Required to be relative (to src_home/target_home) path.
+
+        The `target` is passed to `datetime.strftime` via the `format` parameter, that
+        is, placeholders for date/time components like `%Y`, `%m`, etc., are replaced
+        with the actual values at runtime.
+    delete_extra
+        If `True`, then elements present in `target` but not `src` are deleted.
+    exclude
+        Patterns describing contents of `src` which is not transferred.
+        Will be joined with settings in the containing `CommandGroup` object.
+    """
+
+    src: _NonemptyStr
+    target: _NonemptyStr | None = None
+
+    delete_extra: bool = True
+    exclude: list[_NonemptyStr] = msgspec.field(default_factory=list)
+
+
+class Action(enum.StrEnum):
+    DELETE = "*"
+    CREATE = "c"
+    COPY = ">"
+    ATTRUPDATE = "."
+    HARDLINK = "h"
+
+    def __str__(self) -> str:
+        return self.name.lower()
+
+
+class Transaction(msgspec.Struct):
+    filename: str
+    transfer_bytes: int
+    info: Annotated[
+        # The first character alternative match the non-`*`-options in `Action`.
+        str, msgspec.Meta(min_length=11, max_length=11, pattern=r"^(\*|c|>|h|\.)")
+    ]
+
+    # Custom `dec_hook` requires an obj type unknown to msgspec to be triggered.
+    @property
+    def action(self) -> Action:
+        return Action(self.info[0])

yd_cli-0.3.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: yd-cli
+Version: 0.3
+Summary: CLI tool to synchronize directories using rsync.
+Author: Christian Heinze
+License-Expression: MIT
+License-File: LICENSES/MIT.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: msgspec>=0.20
+Requires-Dist: rich>=14.3
+Requires-Dist: typer>=0.24
+Requires-Python: >=3.14
+Project-URL: Repository, https://codeberg.org/christianheinze/syf
+Description-Content-Type: text/markdown
+
+# Directory synchronization tool `yd`
+
+Build and execute `rsync` commands from *TOML* configuration files.
+
+## Create a config
+
+Create a new configuration called `photos` with:
+
+```bash
+yd edit --new photos
+```
+
+This command
+
+- creates `~/.config/yd/photos.toml` (or under `$XDG_CONFIG_HOME/yd` if set; relative paths are resolved from your home directory), and
+- opens it in the editor selected via `EDITOR`.
+
+Reopen an existing configuration with:
+
+```bash
+yd edit photos
+```
+
+## Configuration format
+
+### Example
+
+```toml
+# Phone backup
+src_home = "/home/alice"
+target_home = "/mnt/backup"
+backup = "deleted/%Y-%m-%d"
+exclude = [".venv/", "__pycache__/"]
+
+[[commands]]
+src = "Documents"
+exclude = ["*.log"]
+
+[[commands]]
+src = "Pictures"
+target = "pics-%Y-%m-%d"
+delete_extra = false
+```
+
+Leading comment lines directly at the top of the file are treated as the configuration description and are shown by `yd ls`.
+
+### Top-level options
+
+| Key | Meaning |
+| --- | --- |
+| `src_home` | Base directory for all `src` paths. Relative paths are resolved from your home directory. |
+| `target_home` | Base directory for all target paths. Relative paths are resolved from your home directory. `strftime` placeholders such as `%Y-%m-%d` are supported. |
+| `mtp_target` | Use in-place syncing for MTP targets. |
+| `backup` | Backup directory for replaced or deleted files. Relative paths are resolved from `target_home`. `strftime` placeholders are supported. |
+| `exclude` | Exclude patterns applied to every command. |
+
+`mtp_target` matters because `rsync` normally copies to a temporary file and renames it afterward, but that is not possible when syncing via *MTP*.
+
+### Command options
+
+| Key | Meaning |
+| --- | --- |
+| `src` | Relative source directory below `src_home`. |
+| `target` | Relative target directory below `target_home`; defaults to `src`. `strftime` placeholders are supported. |
+| `delete_extra` | Delete files in the target that do not exist in the source. Defaults to `true`. |
+| `exclude` | Extra exclude patterns for this command only. |
+
+### Notes
+
+- `src` and `target` must stay within `src_home` and `target_home` after path resolution.
+- `src_home` or `target_home` may be omitted from the configuration, but every missing value must then be supplied when running (via CLI parameters).
+- Exactly one of `--src-home -` and `--target-home -` may read from standard input in a single run.
+- If `backup` is omitted, `yd` creates a timestamped backup directory automatically unless `--no-backup` is specified.
+- If a configured source directory exists but is empty, `yd` reports that no synchronization was performed for that command. E.g., forgetting to mount an external drive does not delete all corresponding copies on harddrive).
+
+## Run a config
+
+Run a saved configuration by name:
+
+```bash
+yd run photos
+```
+
+### Options
+
+| Option | Meaning |
+| --- | --- |
+| `--dry-run` | Show what would happen without changing files. |
+| `--no-backup` | Disable backup handling for this run. |
+| `--keep-newer` | Skip updates when the target file is newer. |
+| `--rename-speedup` | Enable `rsync` options tuned for rename-heavy targets. This may require more disk space on the target. |
+| `--src-home PATH` | Override `src_home` from the config. Use `-` to read the value from standard input. |
+| `--target-home PATH` | Override `target_home` from the config. Use `-` to read the value from standard input. |
+
+## List configs
+
+List available configurations with:
+
+```bash
+yd ls
+```
+
+This shows the configuration name together with the optional leading-comment description.
+
+## Why `yd`?
+
+- Has one character from `synchronize` and one from `directory`.
+- Easy to type with both *QWERTZ* and *QUERTY* keyboards.
+- Name was still available on *PyPI*.

yd_cli-0.3.dist-info/RECORD

@@ -0,0 +1,13 @@
+yd/__init__.py,sha256=r2mprMYiyYZ1lIxZRseO4qOjsCLf5UNccL71EPm8Tcw,878
+yd/__main__.py,sha256=6NlT1w1H9uWETLssY37wSpRuIFouOoomfY5DcQ1YU10,201
+yd/cli.py,sha256=2dqSDRpS_-G3i2fkqQ4jYsCGMSEChN-eCI4yqO02GDw,15619
+yd/commands.py,sha256=BlU9KM1EpO2sXhZITzs9rv1Hymlx-WAsGDv-PKodFKo,9059
+yd/execution.py,sha256=UHMi2JJEou_V0uIVJ4NLHLv8QNEytwlOkp4ou7NK2Do,4778
+yd/io.py,sha256=XYVugCKhbYkS8lEqDcGsnI8fo7I5CoshXJ63jm95Ims,6428
+yd/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yd/types.py,sha256=6jb8zkvaDIQ_1-6lxM86VCe8NQsFFms-ygRKwNXy2o8,5035
+yd_cli-0.3.dist-info/licenses/LICENSES/MIT.txt,sha256=unowdk_KzQ7oBGrEJBQJOTzhui6aTsTzSSfjf447LKM,1077
+yd_cli-0.3.dist-info/WHEEL,sha256=bEhYrD-rjlF0iRRHiAnfJ0mEjMsRwm29hhDD7yRgWCY,80
+yd_cli-0.3.dist-info/entry_points.txt,sha256=D1fJ5Xv9YGtR8HaP_AC4h36jwV1FZpysiMLQIqgNW3Q,35
+yd_cli-0.3.dist-info/METADATA,sha256=WMy6Jcjvl6L2WFJcjeCVVQJIuuG8kzHxfAeEfzSRtmI,4543
+yd_cli-0.3.dist-info/RECORD,,

yd_cli-0.3.dist-info/WHEEL

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

yd_cli-0.3.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+yd = yd.cli:app
+

yd_cli-0.3.dist-info/licenses/LICENSES/MIT.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright 2026 Christian Heinze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.