zstdlib 0.7.0__tar.gz → 0.8.0__tar.gz

{zstdlib-0.7.0 → zstdlib-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zstdlib
-Version: 0.7.0
+Version: 0.8.0
 Summary: A set of useful python utilities
 License: GPLv3
 Project-URL: Homepage, https://github.com/zwimer/zstdlib
@@ -11,6 +11,7 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: osascript2
 Dynamic: license-file
 
 # zstdlib

{zstdlib-0.7.0 → zstdlib-0.8.0}/pyproject.toml

@@ -15,6 +15,9 @@ description = "A set of useful python utilities"
 urls = {Homepage = "https://github.com/zwimer/zstdlib"}
 requires-python = ">= 3.14"
 dynamic = ["version"]
+dependencies = [
+	"osascript2"  # For macOS
+]
 
 [project.readme]
 file = "README.md"
@@ -60,7 +63,7 @@ ignore=[
 	"E731",
 	"I001",
 	"PLR0913", "PLR2004",
-	"S101",
+	"S101", "S603",
 	"TID252",
 ]
 extend-select = [
@@ -87,7 +90,7 @@ convention = "google"
 "tests/*" = ["DTZ005", "PGH003", "PLW0108"]
 
 [tool.bandit]
-skips = ["B101", "B104", "B201"]
+skips = ["B101", "B104", "B201", "B404", "B603"]
 
 [tool.vulture]
 ignore_names = []

{zstdlib-0.7.0 → zstdlib-0.8.0}/tests/log/base.py

@@ -29,7 +29,8 @@ class LeftBase:
     def hijack(
         cls, name: str, reuse: bool = False, fmt: logging.Formatter | None = None
     ) -> AbstractContextManager[logging.Logger]:
-        """
+        """Create a hijacked logger
+
         Returns:
             A logger configured to write to an internal queue
         """

zstdlib-0.8.0/tests/test_lazy.py

@@ -0,0 +1,25 @@
+# pylint: disable=missing-module-docstring,missing-class-docstring,missing-function-docstring
+import unittest
+
+from zstdlib.lazy import Str
+
+
+def _append(buf: list[str], *, obj: str) -> str:
+    buf.append(obj)
+    return str(len(buf))
+
+
+class TestLazy(unittest.TestCase):
+
+    def test_str(self) -> None:
+        buf: list[str] = []
+        obj = "apples"
+        x = Str(_append, buf, obj=obj)
+        self.assertEqual(buf, [])
+        one = str(x)  # Invoke Lazy Str
+        self.assertEqual(one, "1")
+        self.assertEqual(buf, [obj])
+
+
+if __name__ == "__main__":
+    unittest.main()

{zstdlib-0.7.0 → zstdlib-0.8.0}/zstdlib/__init__.py

@@ -1,11 +1,11 @@
-__version__ = "0.7.0"
+__version__ = "0.8.0"
 
 from .not_set import NotSetType, NotSet
 from .frozen import Freezable, frozen
 from .singleton import Singleton
 from .signal_cm import signal_cm
 from .enum import Enum, auto
-from . import log, io
+from . import macos, lazy, log, io
 
 __all__ = (
     "Enum",
@@ -16,6 +16,8 @@ __all__ = (
     "auto",
     "frozen",
     "io",
+    "lazy",
     "log",
+    "macos",
     "signal_cm",
 )

{zstdlib-0.7.0 → zstdlib-0.8.0}/zstdlib/ansi.py

@@ -117,14 +117,18 @@ class Color(metaclass=_ColorMeta):
             self.code = RawColor._parse_color(fmt) if isinstance(fmt, str) else fmt.code
 
     def __call__(self, string: str) -> str:
-        """
+        """Args:
+            string: The string to color
+
         Returns:
             The string color codes with the given ansi code
         """
         return f"{self.code}{string}{self.RESET}"
 
     def __add__(self, other: Self) -> Self:
-        """
+        """Args:
+            other: The other string to color
+
         Returns:
             A new color made by concatenating these two
         """
@@ -133,31 +137,30 @@ class Color(metaclass=_ColorMeta):
         return type(self)(code=f"{self.code[:-1]};{other.code[len(_PREFIX):]}")
 
     def __eq__(self, other: object) -> bool:
-        """
+        """Args:
+            other: The color to compare against
+
         Returns:
             Whether the two colors are equal
         """
         return isinstance(other, type(self)) and self.code == other.code
 
     def __hash__(self) -> int:
-        """
-        Returns:
-            A hash of the current color
-        """
         return hash((type(self), self.code))
 
     def __repr__(self) -> str:
-        """
-        Returns:
-            The ansi color code this object represents
-        """
+        """Get the ansi color code this object represents"""
         return f"<Color {self.code!r}>"
 
     @classmethod
     def factory(
         cls, *, foreground: RawColor | None = None, background: RawColor | None = None, **modifiers: bool
     ) -> Self:
-        """
+        """Args:
+            foreground: The foreground color
+            background: The background color
+            **modifiers: Color modifiers to apply
+
         Returns:
             The Ansi given the chosen color and various modifiers
         """
@@ -167,7 +170,11 @@ class Color(metaclass=_ColorMeta):
 def _generate_code(
     foreground: RawColor | None, background: RawColor | None, modifiers: dict[str, bool]
 ) -> str:
-    """
+    """Args:
+        foreground: The foreground color
+        background: The background color
+        **modifiers: Color modifiers to apply
+
     Returns:
         The Ansi given the chosen color and various modifiers
     """

{zstdlib-0.7.0 → zstdlib-0.8.0}/zstdlib/enum.py

@@ -136,8 +136,7 @@ class Enum(metaclass=EnumType, empty_ok=True):
 
 
 def entries(enum: EnumType) -> dict[str, tuple[type | None, Any]]:
-    """
-    Args:
+    """Args:
         enum: A class whose metaclass is EnumType
 
     Returns:
@@ -150,8 +149,7 @@ def entries(enum: EnumType) -> dict[str, tuple[type | None, Any]]:
 
 
 def values(enum: Any) -> tuple[Any, ...]:
-    """
-    Args:
+    """Args:
         enum: A class whose metaclass is EnumType
 
     Returns:

{zstdlib-0.7.0 → zstdlib-0.8.0}/zstdlib/io.py

@@ -16,7 +16,7 @@ class ProtectedFile:
     __slots__ = ("raw",)
 
     def __init__(self, raw: IOBase) -> None:
-        """
+        """Create a ProtectedFile
         Args:
             raw: The raw IO object to wrap, users can access it directly if they must
         """

zstdlib-0.8.0/zstdlib/lazy.py

@@ -0,0 +1,31 @@
+from collections.abc import Callable
+from typing import ParamSpec
+from threading import Lock
+
+P = ParamSpec("P")
+
+__all__ = ("Str",)
+
+
+class Str:
+    """A lazily evaluated string class"""
+
+    __slots__ = ("_args", "_fn", "_kwargs", "_lock", "_result")
+
+    def __init__(self, fn: Callable[P, str], *args: P.args, **kwargs: P.kwargs) -> None:
+        """Store a function and its arguments, on str(self) return fn(*args, **kwargs)
+        The result of the function invocation is cached and will be reused
+        """
+        self._result: str | None = None
+        self._lock = Lock()
+        self._fn = fn
+        self._args = args
+        self._kwargs = kwargs
+
+    def __str__(self) -> str:
+        """Evaluate the saved function"""
+        if self._result is not None:
+            return self._result
+        with self._lock:
+            self._result = self._fn(*self._args, **self._kwargs)
+        return self._result

zstdlib-0.8.0/zstdlib/macos.py

@@ -0,0 +1,198 @@
+from typing import NamedTuple, ParamSpec, ClassVar, TypeVar, Self
+from subprocess import TimeoutExpired, Popen
+from collections.abc import Callable
+from multiprocessing import Process
+from logging import getLogger
+from functools import wraps
+from threading import Lock
+from pathlib import Path
+from os import getpid
+import atexit
+
+import osascript
+
+CAFFEINATE = "/usr/bin/caffeinate"  # This is a hard-coded location on macOS
+P = ParamSpec("P")
+R = TypeVar("R")
+_log = getLogger(__name__)
+
+
+__all__ = ("Caffeinate", "osascript")
+
+
+class Caffeinate:
+    """A small wrapper class around macOS' CLI tool Caffeinate"""
+
+    _armed_lock: ClassVar[Lock] = Lock()
+    _armed: ClassVar[set[Self]] = set()
+    __slots__ = ("_cmd", "_data", "_lock", "_wait")
+
+    class _Data(NamedTuple):
+        owner: int
+        proc: Popen
+
+    # pylint: disable=too-many-arguments
+    def __init__(
+        self,
+        cmd: list[Path | str | None] | None = None,
+        *,
+        wait_for_cmd: bool = False,
+        display: bool = False,
+        idle: bool = False,
+        disk: bool = False,
+        system: bool = False,
+        user: bool = False,
+        timeout: int | None = None,
+        wait: int | Popen | Process | None = None,
+    ) -> None:
+        """Invokes the macOS Caffeinate CLI tool to prevent sleeping.
+        Arguments are passed through to Caffeinate, descriptions are taken from the CLI tool; if they disagree with those found in `man caffeinate`, theirs are more likely to be correct.
+        Warning: If cmd is passed, re-invoking __enter__ after an __exit__ will cause Caffeinate to run again and thus the command will run again
+
+        Args:
+            cmd: An optional CLI command (and arguments) to run under the Caffeinate process
+            wait_for_cmd: If True: Wait until cmd has finished executing before returning from __enter__
+            display: If True: Create an assertion to prevent the display from sleeping.
+            idle: If True: Create an assertion to prevent the system from idle sleeping.
+            disk: If True: Create an assertion to prevent the disk from idle sleeping.
+            system: If True: Create an assertion to prevent the system from sleeping. This assertion is valid only when system is running on AC power.
+            user: If True: Create an assertion to declare that user is active. If the display is off, this option turns the display on and prevents the display from going into idle sleep. If a timeout is not specified with '-t' option, then this assertion is taken with a default of 5 second timeout.
+            timeout: Specifies the timeout value in seconds for which this assertion has to be valid. The assertion is dropped after the specified timeout. This option conflicts with cmd. Note: this timeout is passed to the Caffeinate CLI command, it is not enforced by python
+         with this command.
+            wait: Waits for the process with the specified pid to exit. Once the the process exits, the assertion is also released. This option conflicts with cmd.
+        """
+        if cmd is None:
+            if wait_for_cmd:
+                raise ValueError("wait_for_cmd requires cmd not be None")
+            cmd = []
+        elif not cmd:
+            raise ValueError("Empty cmd; did you mean to use None?")
+        elif timeout is not None:
+            raise ValueError("timeout may not be used with cmd")
+        elif wait is not None:
+            raise ValueError("wait may not be used with cmd")
+        else:
+            cmd = list(cmd)
+        self._lock = Lock()
+        self._data: Caffeinate._Data | None = None  # Have to hardcode "Caffeinate" for mypy :/
+        if isinstance(timeout, float):
+            raise TypeError("Float timeout not supported")
+        if timeout is not None and timeout < 1:
+            raise ValueError("Timeout should be a positive integer")
+        wait = wait.pid if isinstance(wait, Popen | Process) else wait
+        flags = [
+            "-d" if display else None,
+            "-i" if idle else None,
+            "-m" if disk else None,
+            "-s" if system else None,
+            "-u" if user else None,
+            None if timeout is None else f"-t {timeout}",
+            None if wait is None else f"-w {wait}",
+        ]
+        self._cmd = list(map(str, [CAFFEINATE] + [k for i in flags if i for k in i.split(" ")] + cmd))
+        self._wait = wait_for_cmd
+
+    def __enter__(self) -> Self:
+        """Start Caffeinate-ing"""
+        with self._lock:
+            if self._data is not None:
+                raise RuntimeError("This context manager has already been entered")
+            self._data = self._Data(getpid(), Popen(self._cmd))
+            _log.debug("Created Popen(%s), pid=%s", self._cmd, self._data.proc.pid)
+        if self._wait:
+            self._data.proc.wait()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        with self._lock:
+            if self._data is None:
+                raise RuntimeError("Context managernever __enter__'d or already __exit__'d")
+            if getpid() != self._data.owner:
+                return
+            _log.debug("Reaping Caffeinate process: %s", self._data.proc.pid)
+            self._data.proc.terminate()
+            try:
+                self._data.proc.wait(timeout=1)
+            except TimeoutExpired:
+                _log.error("Caffeinate process didn't exit on .terminate()")
+                self._data.proc.kill()
+            self._data = None
+
+    @classmethod
+    def decorate(
+        cls, cmd: list[Path | str | None] | None = None, **caffeinate_kwargs: object
+    ) -> Callable[[Callable[P, R]], Callable[P, R]]:
+        """A decorator to wrap a function with a Caffeinate instance
+        Example:
+            @decorate(idle=True)
+            def foo():
+        """
+        if cmd and callable(cmd[0]):
+            raise ValueError(f"Invalid usage of .decorate; see help({cls.__name__}.decorate)")
+
+        def outer(f: Callable[P, R]) -> Callable[P, R]:
+            @wraps(f)
+            def inner(*args: P.args, **kwargs: P.kwargs) -> R:
+                with cls(cmd, **caffeinate_kwargs):  # type: ignore[arg-type]
+                    return f(*args, **kwargs)
+
+            return inner
+
+        return outer
+
+    @classmethod
+    def new(
+        cls,
+        cmd: list[Path | str | None] | None = None,
+        *,
+        survive_exit: bool = False,
+        **kwargs: object,
+    ) -> Self:
+        """Return an __enter__'d Caffeinate, whose __exit__ will run atexit
+        cmd and **kwargs are passed to __init__
+
+        Args:
+            cmd: Passed to Caffeinate
+            survive_exit: Do not kill this Caffeinate instance when this process exits
+            kwargs: Passed to Caffeinate
+        """
+        ret = cls(cmd, **kwargs)  # type: ignore[arg-type]
+        _ = ret.__enter__()  # pylint: disable=unnecessary-dunder-call
+        if not survive_exit:
+            with cls._armed_lock:
+                cls._armed.add(ret)
+        return ret
+
+    def survive_exit(self) -> None:
+        """Disable atexit death; only permitted for instances created by .new()"""
+        # pylint: disable=protected-access
+        with self._armed_lock:
+            if self not in self._armed:
+                msg = f"This instance was not created by {self.__class__.__name__}.new() or already called .survive_exit()"
+                raise ValueError(msg)
+            self._armed.remove(self)
+            assert self._data is not None
+            _log.debug("Disabled cleanup of caffeinate subprocess PID=%s", self._data.proc.pid)
+
+    @classmethod
+    def _atexit(cls) -> None:
+        """Clean up child Caffeinate subprocesses started by this class"""
+        # pylint: disable=protected-access
+        pid = getpid()
+        _log.debug("Cleaning up all owned Caffeinate subprocesses started this process (PID=%s)", pid)
+        with cls._armed_lock:
+            for i in cls._armed:
+                if i._data is None:
+                    _log.error("Unentered Caffeinate process in ._armed; this should never happen")
+                    continue
+                if i._data.owner == pid:
+                    i.__exit__()
+            cls._armed.clear()
+
+    def __repr__(self) -> str:
+        if self._data is None:
+            return f"<Caffeinate: NOT RUNNING, flags={self._cmd[1:]}>"
+        return f"<Caffeinate: PID={self._data.proc.pid}, flags={self._cmd[1:]}>"
+
+
+atexit.register(Caffeinate._atexit)  # pylint: disable=protected-access

{zstdlib-0.7.0 → zstdlib-0.8.0}/zstdlib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zstdlib
-Version: 0.7.0
+Version: 0.8.0
 Summary: A set of useful python utilities
 License: GPLv3
 Project-URL: Homepage, https://github.com/zwimer/zstdlib
@@ -11,6 +11,7 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: osascript2
 Dynamic: license-file
 
 # zstdlib

{zstdlib-0.7.0 → zstdlib-0.8.0}/zstdlib.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ tests/test_ansi.py
 tests/test_enum.py
 tests/test_frozen.py
 tests/test_io.py
+tests/test_lazy.py
 tests/test_not_set.py
 tests/test_singleton.py
 tests/log/__init__.py
@@ -17,6 +18,8 @@ zstdlib/ansi.py
 zstdlib/enum.py
 zstdlib/frozen.py
 zstdlib/io.py
+zstdlib/lazy.py
+zstdlib/macos.py
 zstdlib/not_set.py
 zstdlib/py.typed
 zstdlib/signal_cm.py
@@ -24,6 +27,7 @@ zstdlib/singleton.py
 zstdlib.egg-info/PKG-INFO
 zstdlib.egg-info/SOURCES.txt
 zstdlib.egg-info/dependency_links.txt
+zstdlib.egg-info/requires.txt
 zstdlib.egg-info/top_level.txt
 zstdlib/log/__init__.py
 zstdlib/log/cute.py

zstdlib-0.8.0/zstdlib.egg-info/requires.txt

@@ -0,0 +1 @@
+osascript2