kisstdlib 0.0.9__tar.gz → 0.0.10__tar.gz

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kisstdlib
-Version: 0.0.9
+Version: 0.0.10
 Summary: System programming with conceptually and algebraically simple primitives.
 Author-email: Jan Malakhovski <oxij@oxij.org>
 Project-URL: Homepage, https://oxij.org/software/kisstdlib/

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/kisstdlib/__init__.py

@@ -36,11 +36,15 @@ from .io.stdio import *
 from .logging_ext import *
 from .signal_ext import *
 
+from .fs import setup_fs as _setup_fs
+
 
 def setup_kisstdlib(
     prog: str | None = None,
+    *,
     do_setup_stdio: bool = True,
-    signals: list[str] | None = None,
+    do_setup_delay_signals: bool = True,
+    do_setup_fs: bool = True,
     **kwargs: _t.Any,
 ) -> tuple[LogCounter, ANSILogHandler]:
     """Run all `setup_*` functions of all other `kisstdlib.*` modules and setup
@@ -50,9 +54,12 @@ def setup_kisstdlib(
         prog = _op.basename(_sys.argv[0])
     if do_setup_stdio:
         setup_stdio()
-    res = setup_logging(prog, **kwargs)
     setup_delay_signal_messages(prog + ": ")
-    setup_delay_signals(signals)
+    if do_setup_delay_signals:
+        setup_delay_signals()
+    if do_setup_fs:
+        _setup_fs(prog)
+    res = setup_logging(prog, **kwargs)
     return res
 
 
@@ -102,9 +109,18 @@ def run_kisstdlib_main(
         for be in flat_exceptions(excs):
             critical(gettext("Uncaught exception: %s"), str(be), exc_info=be)
 
-    logger.flush()
-    stdout.flush()
-    stderr.flush()
+    try:
+        logger.flush()
+    except BrokenPipeError:
+        pass
+    try:
+        stdout.flush()
+    except BrokenPipeError:
+        pass
+    try:
+        stderr.flush()
+    except BrokenPipeError:
+        pass
 
     num_warnings = counter.warnings
     num_errors = counter.errors

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/kisstdlib/argparse_ext.py

@@ -159,16 +159,16 @@ class MarkdownBetterHelpFormatter(BetterHelpFormatter):
             return join(["\n", heading, item_help, "\n"])
 
 
-class OptionallyMarkdownHelpAction(Action):
+class _OptionallyMarkdownHelpAction(Action):
     def __init__(
         self,
         option_strings: list[str],
         dest: str = SUPPRESS,
         default: _t.Any = SUPPRESS,
-        help: str | None = None,  # pylint: disable=redefined-builtin
+        **kwargs: _t.Any,
     ) -> None:
         super().__init__(
-            option_strings=option_strings, dest=dest, default=default, nargs=0, help=help
+            option_strings=option_strings, dest=dest, default=default, nargs=0, **kwargs
         )
 
     def show_help(self, parser: "BetterArgumentParser", namespace: Namespace) -> None:
@@ -194,6 +194,38 @@ class OptionallyMarkdownHelpAction(Action):
         parser.post_parse_args = self.show_help
 
 
+class _StoreMapAction(Action):
+    def __init__(self, func: _t.Callable[[_t.Any], _t.Any] = _identity, **kwargs: _t.Any) -> None:
+        super().__init__(**kwargs)
+        self.func = func
+
+    def __call__(
+        self,
+        parser: _t.Any,
+        namespace: Namespace,
+        values: _t.Any,
+        option_string: str | None = None,
+    ) -> None:
+        setattr(namespace, self.dest, self.func(values))
+
+
+class _AppendMapAction(Action):
+    def __init__(self, func: _t.Callable[[_t.Any], _t.Any] = _identity, **kwargs: _t.Any) -> None:
+        super().__init__(default=[], **kwargs)
+        self.func = func
+
+    def __call__(
+        self,
+        parser: _t.Any,
+        namespace: Namespace,
+        values: _t.Any,
+        option_string: str | None = None,
+    ) -> None:
+        v = getattr(namespace, self.dest)
+        v.append(self.func(values))
+        setattr(namespace, self.dest, v)
+
+
 class BetterArgumentParser(ArgumentParser):
     """Like `argparse.ArgumentParser`, but uses `BetterHelpFormatter` by default,
     and implements `format_help` that recurses into subcommands and appends
@@ -225,6 +257,10 @@ class BetterArgumentParser(ArgumentParser):
             **kwargs,
         )
 
+        self.register("action", "store_map", _StoreMapAction)
+        self.register("action", "append_map", _AppendMapAction)
+        self.register("action", "help_omd", _OptionallyMarkdownHelpAction)
+
         self.add_version = add_version
         self.add_help = add_help
         self.additional_sections = additional_sections
@@ -249,12 +285,10 @@ class BetterArgumentParser(ArgumentParser):
             )
 
         if add_help:
-            self.register("action", "help", OptionallyMarkdownHelpAction)
-
             self.add_argument(
                 default_prefix + "h",
                 default_prefix * 2 + "help",
-                action="help",
+                action="help_omd",
                 default=SUPPRESS,
                 help=_gettext("show this help message and exit"),
             )

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/kisstdlib/base.py

@@ -30,6 +30,7 @@ import traceback as _traceback
 import typing as _t
 
 from decimal import Decimal
+from functools import partial, partialmethod  # pylint: disable=unused-import
 
 
 ### Primitive types

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/kisstdlib/fs.py

@@ -36,41 +36,29 @@ import stat as _stat
 import sys as _sys
 import typing as _t
 
+from os import fsencode, fsdecode
+
 from .base import POSIX as _POSIX, identity as _identity
-from .string_ext import escaper as _escaper
 from .io.base import *
+from .string_ext import escape_path as _escape_path
 from .time import Timestamp as _Timestamp
 
 sep = _op.sep
 sepb = _os.fsencode(_op.sep)
 
 
-def fsdecode_maybe(x: str | bytes) -> str:
-    """Apply `os.fsdecode` if `bytes`."""
-    if isinstance(x, bytes):
-        return _os.fsdecode(x)
-    return x
-
-
-def fsencode_maybe(x: str | bytes) -> bytes:
-    """Apply `os.fsencode` if `str`."""
-    if isinstance(x, str):
-        return _os.fsencode(x)
-    return x
-
-
-def dirname_dot(x: _t.AnyStr) -> tuple[_t.AnyStr, bool]:
+def dirname_dot(path: _t.AnyStr) -> tuple[_t.AnyStr, bool]:
     """Apply `os.path.dirname` to the given argument, but if it's empty, return "." instead.
     The second element of the tuple is `False` if the above replacement was performed, `True` otherwise.
     """
-    x = _os.path.dirname(x)
-    if isinstance(x, bytes):
-        if x == b"":
+    path = _os.path.dirname(path)
+    if isinstance(path, bytes):
+        if path == b"":
             return b".", False
-        return x, True
-    if x == "":
+        return path, True
+    if path == "":
         return ".", False
-    return x, True
+    return path, True
 
 
 def read_file_maybe(path: str | bytes) -> bytes | None:
@@ -100,8 +88,8 @@ def same_file_data(path1: str | bytes, path2: str | bytes) -> bool:
 
 def same_symlink_data(path1: str | bytes, path2: str | bytes) -> bool:
     """Check if two given symlinks have exactly the same content."""
-    a = _os.readlink(fsencode_maybe(path1))
-    b = _os.readlink(fsencode_maybe(path2))
+    a = _os.readlink(fsencode(path1))
+    b = _os.readlink(fsencode(path2))
     return a == b
 
 
@@ -206,7 +194,7 @@ def iter_subtree(
             if handle_error is not None:
                 eno = exc.errno
                 handle_error(
-                    "failed to stat `%s`: [Errno %d, %s] %s: %s",
+                    "failed to `stat`: [Errno %d, %s] %s: %s",
                     eno,
                     _errno.errorcode.get(eno, "?"),
                     _os.strerror(eno),
@@ -410,12 +398,12 @@ def describe_forest(
     """Produce a simple `find .`+`stat`-like description of walks of given `paths`.
     See `describe-forest` script for more info.
     """
-    escape: _t.Callable[[str], str] = _identity if literal else _escaper("\\").escape  # type: ignore
+    escape: _t.Callable[[str], str] = _identity if literal else _escape_path  # type: ignore
     seen: dict[tuple[int, int], tuple[_t.AnyStr, int, str]] = {}
     for i, dirpath in enumerate(paths):
         for fpath, _eps, _edir in iter_subtree(dirpath, follow_symlinks=follow_symlinks):
             abs_path = _op.abspath(fpath)
-            rpath = fsdecode_maybe(_op.relpath(fpath, dirpath))
+            rpath = fsdecode(_op.relpath(fpath, dirpath))
             epath: str
             if numbers is False or numbers is None and len(paths) == 1:
                 epath = escape(rpath)
@@ -434,7 +422,7 @@ def describe_forest(
                 if relative_hardlinks and hi == i:
                     # within the same `dirpath`
                     dirname = _op.dirname(abs_path)
-                    target = escape(fsdecode_maybe(_op.relpath(habs_path, dirname)))
+                    target = escape(fsdecode(_op.relpath(habs_path, dirname)))
                     yield [epath, "ref", "=>", target]
                 else:
                     yield [epath, "ref", "==>", hepath]
@@ -464,7 +452,7 @@ def describe_forest(
                     sha256 = sha256[:hash_length]
                 yield [epath, "reg"] + emode + emtime + esize + ["sha256", sha256]  # fmt: skip
             elif _stat.S_ISLNK(stat.st_mode):
-                esymlink = escape(fsdecode_maybe(_os.readlink(abs_path)))
+                esymlink = escape(fsdecode(_os.readlink(abs_path)))
                 yield [epath, "sym"] + emode + emtime + ["->", esymlink]
             else:
                 yield [epath, "???"] + emode + emtime + esize
@@ -588,6 +576,7 @@ class DeferredSync(_t.Generic[_t.AnyStr]):
     Doing this can improve disk performance considerably.
     """
 
+    defer: bool
     tmp_file: set[_t.AnyStr]
     unlink_file: set[_t.AnyStr]
     fsync_file: set[_t.AnyStr]
@@ -598,7 +587,8 @@ class DeferredSync(_t.Generic[_t.AnyStr]):
     # if all of the above succeed, also do these
     _after: _t.Optional["DeferredSync[_t.AnyStr]"]
 
-    def __init__(self) -> None:
+    def __init__(self, defer: bool) -> None:
+        self.defer = defer
         self.reset()
 
     def reset(self) -> None:
@@ -628,14 +618,14 @@ after="""
     @property
     def after(self) -> "DeferredSync[_t.AnyStr]":
         if self._after is None:
-            self._after = DeferredSync()
+            self._after = DeferredSync(self.defer)
         return self._after
 
     def copy(self) -> "DeferredSync[_t.AnyStr]":
         """Return a shallow copy of this object (elements describing operations are not
         copied, only the structure is).
         """
-        res: DeferredSync[_t.AnyStr] = DeferredSync()
+        res: DeferredSync[_t.AnyStr] = DeferredSync(self.defer)
         res.tmp_file = set(self.tmp_file)
         res.unlink_file = set(self.unlink_file)
         res.fsync_file = set(self.fsync_file)
@@ -654,20 +644,18 @@ after="""
             unlink_many(self.tmp_file)
         self.reset()
 
-    def commit(
-        self, strict: bool = True, simulate: list[list[str]] | None = None
-    ) -> list[Exception]:
+    def sync(self, strict: bool = True, simulate: list[list[str]] | None = None) -> list[Exception]:
         """Perform all deferred operations and return a list of raised exceptions.
 
         Operations that fail will be left sitting in the corresponding fields.
 
         With `simulate` argument set, this function instead simulates the
-        `commit` and writes the log of things it would do into that argument.
+        `sync` and writes the log of things it would do into that argument.
         """
         exceptions: list[Exception] = []
 
         if simulate is not None:
-            simulate += [["unlink", fsdecode_maybe(f)] for f in sorted(self.unlink_file)]
+            simulate += [["unlink", fsdecode(f)] for f in sorted(self.unlink_file)]
             self.unlink_file = set()
         elif self.unlink_file:
             self.unlink_file = set(unlink_many(sorted(self.unlink_file), exceptions))
@@ -689,7 +677,7 @@ after="""
 
         while self.fsync_file or self.fsync_dir or self.fsync_dir2 or self.rename_file:
             if simulate is not None:
-                simulate += [["fsync", fsdecode_maybe(f)] for f in sorted(self.fsync_file)]
+                simulate += [["fsync", fsdecode(f)] for f in sorted(self.fsync_file)]
                 self.fsync_file = set()
             elif self.fsync_file:
                 fsync_file_left.update(fsync_many_files(sorted(self.fsync_file), 0, exceptions))
@@ -723,7 +711,7 @@ after="""
 
                     try:
                         if simulate is not None:
-                            simulate.append(["replace" if allow_overwrites else "rename", fsdecode_maybe(src_path), fsdecode_maybe(dst_path)])  # fmt: skip
+                            simulate.append(["replace" if allow_overwrites else "rename", fsdecode(src_path), fsdecode(dst_path)])  # fmt: skip
                         else:
                             rename(src_path, dst_path, allow_overwrites, makedirs=False, dst_dir=dst_dir)  # fmt: skip
                     except Exception as exc:
@@ -751,14 +739,14 @@ after="""
                         return exceptions
 
             if simulate is not None:
-                simulate += [["fsync_win", fsdecode_maybe(f)] for f in sorted(self.fsync_file)]
+                simulate += [["fsync_win", fsdecode(f)] for f in sorted(self.fsync_file)]
                 self.fsync_file = set()
             elif self.fsync_file:
                 fsync_file_left.update(fsync_many_files(sorted(self.fsync_file), 0, exceptions))
                 self.fsync_file = set()
 
             if simulate is not None:
-                simulate += [["fsync_dir", fsdecode_maybe(f)] for f in sorted(self.fsync_dir)]
+                simulate += [["fsync_dir", fsdecode(f)] for f in sorted(self.fsync_dir)]
                 self.fsync_dir = set()
             elif self.fsync_dir:
                 if _POSIX:
@@ -766,7 +754,7 @@ after="""
                 self.fsync_dir = set()
 
             if simulate is not None:
-                simulate += [["fsync_dir", fsdecode_maybe(f)] for f in sorted(self.fsync_dir2)]
+                simulate += [["fsync_dir", fsdecode(f)] for f in sorted(self.fsync_dir2)]
                 self.fsync_dir2 = set()
             elif self.fsync_dir2:
                 if _POSIX:
@@ -785,7 +773,7 @@ after="""
             return exceptions
 
         if self._after is not None:
-            excs = self._after.commit(strict, simulate)
+            excs = self._after.sync(strict, simulate)
             if len(excs) > 0:
                 exceptions += excs
             else:
@@ -793,12 +781,12 @@ after="""
 
         return exceptions
 
-    def finish(self, strict: bool = True) -> None:
-        """Like `commit` but raises collected exceptions as an exception group and calls
+    def flush(self, strict: bool = True) -> None:
+        """Like `sync` but raises collected exceptions as an exception group and calls
         `.clear` in that case.
         """
         try:
-            excs = self.commit(strict)
+            excs = self.sync(strict)
             if len(excs) > 0:
                 raise ExceptionGroup("failed to sync", excs)
         finally:
@@ -811,7 +799,7 @@ def atomic_rename(
     allow_overwrites: bool,
     *,
     makedirs: bool = True,
-    dsync: DeferredSync[_t.AnyStr] | None = None,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
 ) -> None:
     """Atomically rename a file, performing all necesary `fsync`s."""
 
@@ -821,19 +809,24 @@ def atomic_rename(
     if makedirs and nondot:
         _os.makedirs(dst_dir, exist_ok=True)
 
-    if dsync is not None:
-        dsync.rename_file.append((src_path, dst_path, allow_overwrites, src_dir, dst_dir))
+    if isinstance(sync, DeferredSync) and sync.defer:
+        sync.rename_file.append((src_path, dst_path, allow_overwrites, src_dir, dst_dir))
         return
 
     rename(src_path, dst_path, allow_overwrites, makedirs=False, dst_dir=dst_dir)
 
-    if _POSIX:
-        fsync_file(dst_dir, _os.O_DIRECTORY)
-        if src_dir != dst_dir:
-            fsync_file(src_dir, _os.O_DIRECTORY)
-    else:
-        # on Windows, some docs claim, this helps
-        fsync_file(dst_path)
+    if isinstance(sync, DeferredSync):
+        sync.fsync_dir.add(dst_dir)
+        return
+
+    if sync:
+        if _POSIX:
+            fsync_file(dst_dir, _os.O_DIRECTORY)
+            if src_dir != dst_dir:
+                fsync_file(src_dir, _os.O_DIRECTORY)
+        else:
+            # on Windows, some docs claim, this helps
+            fsync_file(dst_path)
 
 
 def make_file(
@@ -842,7 +835,7 @@ def make_file(
     allow_overwrites: bool = False,
     *,
     makedirs: bool = True,
-    dsync: DeferredSync[_t.AnyStr] | None = None,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
 ) -> None:
     """Create a file using a given `make_dst` function."""
 
@@ -854,24 +847,28 @@ def make_file(
 
     if makedirs and nondot:
         _os.makedirs(dst_dir, exist_ok=True)
-    make_dst(dst_path, dsync is None)
+    make_dst(dst_path, isinstance(sync, bool))
 
-    if dsync is not None:
-        dsync.fsync_file.add(dst_path)
-        dsync.fsync_dir.add(dst_dir)
+    if isinstance(sync, DeferredSync):
+        sync.fsync_file.add(dst_path)
+        sync.fsync_dir.add(dst_dir)
         return
 
-    if _POSIX:
+    if sync and _POSIX:
         fsync_file(dst_dir, _os.O_DIRECTORY)
 
 
+_dot_part = ".part"
+_dot_partb = b".part"
+
+
 def atomic_make_file(
     make_dst: _t.Callable[[_t.AnyStr, bool], None],
     dst_path: _t.AnyStr,
     allow_overwrites: bool = False,
     *,
     makedirs: bool = True,
-    dsync: DeferredSync[_t.AnyStr] | None = None,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
 ) -> None:
     """Atomically create a file using a given `make_dst` function. This
     runs `make_dst` on a `.part` path first, `fsync`s it, then does
@@ -885,29 +882,35 @@ def atomic_make_file(
         raise FileExistsError(_errno.EEXIST, _os.strerror(_errno.EEXIST), dst_path)
 
     if isinstance(dst_path, str):
-        tmp_path = dst_path + ".part"
+        tmp_path = dst_path + _dot_part
     else:
-        tmp_path = dst_path + b".part"
+        tmp_path = dst_path + _dot_partb
 
     dst_dir, nondot = dirname_dot(dst_path)
 
     if makedirs and nondot:
         _os.makedirs(dst_dir, exist_ok=True)
-    make_dst(tmp_path, dsync is None)
+    make_dst(tmp_path, isinstance(sync, bool) and sync)
 
-    if dsync is not None:
-        dsync.tmp_file.add(tmp_path)
-        dsync.fsync_file.add(tmp_path)
-        dsync.rename_file.append((tmp_path, dst_path, allow_overwrites, dst_dir, dst_dir))
+    if isinstance(sync, DeferredSync) and sync.defer:
+        sync.tmp_file.add(tmp_path)
+        sync.fsync_file.add(tmp_path)
+        sync.rename_file.append((tmp_path, dst_path, allow_overwrites, dst_dir, dst_dir))
         return
 
     try:
+        if sync:
+            fsync_file(tmp_path)
         rename(tmp_path, dst_path, allow_overwrites, dst_dir=dst_dir)
     except Exception:
         unlink_maybe(tmp_path)
         raise
 
-    if _POSIX:
+    if isinstance(sync, DeferredSync):
+        sync.fsync_dir.add(dst_dir)
+        return
+
+    if sync and _POSIX:
         fsync_file(dst_dir, _os.O_DIRECTORY)
         # NB: src_dir == dst_dir
 
@@ -919,7 +922,7 @@ def atomic_copy2(
     *,
     follow_symlinks: bool = True,
     makedirs: bool = True,
-    dsync: DeferredSync[_t.AnyStr] | None = None,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
 ) -> None:
     """Atomically copy `src_path` to `dst_path`."""
 
@@ -942,7 +945,7 @@ def atomic_copy2(
 
     # always use the atomic version here, like rsync does,
     # since copying can be interrupted in the middle
-    atomic_make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, dsync=dsync)
+    atomic_make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, sync=sync)
 
 
 def atomic_link(
@@ -952,7 +955,7 @@ def atomic_link(
     *,
     follow_symlinks: bool = True,
     makedirs: bool = True,
-    dsync: DeferredSync[_t.AnyStr] | None = None,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
 ) -> None:
     """Atomically hardlink `src_path` to `dst_path`."""
 
@@ -963,10 +966,10 @@ def atomic_link(
         _os.link(src_path, dst_path, follow_symlinks=follow_symlinks)
 
     # _os.link is atomic, so non-atomic make_file is ok
-    if allow_overwrites:
-        atomic_make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, dsync=dsync)
+    if allow_overwrites or (isinstance(sync, DeferredSync) and sync.defer):
+        atomic_make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, sync=sync)
     else:
-        make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, dsync=dsync)
+        make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, sync=sync)
 
 
 def atomic_symlink(
@@ -976,7 +979,7 @@ def atomic_symlink(
     *,
     follow_symlinks: bool = True,
     makedirs: bool = True,
-    dsync: DeferredSync[_t.AnyStr] | None = None,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
 ) -> None:
     """Atomically symlink `src_path` to `dst_path`."""
 
@@ -987,10 +990,10 @@ def atomic_symlink(
         _os.symlink(src_path, dst_path)
 
     # _os.symlink is atomic, so non-atomic make_file is ok
-    if allow_overwrites:
-        atomic_make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, dsync=dsync)
+    if allow_overwrites or (isinstance(sync, DeferredSync) and sync.defer):
+        atomic_make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, sync=sync)
     else:
-        make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, dsync=dsync)
+        make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, sync=sync)
 
 
 def atomic_link_or_copy2(
@@ -1000,16 +1003,16 @@ def atomic_link_or_copy2(
     *,
     follow_symlinks: bool = True,
     makedirs: bool = True,
-    dsync: DeferredSync[_t.AnyStr] | None = None,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
 ) -> None:
     """Atomically hardlink or copy `src_path` to `dst_path`."""
 
     try:
-        atomic_link(src_path, dst_path, allow_overwrites, follow_symlinks=follow_symlinks, makedirs=makedirs, dsync=dsync)  # fmt: skip
+        atomic_link(src_path, dst_path, allow_overwrites, follow_symlinks=follow_symlinks, makedirs=makedirs, sync=sync)  # fmt: skip
     except OSError as exc:
         if exc.errno != _errno.EXDEV:
             raise
-        atomic_copy2(src_path, dst_path, allow_overwrites, follow_symlinks=follow_symlinks, makedirs=makedirs, dsync=dsync)  # fmt: skip
+        atomic_copy2(src_path, dst_path, allow_overwrites, follow_symlinks=follow_symlinks, makedirs=makedirs, sync=sync)  # fmt: skip
 
 
 def atomic_move(
@@ -1019,7 +1022,7 @@ def atomic_move(
     *,
     follow_symlinks: bool = False,
     makedirs: bool = True,
-    dsync: DeferredSync[_t.AnyStr] | None = None,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
 ) -> None:
     """Atomically move `src_path` to `dst_path`.
 
@@ -1029,17 +1032,17 @@ def atomic_move(
 
     src_dir, _ = dirname_dot(src_path)
 
-    atomic_link_or_copy2(src_path, dst_path, allow_overwrites, follow_symlinks=follow_symlinks, makedirs=makedirs, dsync=dsync)  # fmt: skip
+    atomic_link_or_copy2(src_path, dst_path, allow_overwrites, follow_symlinks=follow_symlinks, makedirs=makedirs, sync=sync)  # fmt: skip
 
-    if dsync is not None:
-        after = dsync.after
+    if isinstance(sync, DeferredSync):
+        after = sync.after
         after.unlink_file.add(src_path)
         after.fsync_dir.add(src_dir)
         return
 
     _os.unlink(src_path)
 
-    if _POSIX:
+    if sync and _POSIX:
         fsync_file(src_dir, _os.O_DIRECTORY)
 
 
@@ -1049,7 +1052,7 @@ def atomic_write(
     allow_overwrites: bool = False,
     *,
     makedirs: bool = True,
-    dsync: DeferredSync[_t.AnyStr] | None = None,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
 ) -> None:
     """Atomically write given `data` to `dst_path`."""
 
@@ -1064,4 +1067,39 @@ def atomic_write(
             unlink_maybe(tmp_path)
             raise
 
-    atomic_make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, dsync=dsync)
+    atomic_make_file(make_dst, dst_path, allow_overwrites, makedirs=makedirs, sync=sync)
+
+
+def atomic_unlink(
+    path: _t.AnyStr,
+    *,
+    sync: DeferredSync[_t.AnyStr] | bool = True,
+) -> None:
+    """Atomically unlink `path`."""
+
+    dirname, _ = dirname_dot(path)
+
+    if isinstance(sync, DeferredSync) and sync.defer:
+        sync.unlink_file.add(path)
+        sync.fsync_dir.add(dirname)
+        return
+
+    _os.unlink(path)
+
+    if isinstance(sync, DeferredSync):
+        sync.fsync_dir.add(dirname)
+        return
+
+    if sync and _POSIX:
+        fsync_file(dirname, _os.O_DIRECTORY)
+
+
+def setup_fs(prog: str | None = None, ext: str = ".part", add_pid: bool = True) -> None:
+    """Setup temporary files prefix."""
+    if prog is None:
+        prog = _op.basename(_sys.argv[0])
+
+    global _dot_part, _dot_partb
+    pid = f"_{_os.getpid()}" if add_pid else ""
+    _dot_part = f".{prog}{pid}{ext}"
+    _dot_partb = _dot_part.encode("ascii")

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/kisstdlib/io/stdio.py

@@ -78,7 +78,6 @@ def printf(
     Colors get applied to `prefix`, rendered `pattern`, and `suffix`, but not to
     `indent` and `end`, so that, e.g., `printf(..., indent=" " * 4`,
     background=1)` produces an indented background-colored block.
-
     """
     if file is None:
         file = stdout
@@ -93,25 +92,29 @@ def printf(
         end = file.eol
 
     data = pattern % args
+    extra = len(prefix) + len(indent) + len(suffix)
 
     lines = 0
+    implicit_eol = False
     if start:
         file.write(start)
         lines += _numlines(start)
     for line in data.splitlines(True):
-        w = len(indent) + len(prefix) + len(line) + len(suffix)
+        w = len(line) + extra
         if indent:
             file.write(indent)
             lines += _numlines(indent)
         if line[-1:] in ("\n", b"\n"):
             file.write_ln(prefix + line[:-1] + suffix, **kwargs)
-            lines += 1 + (w - 1) // width
+            lines += 1
+            w -= 1
         else:
             file.write(prefix + line + suffix, **kwargs)
-            lines += w // width
+        lines += w // width
+        implicit_eol = w > 0 and w % width == 0
     if end:
         file.write(end)
-        lines += _numlines(end)
+        lines += max(0, _numlines(end) - 1) if implicit_eol else _numlines(end)
     if flush is True or flush is None and file.isatty():
         file.flush()
     return lines

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/kisstdlib/logging_ext.py

@@ -153,16 +153,12 @@ class ANSILogHandler(_logging.StreamHandler[_TIOWrappedWriter]):
         After a `reset` with default arguments:
 
         - If next `emit`s repeat the previous message, these repeats will will
-          be counted separately from the previous message.
+          be counted separately.
 
         - If the last message was both ephemeral and printed, it will simply
           become pesistent.
 
         - Next `update` timeout for new ephemeral messages will be reset.
-
-        Unless you want to commit the last ephemeral message to view (which can
-        be done with `update` followed by `reset`), you should use `flush`
-        instead.
         """
         self.last = new
         self.repeats = repeats
@@ -240,30 +236,27 @@ class ANSILogHandler(_logging.StreamHandler[_TIOWrappedWriter]):
                 stream.flush()
             self.repeats_printed = True
 
-    def rollback(self) -> None:
-        """Remove the last printed message from view, but not forget it, i.e. the next
-        `update` will re-print it again, if no `emit`s were done in the
-        meantime.
-        """
-        self._rollback()
-        self.stream.flush()
-        self.reset(self.last, self.repeats)
-
     def flush(self) -> None:
         """Remove any ephemeral state from view and/or commit non-ephemeral state to
         view.
 
-        I.e., if the last message was ephemeral, remove it from view and `reset`.
-        Otherwise, `update` and `reset`.
+        I.e., if the last message was not ephemeral, `update` and `reset`.
+
+        Otherwise, remove the last message from view, but don't forget about it,
+        allowing it to be re-printed with `update`.
+
+        If you want to commit the last ephemeral message to view, do `update`
+        and `reset` manually.
         """
         last = self.last
         if last is not None and last[0]:
             # ephemeral
             self._rollback()
             self.stream.flush()
+            self.reset(self.last, self.repeats)
         else:
             self.update()
-        self.reset()
+            self.reset()
 
     def emit(self, record: _logging.LogRecord) -> None:
         """`logging.Handler` implementation."""

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/kisstdlib/signal_ext.py

@@ -65,12 +65,19 @@ class SignalInterrupt(BaseException):
     # signal number
     signum: int
     # was this signal raised forcefully?
-    forced: bool
+    forced: bool = _dc.field(default=True)
 
     def __post_init__(self) -> None:
         BaseException.__init__(self)
 
 
+class GentleSignalInterrupt(SignalInterrupt):
+    """Unforced `SignalInterrupt`."""
+
+    def __init__(self, signum: int) -> None:
+        super().__init__(signum, False)
+
+
 delay_signal_message: dict[int, str] = {}
 delay_signal_message_default = "Interrupting, gently."
 
@@ -119,7 +126,7 @@ def delay_signal_handler(signum: int, _frame: _t.Any) -> None:
     `yes_signals` block.
     """
 
-    _delayed_signals[signum] = num = _delayed_signals.get(signum, 0) + 1
+    num = _delayed_signals.get(signum, 0) + 1
 
     enabled, verbose = _delay_signals_state
     if isinstance(verbose, str):
@@ -134,7 +141,13 @@ def delay_signal_handler(signum: int, _frame: _t.Any) -> None:
                 start="\n",
                 color=1,
             )
-        raise SignalInterrupt(signum, True)
+        try:
+            del _delayed_signals[signum]
+        except KeyError:
+            pass
+        raise SignalInterrupt(signum)
+
+    _delayed_signals[signum] = num
 
     if verbose:
         _printf_err(
@@ -198,19 +211,20 @@ def pop_delayed_signal() -> int | None:
 
 
 def raise_first_delayed_signal() -> None:
-    """Raise `SignalInterrupt(signum, False)` with the first `signum` delayed by
+    """Raise `GentleSignalInterrupt(signum)` with the first `signum` delayed by
     `delay_signal_handler`, do nothing if no signals bound to
     `delay_signal_handler` were recieved.
 
     This function can be called repeatedly, in which case it will raise
-    `SignalInterrupt`s for each delayed signal in order they were received.
+    `GentleSignalInterrupt`s for each delayed signal in order they were
+    received.
     """
     try:
         signum, _num = _delayed_signals.popitem(False)
     except KeyError:
         pass
     else:
-        raise SignalInterrupt(signum, False)
+        raise GentleSignalInterrupt(signum)
 
 
 def raise_delayed_signals() -> None:
@@ -220,7 +234,7 @@ def raise_delayed_signals() -> None:
     excs = []
     while len(_delayed_signals) > 0:
         signum, _num = _delayed_signals.popitem(False)
-        excs.append(SignalInterrupt(signum, False))
+        excs.append(GentleSignalInterrupt(signum))
     if len(excs) == 0:
         return
     if len(excs) == 1:
@@ -243,8 +257,8 @@ def no_signals(*, do_raise: bool = True, verbose: bool | str = True) -> _t.Itera
     When `do_raise` is set (which is the default), if this is the topmost
     `no_signals` block, or if the parent block is `yes_signals`, then
     `raise_delayed_signals` will be called right after this block finishes.
-    I.e., any delayed `SignalInterrupt`s will be raised immediately at exit from
-    this block.
+    I.e., any delayed `GentleSignalInterrupt`s will be raised immediately at
+    exit from this block.
 
     You can also `raise` them at certain program points by calling
     `raise_first_delayed_signal` or `raise_delayed_signals` manually from inside
@@ -267,7 +281,7 @@ def no_signals(*, do_raise: bool = True, verbose: bool | str = True) -> _t.Itera
     try:
         yield None
     except Exception:
-        # pretend `SignalInterrupt` was raised first
+        # pretend `GentleSignalInterrupt` was raised first
         if do_raise and old[0]:
             raise_delayed_signals()
         raise
@@ -305,16 +319,18 @@ def soft_sleep(seconds: int | float, *, verbose: bool | str = False) -> None:
     """Start `yes_signals(verbose=verbose)` block, if doing that does not not
     trigger `raise_delayed_signals`, run `time.sleep` with the given argument,
     if the latter gets interrupted with a `SignalInterrupt`, raise
-    `SignalInterrupt` with the same `signum` but with `forced=False`.
+    `GentleSignalInterrupt` with the same `signum` instead.
 
     Note that you should probably use `try ... except*`, not simply `try ...
     except` with this, unless you know what you are doing.
     """
+    # NB: there's no need to handle `BaseExceptionGroup` here since this these
+    # `except` clauses will only be executed right after `delay_signal_handler`
+    # `raise`s.
     try:
         with yes_signals(verbose=verbose):
             sleep(seconds)
+    except GentleSignalInterrupt:
+        raise
     except SignalInterrupt as exc:
-        # NB: there's no need to handle `BaseExceptionGroup` here since this
-        # will only needs to be executed right after `delay_signal_handler`
-        # `raise`s.
-        raise SignalInterrupt(exc.signum, False) from exc
+        raise GentleSignalInterrupt(exc.signum) from exc

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/kisstdlib/string_ext.py

@@ -482,6 +482,13 @@ def unescape(
     )
 
 
+### Path escaping
+
+path_escaper: StringLexer[str] = escaper("\\")
+escape_path = path_escaper.escape
+unescape_path = path_escaper.unescape
+
+
 ### URL-quoting
 
 _safe_url_chars: dict[tuple[str, str], _t.Callable[[int | str], bool]] = {}

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/kisstdlib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kisstdlib
-Version: 0.0.9
+Version: 0.0.10
 Summary: System programming with conceptually and algebraically simple primitives.
 Author-email: Jan Malakhovski <oxij@oxij.org>
 Project-URL: Homepage, https://oxij.org/software/kisstdlib/

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/pyproject.toml

@@ -9,7 +9,7 @@ namespaces = true
 "kisstdlib" = ["py.typed"]
 [project]
 name = "kisstdlib"
-version = "0.0.9"
+version = "0.0.10"
 authors = [{ name = "Jan Malakhovski", email = "oxij@oxij.org" }]
 description = "System programming with conceptually and algebraically simple primitives."
 readme = "README.md"

{kisstdlib-0.0.9 → kisstdlib-0.0.10}/test/test_fs.py

@@ -56,26 +56,26 @@ def test_iter_subtree(tmp_path: str) -> None:
     ]
 
 
-def atomic1(sync: bool, tmp_path: str) -> None:
+def atomic1(defer: bool, tmp_path: str) -> None:
     os.chdir(tmp_path)
 
-    dsync = None
-    if sync:
-        dsync = DeferredSync()
+    sync: DeferredSync[str] | bool = True
+    if defer:
+        sync = DeferredSync(True)
 
     def check(es: list[list[str]], ed: list[list[str]] | None = None) -> None:
-        if dsync is not None:
+        if isinstance(sync, DeferredSync):
             gs: list[list[str]] = []
-            dsync.copy().commit(True, gs)
+            sync.copy().sync(True, gs)
             assert es == gs
 
         if ed is not None:
             gd = list(describe_forest(["."], hash_length=8))
             assert ed == gd
 
-    atomic_write(b"test a", "test.a", dsync=dsync)
-    atomic_write(b"test b", "test.b", dsync=dsync)
-    atomic_write(b"test c", "test.c", dsync=dsync)
+    atomic_write(b"test a", "test.a", sync=sync)
+    atomic_write(b"test b", "test.b", sync=sync)
+    atomic_write(b"test c", "test.c", sync=sync)
     check(
         [
             ["fsync", "test.a.part"],
@@ -90,7 +90,7 @@ def atomic1(sync: bool, tmp_path: str) -> None:
             ["fsync_dir", "."],
         ]
     )
-    atomic_rename("test.a", "a/test.a", False, dsync=dsync)
+    atomic_rename("test.a", "a/test.a", False, sync=sync)
     check(
         [
             ["fsync", "test.a.part"],
@@ -110,7 +110,7 @@ def atomic1(sync: bool, tmp_path: str) -> None:
             ["fsync_dir", "."],
         ]
     )
-    atomic_rename("test.b", "a/test.b", False, dsync=dsync)
+    atomic_rename("test.b", "a/test.b", False, sync=sync)
     check(
         [
             ["fsync", "test.a.part"],
@@ -132,7 +132,7 @@ def atomic1(sync: bool, tmp_path: str) -> None:
             ["fsync_dir", "."],
         ]
     )
-    atomic_rename("test.c", "b/test.c", False, dsync=dsync)
+    atomic_rename("test.c", "b/test.c", False, sync=sync)
     check(
         [
             ["fsync", "test.a.part"],
@@ -157,7 +157,7 @@ def atomic1(sync: bool, tmp_path: str) -> None:
             ["fsync_dir", "."],
         ]
     )
-    atomic_rename("a/test.b", "test.b", False, dsync=dsync)
+    atomic_rename("a/test.b", "test.b", False, sync=sync)
     check(
         [
             ["fsync", "test.a.part"],
@@ -187,8 +187,8 @@ def atomic1(sync: bool, tmp_path: str) -> None:
             ["fsync_dir", "a"],
         ]
     )
-    if dsync is not None:
-        dsync.finish()
+    if isinstance(sync, DeferredSync):
+        sync.flush()
     check(
         [],
         [
@@ -201,8 +201,8 @@ def atomic1(sync: bool, tmp_path: str) -> None:
         ],
     )
 
-    atomic_link("a/test.a", "test.a", True, dsync=dsync)
-    atomic_symlink("b/test.c", "test.c", True, dsync=dsync)
+    atomic_link("a/test.a", "test.a", True, sync=sync)
+    atomic_symlink("b/test.c", "test.c", True, sync=sync)
     check(
         [
             ["fsync", "test.a.part"],
@@ -214,14 +214,14 @@ def atomic1(sync: bool, tmp_path: str) -> None:
             ["fsync_dir", "."],
         ]
     )
-    if dsync is not None:
-        dsync.finish()
+    if isinstance(sync, DeferredSync):
+        sync.flush()
     check([])
 
-    atomic_copy2("test.a", "x/test.a", True, dsync=dsync)
-    atomic_copy2("test.c", "x/test.c", True, dsync=dsync)
-    atomic_link("test.c", "x/test.c.lnk", True, follow_symlinks=False, dsync=dsync)
-    atomic_copy2("test.c", "x/test.c.sym", True, follow_symlinks=False, dsync=dsync)
+    atomic_copy2("test.a", "x/test.a", True, sync=sync)
+    atomic_copy2("test.c", "x/test.c", True, sync=sync)
+    atomic_link("test.c", "x/test.c.lnk", True, follow_symlinks=False, sync=sync)
+    atomic_copy2("test.c", "x/test.c.sym", True, follow_symlinks=False, sync=sync)
     check(
         [
             ["fsync", "x/test.a.part"],
@@ -239,8 +239,8 @@ def atomic1(sync: bool, tmp_path: str) -> None:
             ["fsync_dir", "x"],
         ]
     )
-    if dsync is not None:
-        dsync.finish()
+    if isinstance(sync, DeferredSync):
+        sync.flush()
     check(
         [],
         [
@@ -260,11 +260,11 @@ def atomic1(sync: bool, tmp_path: str) -> None:
         ],
     )
 
-    atomic_copy2("test.a", "y/test.a", True, dsync=dsync)
-    atomic_copy2("test.c", "y/test.c", True, dsync=dsync)
-    atomic_link("test.c", "y/test.c.lnk", True, follow_symlinks=False, dsync=dsync)
-    atomic_copy2("test.c", "y/test.c.sym", True, follow_symlinks=False, dsync=dsync)
-    atomic_move("test.c", "z/test.c", True, dsync=dsync)
+    atomic_copy2("test.a", "y/test.a", True, sync=sync)
+    atomic_copy2("test.c", "y/test.c", True, sync=sync)
+    atomic_link("test.c", "y/test.c.lnk", True, follow_symlinks=False, sync=sync)
+    atomic_copy2("test.c", "y/test.c.sym", True, follow_symlinks=False, sync=sync)
+    atomic_move("test.c", "z/test.c", True, sync=sync)
     check(
         [
             ["fsync", "y/test.a.part"],
@@ -288,8 +288,8 @@ def atomic1(sync: bool, tmp_path: str) -> None:
             ["fsync_dir", "."],
         ]
     )
-    if dsync is not None:
-        dsync.finish()
+    if isinstance(sync, DeferredSync):
+        sync.flush()
     check(
         [],
         [