pathapi-uri 0.1.0__py3-none-any.whl

uripath/_version.py

@@ -0,0 +1,11 @@
+"""The version of the installed distribution."""
+
+from __future__ import annotations
+
+from importlib import metadata as _metadata
+
+try:
+    __version__ = _metadata.version("pathapi-uri")
+except _metadata.PackageNotFoundError:
+    # Run from a source tree that was never installed.
+    __version__ = "0+unknown"

uripath/cli/__init__.py

@@ -0,0 +1,54 @@
+"""The `uripath` command line, built on `duho`.
+
+`main` is the entry point of the `uripath` console script and of `python -m
+uripath`. It needs the `cli` extra (`pip install "pathapi-uri[cli]"`); importing
+this package does not, so a bare install gets one line naming the extra in
+place of an `ImportError`. The root command, `Uripath`, is built on first use
+because its base class comes from `duho`.
+"""
+
+from __future__ import annotations
+
+import sys as _sys
+import typing as _ty
+
+if _ty.TYPE_CHECKING:
+    from ._root import Uripath
+
+__all__ = ["main"]
+
+_NEEDS_EXTRA = (
+    'uripath: error: the command line needs the "cli" extra: '
+    'pip install "pathapi-uri[cli]"'
+)
+
+
+def main(argv: "_ty.Optional[_ty.Sequence[str]]" = None) -> int:
+    """Run one `uripath` command and return its exit status.
+
+    `argv` is the arguments after the program name (default `sys.argv[1:]`).
+    Returns 0 on success, 1 when the operation failed, 2 for a wrong
+    invocation, 130 on Ctrl-C and 141 when the reader of standard output went
+    away. Results go to stdout and one `uripath: <Type>: <message>` line per
+    failure to stderr. Without `duho` it prints which extra to install and
+    returns 1.
+    """
+    try:
+        import duho  # noqa: F401
+    except ModuleNotFoundError as error:
+        if error.name != "duho":
+            raise
+        print(_NEEDS_EXTRA, file=_sys.stderr)
+        return 1
+    from ._root import run
+
+    return run(argv)
+
+
+def __getattr__(name: str) -> "_ty.Any":
+    """`Uripath`, the root command, imported on first use."""
+    if name == "Uripath":
+        from ._root import Uripath
+
+        return Uripath
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

uripath/cli/_common.py

@@ -0,0 +1,48 @@
+"""What the commands share: the base class and the standard streams."""
+
+from __future__ import annotations
+
+import sys as _sys
+import typing as _ty
+
+from duho import Cmd, LoggingArgs, UsageError, running_mode
+
+
+class Command(LoggingArgs, Cmd):
+    """The base of every command: `-v`, `-q` and `--loglevel`, and the logger
+    they raise, `uripath`."""
+
+    _logger_name_ = "uripath"
+    # A tail after `--` would be ignored; a path that starts with `-` is
+    # written `./-name`.
+    _allow_passthrough_ = False
+
+    @property
+    def wants_detail(self) -> bool:
+        """`-v` given more often than `-q`."""
+        return self.verbose > self.quiet
+
+
+def stdout() -> "_ty.BinaryIO":
+    """The binary standard output of the process."""
+    return _sys.stdout.buffer
+
+
+def stdin() -> "_ty.BinaryIO":
+    """The binary standard input of the process. A command served as a tool
+    has none: the server reads its requests from it."""
+    if running_mode() == "mcp":
+        raise UsageError("standard input is not available to a tool: name a file")
+    return _sys.stdin.buffer
+
+
+def source_of(text: str) -> "_ty.Union[str, _ty.BinaryIO]":
+    """Where a command reads bytes from: `-` is standard input, anything else
+    the path or URI it names."""
+    return stdin() if text == "-" else text
+
+
+def target_of(text: str) -> "_ty.Union[str, _ty.BinaryIO]":
+    """Where a command writes bytes to: `-` is standard output, anything else
+    the path or URI it names."""
+    return stdout() if text == "-" else text

uripath/cli/_root.py

@@ -0,0 +1,70 @@
+"""The root command and the run around it: exceptions become statuses."""
+
+from __future__ import annotations
+
+import os as _os
+import sys as _sys
+import typing as _ty
+
+from duho import AUTO, Cli, DefaultsFormatter
+from duho import main as _main
+
+from ..exceptions import OutputClosedError
+from .cp import Cp
+from .read import Read
+from .rm import Rm
+from .sync import Sync
+from .write import Write
+
+#: The status of a tool killed by SIGPIPE (128 + 13), and of Ctrl-C (128 + 2).
+_EXIT_BROKEN_PIPE = 141
+_EXIT_INTERRUPTED = 130
+
+
+class Uripath(Cli):
+    """Read, write, copy, remove and sync local paths and URIs. A PATH is a local path or a URI; - is standard input or output where bytes are read or written."""
+
+    _parsername_ = "uripath"
+    _version_ = AUTO
+    _distribution_ = "pathapi-uri"
+    _help_formatter_ = DefaultsFormatter
+    _exit_codes_ = {
+        1: "the operation failed",
+        2: "the invocation was wrong",
+        130: "interrupted",
+        141: "the reader of standard output went away",
+    }
+    _subcommands_ = [Read, Write, Rm, Cp, Sync]
+
+
+def _discard_stdout() -> None:
+    """Point the real standard output at the null device, so that the flush
+    the interpreter makes at exit cannot fail again."""
+    try:
+        devnull = _os.open(_os.devnull, _os.O_WRONLY)
+        _os.dup2(devnull, _sys.stdout.fileno())
+        _os.close(devnull)
+    except (OSError, ValueError, AttributeError):
+        pass
+
+
+def run(argv: "_ty.Optional[_ty.Sequence[str]]") -> int:
+    """Parse `argv`, run the command it names and return its exit status."""
+    try:
+        status = _main(Uripath, None if argv is None else list(argv))
+    except SystemExit as stop:
+        # The parser exits through SystemExit: 0 after --help and --version,
+        # 2 on a usage error.
+        if stop.code is None:
+            return 0
+        return stop.code if isinstance(stop.code, int) else 2
+    except OutputClosedError:
+        # Quiet, like a POSIX tool killed by SIGPIPE.
+        _discard_stdout()
+        return _EXIT_BROKEN_PIPE
+    except KeyboardInterrupt:
+        return _EXIT_INTERRUPTED
+    except Exception as error:
+        print(f"uripath: {type(error).__name__}: {error}", file=_sys.stderr)
+        return 1
+    return 0 if status is None else int(status)

uripath/cli/cp.py

@@ -0,0 +1,61 @@
+"""`uripath cp`: copy a path, a tree or a stream."""
+
+from __future__ import annotations
+
+from duho import UsageError
+
+from .. import as_path, copy_stream
+from ._common import Command, source_of, target_of
+
+__all__ = ["Cp"]
+
+
+class Cp(Command):
+    """Copy a file, or with --recursive a directory, from SOURCE to TARGET; either may be a URI."""
+
+    _parsername_ = "cp"
+
+    source: str
+    "The file, directory or URI to copy; - reads standard input. Required"
+    ("source",)
+
+    target: str
+    "Where to copy it to; - writes standard output. Required"
+    ("target",)
+
+    recursive: bool = False
+    "Copy a directory with everything in it; not with -. Omitted: a single file"
+    ("--recursive", "-r")
+
+    overwrite: bool = False
+    "Replace an existing TARGET. Omitted: an existing TARGET is refused"
+    ("--overwrite",)
+
+    follow_symlinks: bool = True
+    "Copy what a symbolic link points to. With --no-follow-symlinks: copy the link itself"
+    ("--follow-symlinks",)
+
+    preserve_metadata: bool = True
+    "Copy modes and times where the target can hold them. With --no-preserve-metadata: leave them out"
+    ("--preserve-metadata",)
+
+    def __call__(self) -> int:
+        streamed = "-" in (self.source, self.target)
+        if streamed and self.recursive:
+            raise UsageError("--recursive cannot copy from or to '-'")
+        if streamed:
+            # An exclusive create: no check-then-write race on the target.
+            copy_stream(
+                source_of(self.source),
+                target_of(self.target),
+                exclusive=not self.overwrite,
+            )
+            return 0
+        as_path(self.source).copy(
+            as_path(self.target),
+            overwrite=self.overwrite,
+            follow_symlinks=self.follow_symlinks,
+            preserve_metadata=self.preserve_metadata,
+            recursive=self.recursive,
+        )
+        return 0

uripath/cli/read.py

@@ -0,0 +1,22 @@
+"""`uripath read`: the bytes of a path to standard output."""
+
+from __future__ import annotations
+
+from .. import copy_stream
+from ._common import Command, source_of, stdout
+
+__all__ = ["Read"]
+
+
+class Read(Command):
+    """Write the bytes of a path or URI to standard output, in chunks."""
+
+    _parsername_ = "read"
+
+    path: str
+    "The file or URI to read; - reads standard input. Required"
+    ("path",)
+
+    def __call__(self) -> int:
+        copy_stream(source_of(self.path), stdout())
+        return 0

uripath/cli/rm.py

@@ -0,0 +1,38 @@
+"""`uripath rm`: remove a path."""
+
+from __future__ import annotations
+
+from .. import as_path
+from ._common import Command
+
+__all__ = ["Rm"]
+
+
+class Rm(Command):
+    """Remove a file, an empty directory or a URI; with --recursive, a directory and everything in it."""
+
+    _parsername_ = "rm"
+
+    path: str
+    "The file, empty directory or URI to remove. Required"
+    ("path",)
+
+    recursive: bool = False
+    "Remove a directory with everything in it. Omitted: a directory must be empty"
+    ("--recursive", "-r")
+
+    missing_ok: bool = False
+    "Succeed when the path does not exist. Omitted: a missing path fails"
+    ("--missing-ok",)
+
+    ignore_error: bool = False
+    "Keep removing after a failure. Omitted: stop at the first"
+    ("--ignore-error",)
+
+    def __call__(self) -> int:
+        as_path(self.path).rm(
+            recursive=self.recursive,
+            missing_ok=self.missing_ok,
+            ignore_error=self.ignore_error,
+        )
+        return 0

uripath/cli/sync.py

@@ -0,0 +1,78 @@
+"""`uripath sync`: make a target tree match a source tree."""
+
+from __future__ import annotations
+
+import io as _io
+
+from pathapi.sync import PathSyncer, SyncEvent
+
+from .. import as_path, copy_stream
+from ._common import Command, stdout
+
+__all__ = ["Sync"]
+
+
+_ACTIONS = {
+    SyncEvent.Copy: "copy",
+    SyncEvent.RemovedMissing: "remove",
+    SyncEvent.CreatedDirectory: "mkdir",
+    SyncEvent.TypeMismatch: "replace",
+    SyncEvent.Symlink: "symlink",
+}
+
+
+class Sync(Command):
+    """Make TARGET match SOURCE, comparing file content; nothing is deleted unless --remove-missing."""
+
+    _parsername_ = "sync"
+
+    source: str
+    "The directory or URI to copy from. Required"
+    ("source",)
+
+    target: str
+    "The directory or URI to make match SOURCE. Required"
+    ("target",)
+
+    dry_run: bool = False
+    "Print what would change without changing anything. Omitted: make the changes"
+    ("--dry-run",)
+
+    remove_missing: bool = False
+    "Delete the entries of TARGET that SOURCE does not have. Omitted: keep them"
+    ("--remove-missing",)
+
+    size_only: bool = False
+    "Compare file sizes only, which misses same-size edits. Omitted: compare content"
+    ("--size-only",)
+
+    follow_symlinks: bool = True
+    "Copy what a symbolic link points to. With --no-follow-symlinks: recreate the link"
+    ("--follow-symlinks",)
+
+    follow_mounts: bool = True
+    "Sync into a mount point inside TARGET. With --no-follow-mounts: fail on one"
+    ("--follow-mounts",)
+
+    def __call__(self) -> int:
+        PathSyncer(
+            (lambda entry: entry.stat.st_size) if self.size_only else None,
+            remove_missing=self.remove_missing,
+            follow_symlinks=self.follow_symlinks,
+            follow_mounts=self.follow_mounts,
+            hook=self._report,
+        ).sync(as_path(self.source), as_path(self.target), dry_run=self.dry_run)
+        return 0
+
+    def _report(self, source, target, event, dry_run) -> None:
+        """Print one line for a change: a planned one under --dry-run, a made one under -v."""
+        action = _ACTIONS.get(event)
+        if action is None or not (dry_run or self.wants_detail):
+            return
+        prefix = "would " if dry_run else ""
+        if event is SyncEvent.Copy:
+            line = f"{prefix}{action} {source.path} -> {target.path}"
+        else:
+            line = f"{prefix}{action} {target.path}"
+        text = line.encode("utf-8", "backslashreplace") + b"\n"
+        copy_stream(_io.BytesIO(text), stdout())

uripath/cli/write.py

@@ -0,0 +1,49 @@
+"""`uripath write`: standard input, or the text given, into a path."""
+
+from __future__ import annotations
+
+import io as _io
+import typing as _ty
+
+from duho import Arg, Meta
+
+from .. import as_path, copy_stream
+from ._common import Command, stdin, stdout, target_of
+
+__all__ = ["Write"]
+
+
+def _encoding(name: str) -> str:
+    """A text encoding the interpreter knows (not a bytes-to-bytes codec)."""
+    try:
+        "".encode(name)
+    except LookupError:
+        raise ValueError(f"unknown text encoding: {name!r}") from None
+    return name
+
+
+class Write(Command):
+    """Write standard input, or the text DATA, to a path or URI, replacing what is there."""
+
+    _parsername_ = "write"
+
+    path: str
+    "The file or URI to write, replacing it; - writes standard output. Required"
+    ("path",)
+
+    data: _ty.Optional[str] = None
+    "The text to write, encoded with --encoding. Omitted: the bytes of standard input"
+    ("data",)
+
+    encoding: Arg[str, Meta(type=_encoding)] = "utf-8"
+    "The text encoding of DATA"
+    ("--encoding",)
+
+    def __call__(self) -> int:
+        if self.data is None:
+            copy_stream(stdin(), target_of(self.path))
+        elif self.path == "-":
+            copy_stream(_io.BytesIO(self.data.encode(self.encoding)), stdout())
+        else:
+            as_path(self.path).write_bytes(self.data.encode(self.encoding))
+        return 0

uripath/exceptions.py

@@ -0,0 +1,38 @@
+"""The exceptions of uripath.
+
+`URIPathError` is the base of what goes wrong at run time. A caller's bad
+argument is a plain `ValueError` or `TypeError`, and a failed read or write
+is the `OSError` of the kind `pathlib` raises.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "OutputClosedError",
+    "URIPathError",
+    "URISyntaxError",
+    "UnsupportedSchemeError",
+]
+
+
+class URIPathError(Exception):
+    """The base of the errors uripath raises."""
+
+
+class URISyntaxError(URIPathError, ValueError):
+    """Text that is not a URI, or not the part of one that was asked for: a port
+    that is not 0-65535, a malformed host, a `zip:` URI without the scheme of
+    its archive. The message names what is wrong and never the text, which can
+    carry a password."""
+
+
+class UnsupportedSchemeError(URIPathError, ValueError):
+    """A scheme that no class registered. The message lists the registered
+    ones."""
+
+
+class OutputClosedError(URIPathError, BrokenPipeError):
+    """The reader of a stream that `copy_stream()` was writing went away: a
+    pipe whose other end closed (`uripath read big | head`). It is raised for
+    a stream passed as the target, never for a failure on a path's own
+    connection."""

uripath/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.