zstdlib 0.0.1__tar.gz → 0.0.2__tar.gz

{zstdlib-0.0.1/zstdlib.egg-info → zstdlib-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zstdlib
-Version: 0.0.1
+Version: 0.0.2
 Summary: A set of useful python utilities
 License: GPLv3
 Project-URL: Homepage, https://github.com/zwimer/zstdlib
@@ -12,3 +12,6 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+
+# zstdlib
+A set of useful python utilities

zstdlib-0.0.2/README.md

@@ -0,0 +1,2 @@
+# zstdlib
+A set of useful python utilities

{zstdlib-0.0.1 → zstdlib-0.0.2}/pyproject.toml

@@ -49,11 +49,16 @@ version = {attr = "zstdlib.__version__"}
 
 # Tools
 
+[tool.pylint.MASTER]
+ignore-paths = '^tests/.*$'
 [tool.pylint."MESSAGES CONTROL"]
 disable = [
+    "unnecessary-lambda-assignment",
+    "method-cache-max-size-none",
 	"missing-module-docstring",
-	"invalid-name",
-	"line-too-long"
+	"too-few-public-methods",
+	"line-too-long",
+	"invalid-name"
 ]
 
 [tool.black]
@@ -71,6 +76,6 @@ ignore=["E731"]
 skips = ["B101", "B104", "B201"]
 
 [tool.vulture]
-ignore_names = ["cli", "_help", "_show_version", "_channel", "strict_slashes"]
+ignore_names = []
 min_confidence = 70
 paths = ["zstdlib"]

zstdlib-0.0.2/tests/log/base.py

@@ -0,0 +1,69 @@
+from logging.handlers import QueueHandler
+from contextlib import contextmanager
+from collections.abc import Callable
+from threading import Lock
+from typing import Any
+import logging
+import queue
+
+
+@contextmanager
+def _cml(logger: logging.Logger, exit_func: Callable[[], Any]):
+    try:
+        yield logger
+    finally:
+        exit_func()
+
+
+class LeftBase:
+    """
+    A base class for tests that hijack loggers
+    """
+
+    _hijacked: set[logging.Logger] = set()  # Set of all loggers that have ever been hijacked
+    _qmap: dict[logging.Logger, queue.Queue[logging.LogRecord]] = {}
+    _lb_old: dict[logging.Logger, list[logging.Handler]] = {}
+    _lb_lock = Lock()
+
+    messages: dict[logging.Logger, list[str]] = {}
+
+    @classmethod
+    def hijack(cls, name: str, reuse: bool = False, fmt: logging.Formatter | None = None):
+        """
+        :return: A logger configured to write to an internal queue
+        """
+        log = logging.getLogger(name)
+        q: queue.Queue[logging.LogRecord] = queue.Queue()
+        with cls._lb_lock:
+            if not reuse and log in cls._hijacked:
+                raise RuntimeError("Logger already hijacked")
+            cls._hijacked.add(log)
+            cls._lb_old[log] = log.handlers
+            cls._qmap[log] = q
+        log.handlers = [QueueHandler(q)]
+        if fmt is not None:
+            log.handlers[0].setFormatter(fmt)
+        log.setLevel(1)  # Not 0 to ensure that the parent logger level is not used
+        return _cml(log, lambda: cls._restore(log))
+
+    @classmethod
+    def _restore(cls, logger: logging.Logger) -> None:
+        """
+        Restore the logger and read all messages from the queue
+        :return: The messages stored by the logger queue
+        """
+        if len(logger.handlers) != 1 or not isinstance(qh := logger.handlers[0], QueueHandler):
+            raise RuntimeError("Logger not hijacked")
+        # Restore old logger and extract q
+        with cls._lb_lock:
+            if logger not in cls._hijacked:
+                raise RuntimeError("Logger not hijacked")
+            logger.handlers = cls._lb_old.pop(logger)
+            q = cls._qmap.pop(logger)
+        # Read queue
+        qh.flush()
+        messages = []
+        while not q.empty():
+            messages.append(q.get(False).msg)
+        with cls._lb_lock:
+            cls.messages[logger] = messages

zstdlib-0.0.2/tests/log/test_cute.py

@@ -0,0 +1,98 @@
+# pylint: disable=missing-module-docstring,missing-class-docstring,missing-function-docstring,unused-variable
+import unittest
+
+from zstdlib.log import CuteFormatter
+from zstdlib.ansi import Color
+
+from .base import LeftBase
+
+
+class TestCuteFormatter(LeftBase, unittest.TestCase):
+
+    def test_hardcoded_colors(self) -> None:
+        color = Color.strikethrough_green
+        name = "TestCuteFormatter.test_hardcoded_colors"
+        with self.hijack(name, fmt=CuteFormatter(colors={name: color})) as log:
+            log.debug("test")
+        msg = self.messages[log][0].rsplit("|", 1)[-1]
+        self.assertEqual(f" {color.code}test{Color.RESET}", msg)
+
+    def test_name_width(self) -> None:
+        width = 123
+        color = Color.red
+        name = "TestCuteFormatter.name_width"
+        with self.hijack(name, fmt=CuteFormatter(colors={name: color}, name_width=width)) as log:
+            log.debug("test")
+        lvl, _, nam, msg = self.messages[log][0].split("|")
+        self.assertEqual("DEBUG", lvl.strip())
+        self.assertEqual(f" {color(name.ljust(width))} ", nam)
+        self.assertEqual(f" {color('test')}", msg)
+
+    def test_no_color(self) -> None:
+        name = "TestCuteFormatter.test_no_color"
+        with self.hijack(name, fmt=CuteFormatter(colored=False)) as log:
+            log.debug("test")
+        lvl, _, nam, msg = self.messages[log][0].split("|")
+        self.assertEqual("DEBUG", lvl.strip())
+        self.assertEqual(name, nam.strip())
+        self.assertEqual(" test", msg)
+
+    def test_edit_colors(self) -> None:
+        name = "TestCuteFormatter.edit_colors"
+        cf = CuteFormatter(colored=False)
+        color = Color.strikethrough_red
+        with self.hijack(name, fmt=cf) as log:
+            log.critical("test")
+        msg = self.messages[log][0].rsplit("|", 1)[-1]
+        self.assertEqual(" test", msg)
+        with self.hijack(name, reuse=True, fmt=cf) as log:
+            cf.colored = True
+            cf.update({name: color})
+            log.critical("test")
+        msg = self.messages[log][0].rsplit("|", 1)[-1]
+        self.assertEqual(f" {color.code}test{Color.RESET}", msg)
+
+    def test_level_color(self) -> None:
+        name = "TestCuteFormatter.test_level_color"
+        msg = "test"
+        levels = (5, 10, 20, 30, 40, 50, 60)
+        with self.hijack(name, fmt=CuteFormatter()) as log:
+            for i in levels:
+                log.log(i, msg)
+        self.assertEqual(len(levels), len(self.messages[log]))
+        l_name = lambda idx: self.messages[log][idx].split("|")[0].strip()
+        self.assertEqual(Color.dim("Level 5".ljust(8)), l_name(0))
+        self.assertEqual("DEBUG", l_name(1))
+        self.assertEqual(Color.blue("INFO".ljust(8)), l_name(2))
+        self.assertEqual(Color.yellow("WARNING".ljust(8)), l_name(3))
+        self.assertEqual(Color.red("ERROR".ljust(8)), l_name(4))
+        self.assertEqual(Color.bright_red_bg_yellow("CRITICAL".ljust(8)), l_name(5))
+        self.assertEqual(Color.bright_red_bg_yellow("Level 60".ljust(8)), l_name(6))
+
+    def test_exception(self) -> None:
+        name = "TestCuteFormatter.test_exception"
+        with self.hijack(name, fmt=CuteFormatter()) as log:
+            try:
+                raise ValueError(name)
+            except ValueError:
+                log.error("test", exc_info=True)
+        spt = self.messages[log][0].split("\n")
+        self.assertTrue(len(spt) > 2)
+        self.assertEqual("Traceback (most recent call last):", spt[1].strip())
+        self.assertEqual("raise ValueError(name)", spt[-2].strip())
+        self.assertEqual(f"ValueError: {name}", spt[-1].strip())
+
+    def test_multi_color(self) -> None:
+        base = "TestCuteFormatter.test_multi_color."
+        cf = CuteFormatter()
+        messages: set[str] = set()
+        for i in range(100):
+            with self.hijack(f"{base}{i}", fmt=cf) as log:
+                log.info(base)
+            messages.add(self.messages[log][0].rsplit("|", 1)[-1].strip())
+        cols = ("red", "green", "yellow", "blue", "magenta", "cyan", "default")
+        self.assertEqual({getattr(Color, i)(base) for i in cols}, messages)
+
+
+if __name__ == "__main__":
+    unittest.main()

zstdlib-0.0.2/tests/log/test_trace.py

@@ -0,0 +1,74 @@
+# pylint: disable=missing-module-docstring,missing-class-docstring,missing-function-docstring
+import unittest
+import logging
+
+from zstdlib.log import trace
+
+from .base import LeftBase
+
+
+# mypy: disable_error_code="attr-defined"
+class TestTrace(LeftBase, unittest.TestCase):
+
+    def test_trace(self) -> None:
+        """
+        Avoid splitting up into multiple functions since trace.install() affects global state
+        Keeping this as one function ensures that the tests are run in order
+        """
+        # Test bad installs
+        with self.assertRaises(ValueError):
+            trace.install(value=-1)
+        with self.assertRaises(ValueError):
+            trace.install(value=logging.DEBUG + 1)
+        logging.TRACE = None
+        with self.assertRaises(AttributeError):
+            trace.install()
+        del logging.TRACE
+        logging.trace = None
+        with self.assertRaises(AttributeError):
+            trace.install()
+        del logging.trace
+        logging.getLoggerClass().trace = None
+        with self.assertRaises(AttributeError):
+            trace.install()
+        del logging.getLoggerClass().trace
+        trace._State.start = True  # pylint: disable=protected-access
+        with self.assertRaises(RuntimeError):
+            trace.install()
+        trace._State.start = False  # pylint: disable=protected-access
+        # Good install
+        trace.install(value=5)
+        # Attribute check
+        self.assertTrue(hasattr(logging, "TRACE"))
+        self.assertTrue(hasattr(logging, "trace"))
+        self.assertTrue(hasattr(logging.getLogger(), "trace"))
+        self.assertEqual(logging.TRACE, 5)
+        self.assertEqual(logging.getLevelName(logging.TRACE), "TRACE")  # type: ignore[call-overload]
+        # Root check
+        with self.hijack("") as log:
+            old = log.getEffectiveLevel()
+            # pylint: disable=not-callable
+            logging.trace("test1")  # type: ignore[misc]
+            log.setLevel(logging.DEBUG)
+            # pylint: disable=not-callable
+            logging.trace("test2")  # type: ignore[misc]
+            log.setLevel(old)
+        self.assertEqual(self.messages[log], ["test1"])
+        # Logger check
+        with self.hijack("TestTrace.t1") as log:
+            old = log.getEffectiveLevel()
+            # pylint: disable=not-callable
+            log.trace("test3")
+            log.setLevel(logging.DEBUG)
+            # pylint: disable=not-callable
+            log.trace("test4")
+            log.setLevel(old)
+        self.assertEqual(self.messages[log], ["test3"])
+        # Test re-installation
+        with self.assertRaises(RuntimeError):
+            trace.install(value=5)
+        trace.install(value=5, force=True)
+
+
+if __name__ == "__main__":
+    unittest.main()

zstdlib-0.0.2/tests/test_ansi.py

@@ -0,0 +1,56 @@
+# pylint: disable=missing-module-docstring,missing-class-docstring,missing-function-docstring
+import unittest
+
+from zstdlib.ansi import PureColor, RawColor, Color
+
+
+class TestAnsiColor(unittest.TestCase):
+
+    def test_raw_color(self) -> None:
+        msg = "Hello, World!"
+        for i, k in PureColor.__members__.items():
+            self.assertEqual(f"\033[{k.value}m{msg}\033[0m", getattr(Color, i)(msg))
+
+    def test_bright_background_color(self) -> None:
+        msg = "Hello, World!"
+        for i, k in PureColor.__members__.items():
+            self.assertEqual(f"\033[{k.value+70}m{msg}\033[0m", getattr(Color, f"bg_bright_{i}")(msg))
+
+    def test_init(self) -> None:
+        msg = "Hello, World!"
+        cname = "black"
+        c = RawColor(getattr(PureColor, cname))
+        self.assertEqual(f"\033[{c.value}m{msg}\033[0m", getattr(Color, cname)(msg))  # Sanity check
+        self.assertEqual(f"\033[{c.value}m{msg}\033[0m", Color(c)(msg))
+        self.assertEqual(f"\033[{c.value}m{msg}\033[0m", Color(c)(msg))
+        self.assertEqual(f"\033[{c.value}m{msg}\033[0m", Color(Color(c))(msg))
+        self.assertEqual(f"\033[{c.value}m{msg}\033[0m", Color(code=Color(c).code)(msg))
+        # Errors
+        with self.assertRaises(ValueError):
+            _ = Color("blue_blue")
+        with self.assertRaises(ValueError):
+            _ = Color("bg_blue_bg_bright_blue")
+        with self.assertRaises(ValueError):
+            _ = Color(fmt="1", code="1")
+        with self.assertRaises(ValueError):
+            _ = Color(code="1")
+        with self.assertRaises(ValueError):
+            _ = Color("bright_bg_red")
+        # Error converted
+        with self.assertRaises(AttributeError):
+            _ = Color.bright_bg_red
+
+    def test_modifiers(self) -> None:
+        msg = "Hello, World!"
+        self.assertEqual(f"\033[1;34m{msg}\033[0m", Color.bold_blue(msg))  # Small modifier
+        self.assertEqual(f"\033[9;32m{msg}\033[0m", Color.strikethrough_green(msg))  # Large modifier
+        self.assertEqual(f"\033[2;9;31m{msg}\033[0m", Color.strikethrough_dim_red(msg))
+        self.assertEqual(f"\033[3;4;5;39m{msg}\033[0m", Color.underline_italic_blinking_default(msg))
+        # Test no colors / multiple colors
+        self.assertEqual(f"\033[1m{msg}\033[0m", Color.bold(msg))
+        self.assertEqual(f"\033[31;42m{msg}\033[0m", Color.red_bg_green(msg))
+        self.assertEqual(f"\033[1;3;32;101m{msg}\033[0m", Color.bg_bright_red_bold_italic_green(msg))
+
+
+if __name__ == "__main__":
+    unittest.main()

zstdlib-0.0.2/tests/test_enum.py

@@ -0,0 +1,137 @@
+# pylint: disable=missing-module-docstring,missing-class-docstring,missing-function-docstring,unused-variable
+import unittest
+
+from zstdlib import EnumType, Enum
+
+
+class TestEnumType(unittest.TestCase):
+
+    def test_valid(self) -> None:
+        class ET1(metaclass=EnumType):
+            arg1: int = 0
+            arg2: int = 1
+
+    def test_empty(self) -> None:
+        class ET2(metaclass=EnumType, empty_ok=True):
+            pass
+
+        with self.assertRaises(ValueError):
+
+            class ET3(metaclass=EnumType):
+                pass
+
+    def test_dupe(self) -> None:
+        with self.assertRaises(ValueError):
+
+            class ET4(metaclass=EnumType):
+                arg1: int = 0
+                arg2: int = 0
+
+    def test_annotations(self) -> None:
+        with self.assertRaises(ValueError):
+
+            class ET5(metaclass=EnumType):
+                arg1 = 1
+
+        with self.assertRaises(ValueError):
+
+            class ET6(metaclass=EnumType):
+                arg1: int
+
+        with self.assertRaises(TypeError):
+
+            class ET7(metaclass=EnumType):
+                arg1: str = 0  # type: ignore[assignment]
+
+    def test_instantiation(self) -> None:
+        with self.assertRaises(AttributeError):
+
+            class ET8(metaclass=EnumType):
+                arg1: int = 1
+
+                def __init__(self):
+                    pass
+
+        with self.assertRaises(AttributeError):
+
+            class ET9(metaclass=EnumType):
+                arg1: int = 1
+
+                def __new__(cls):
+                    pass
+
+        class ET10(metaclass=EnumType):
+            arg1: int = 0
+
+        with self.assertRaises(NotImplementedError):
+            ET10()
+        with self.assertRaises(NotImplementedError):
+            ET10.__init__({})
+
+
+class TestEnum(unittest.TestCase):
+    def test_valid(self) -> None:
+        class E1(Enum):
+            arg1: int = 0
+            arg2: int = 1
+
+    def test_empty(self) -> None:
+        class E2(Enum, empty_ok=True):
+            pass
+
+        with self.assertRaises(ValueError):
+
+            class E3(Enum):
+                pass
+
+    def test_dupe(self) -> None:
+        with self.assertRaises(ValueError):
+
+            class E4(Enum):
+                arg1: int = 0
+                arg2: int = 0
+
+    def test_annotations(self) -> None:
+        with self.assertRaises(ValueError):
+
+            class E5(Enum):
+                arg1 = 1
+
+        with self.assertRaises(ValueError):
+
+            class E6(Enum):
+                arg1: int
+
+        with self.assertRaises(TypeError):
+
+            class E7(Enum):
+                arg1: str = 0  # type: ignore[assignment]
+
+    def test_instantiation(self) -> None:
+        with self.assertRaises(AttributeError):
+
+            class E8(Enum):
+                arg1: int = 1
+
+                def __init__(self):
+                    pass
+
+        with self.assertRaises(AttributeError):
+
+            class E9(Enum):
+                arg1: int = 1
+
+                def __new__(cls):
+                    pass
+
+        class E10(Enum):
+            arg1: int = 0
+
+        with self.assertRaises(NotImplementedError):
+            E10()
+        with self.assertRaises(NotImplementedError):
+            E10.__init__({})
+
+
+if __name__ == "__main__":
+    unittest.main()

zstdlib-0.0.2/tests/test_singleton.py

@@ -0,0 +1,126 @@
+# pylint: disable=missing-module-docstring,missing-class-docstring,missing-function-docstring,unused-variable
+from threading import Thread, Lock
+from time import sleep
+import unittest
+
+from zstdlib import SingletonType, Singleton
+
+
+class TestSingletonType(unittest.TestCase):
+
+    def test_valid(self) -> None:
+        class ST1(metaclass=SingletonType):
+            pass
+
+        self.assertIs(ST1(), ST1())
+
+        class ST2(metaclass=SingletonType):
+            pass
+
+        self.assertIsNot(ST1(), ST2())
+
+    def test_subclass(self) -> None:
+        class ST3(metaclass=SingletonType):
+            pass
+
+        with self.assertRaises(NotImplementedError):
+
+            class ST4(ST3):
+                pass
+
+    def test_multi_thread(self):
+        """
+        Ensure that SingletonType is thread safe and that constructing an object doesn't delay other threads
+        Technically this is more of a heuristic, but it failing is extremely unlikely
+        """
+
+        class ST5(metaclass=SingletonType):
+            def __init__(self):
+                sleep(0.2)
+
+        class ST6(metaclass=SingletonType):
+            def __init__(self):
+                sleep(0.8)
+
+        lock = Lock()
+        events = []
+        results = []
+
+        def t1() -> None:
+            """
+            Construct an ST6 immediately
+            """
+            with lock:
+                pass
+            events.append("START: ST6()")
+            results.append(ST6())
+            events.append("END: ST6()")
+
+        def t2() -> None:
+            """
+            Construct an ST6 after the first ST6 has started construction but before it has finished
+            """
+            with lock:
+                pass
+            sleep(0.2)
+            events.append("START: ST6()")
+            results.append(ST6())
+            events.append("END: ST6()")
+
+        def t3() -> None:
+            """
+            Construct ST5's after both ST6s have started construction, finishing before either end
+            """
+            with lock:
+                pass
+            sleep(0.4)
+            # Loop Enough times that ST6 wil be complete if it ST5 actually constructed each time
+            for i in range(10):
+                events.append("START: ST5()")
+                results.append(ST5())
+                events.append("END: ST5()")
+
+        threads = (Thread(target=t1), Thread(target=t2), Thread(target=t3))
+        with lock:
+            for i in threads:
+                i.start()
+            # Give threads a moment to construct then let them go
+            sleep(0.2)
+        for i in threads:
+            i.join()
+        # Check results
+        wanted = ["START: ST6()"] * 2 + ["START: ST5()", "END: ST5()"] * 10 + ["END: ST6()"] * 2
+        self.assertEqual(events, wanted)
+        # Check constructed objects
+        self.assertEqual(len(results), 2 + 10)
+        for i in range(9):
+            self.assertIs(results[0], results[i + 1])
+        self.assertIsNot(results[0], results[-1])
+        self.assertIs(results[-1], results[-2])
+
+
+class TestSingleton(unittest.TestCase):
+
+    def test_valid(self):
+        class S1(Singleton):
+            pass
+
+        self.assertIs(S1(), S1())
+
+        class S2(Singleton):
+            pass
+
+        self.assertIsNot(S1(), S2())
+
+    def test_subclass(self):
+        class S3(Singleton):
+            pass
+
+        with self.assertRaises(NotImplementedError):
+
+            class S4(S3):
+                pass
+
+
+if __name__ == "__main__":
+    unittest.main()

zstdlib-0.0.2/zstdlib/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.0.2"
+
+from .singleton import SingletonType, Singleton
+from .enum import EnumType, Enum
+from . import log

zstdlib-0.0.2/zstdlib/ansi.py

@@ -0,0 +1,172 @@
+from enum import Enum, unique, auto
+from functools import cache
+from typing import Self
+import re
+
+
+MODIFIERS = ("bold", "dim", "italic", "underline", "blinking", "inverse", "hidden", "strikethrough")
+
+_PREFIX = "\033["
+
+
+@unique
+class PureColor(Enum):
+    """
+    An enum of ansi color values
+    """
+
+    black = 30
+    red = auto()
+    green = auto()
+    yellow = auto()
+    blue = auto()
+    magenta = auto()
+    cyan = auto()
+    white = auto()
+    default = 39
+
+
+class RawColor:
+    """
+    A class that represents a color with all possible modifiers
+    """
+
+    __slots__ = ("color", "bright", "background", "value")
+
+    def __init__(self, color: PureColor | str | int, *, bright: bool = False, background: bool = False):
+        self.color = PureColor(getattr(PureColor, color) if isinstance(color, str) else color)
+        self.bright = bright
+        self.background = background
+        self.value = self.color.value + (10 if self.background else 0) + (60 if self.bright else 0)
+
+
+class _ColorMeta(type):
+    """
+    A metaclass that implements __getattr__ at the class level for Color
+    """
+
+    def __getattr__(cls, item: str) -> "Color":
+        try:
+            return cls(code=_parse_color(item))
+        except ValueError as e:
+            raise AttributeError(str(e)) from e
+
+
+class Color(metaclass=_ColorMeta):
+    """
+    Represents an Ansi color code; calling this on a string will apply the code to the string
+    Can be constructed via .factory; alternatively calling Color.<name> or Color(<name>) will
+    automatically construct a color. Colors are constructed with attributes determined by
+    splitting <name> on "_". Colors may be made bright by prepending "bright_" to the color name
+    Background colors may be specified by prepending "BG_" to a color name
+        BG_ must precede bright_ if both are specified
+    Foreground and background colors may both be specified at once
+    Examples:
+        Color.red
+        Color.default
+        Color.BRIGHT_BLUE
+        Color.BG_green
+        Color.Bright_BG_black
+        Color.bold_underline_yellow
+        Color.bold_bright_bg_BLUE_bright_green
+        Color.BOLD_bright_Red_strikethrough_bg_Bright_GREEN
+    """
+
+    __slots__ = ("code",)
+
+    RESET: str = f"{_PREFIX}0m"
+
+    def __init__(self, fmt: Self | RawColor | str = "", *, code: str = "") -> None:
+        """
+        Create a Color based on either the format or code, exactly one must be passed
+        :param fmt: A Color, RawColor, or string representation of this desired color
+        :param code: The ansi color code this object represents
+        """
+        if fmt != "" and code != "":
+            raise ValueError("code and fmt may not both be passed")
+        if code:
+            if not code.startswith(_PREFIX) or not code.endswith("m"):
+                raise ValueError("Invalid ansi color code")
+            self.code: str = code
+        elif isinstance(fmt, RawColor):
+            self.code = f"{_PREFIX}{fmt.value}m"
+        else:
+            self.code = _parse_color(fmt) if isinstance(fmt, str) else fmt.code
+
+    def __call__(self, string: str) -> str:
+        """
+        :return: The string color codes with the given ansi code
+        """
+        return f"{self.code}{string}{self.RESET}"
+
+    def __add__(self, other: Self) -> Self:
+        """
+        :return: A new color made by concatenating these two
+        """
+        if not isinstance(other, type(self)):
+            raise TypeError("Cannot add non-Color to Color")
+        return type(self)(code=f"{self.code[:-1]};{other.code[len(_PREFIX):]}")
+
+    def __repr__(self) -> str:
+        """
+        :return: The ansi color code this object represents
+        """
+        return f"<Color {repr(self.code)}>"
+
+    @classmethod
+    def factory(
+        cls, *, foreground: RawColor | None = None, background: RawColor | None = None, **modifiers
+    ) -> Self:
+        """
+        :return: The Ansi given the chosen color and various modifiers
+        """
+        return cls(code=_generate_code(foreground, background, modifiers))
+
+
+def _generate_code(
+    foreground: RawColor | None, background: RawColor | None, modifiers: dict[str, bool]
+) -> str:
+    """
+    :return: The Ansi given the chosen color and various modifiers
+    """
+    if any(bad := [i for i in modifiers if i not in MODIFIERS]):
+        raise ValueError(f"Unknown modifier(s): {bad}")
+    modifiers = {i: modifiers.get(i, False) for i in MODIFIERS}
+    raw = (MODIFIERS.index(i) + 1 for i, k in modifiers.items() if k)
+    ints = [i + (0 if i < 6 else 1) for i in raw]  # Ansi skips 6 for some reason
+    if foreground:
+        ints.append(foreground.value)
+    if background:
+        ints.append(background.value)
+    return f"{_PREFIX}{';'.join(str(i) for i in ints)}m"
+
+
+@cache
+def _parse_color(item: str) -> str:
+    """
+    Construct a color following the rules defined by Color
+    This method is not a classmethod since python3.13 deprecates mixing classmethod and cache
+    """
+    item = item.lower()
+    if "bright_bg" in item:
+        raise ValueError("bg_ must precede bright_ in color specification")
+    pat = f"(:?bright_)?({'|'.join(list(PureColor.__members__))})"
+    shx = re.findall(f"(bg_){pat}", item)
+    if len(shx) > 1:
+        raise ValueError(f"Multiple background colors specified in {item}")
+    bg: RawColor | None = None
+    if len(shx) == 1:
+        item = item.replace("".join(shx[0]), "")
+        bg = RawColor(shx[0][-1], bright="bright_" in shx[0], background=True)
+    shx = re.findall(pat, item)
+    if len(shx) > 1:
+        raise ValueError(f"Multiple foreground colors specified in {item}")
+    fg: RawColor | None = None
+    if len(shx) == 1:
+        item = item.replace("".join(shx[0]), "")
+        fg = RawColor(shx[0][-1], bright="bright_" in shx[0])
+    # Determine modifiers and construct the color
+    attrs = [i for i in item.split("_") if i]
+    if any(bad := [i for i in attrs if i not in MODIFIERS]):
+        raise ValueError(f"Unknown modifiers(s): {', '.join(bad)}")
+    return _generate_code(fg, bg, {i: True for i in MODIFIERS if i in attrs})

zstdlib-0.0.2/zstdlib/enum.py

@@ -0,0 +1,57 @@
+import collections
+
+
+def _not_implemented(*_, **__):
+    raise NotImplementedError("Cannot instantiate this class")
+
+
+class EnumType(type):
+    """
+    Metaclass for uninstantiable Enum classes with required annotations and unique values
+    Enum values may not be prefixed with _
+    These 'Enum' classes may not be modified after creation
+    """
+
+    def __new__(mcs, name, bases, attrs, **kwargs):
+        # Disallow instantiation
+        for bad in ("__init__", "__new__"):
+            if bad in attrs:
+                raise AttributeError("Cannot define __init__ or __new__")
+            attrs[bad] = _not_implemented
+        # Check annotations
+        public = {i: k for i, k in attrs.items() if not i.startswith("__")}
+        annotations = attrs.get("__annotations__", {})
+        eok = kwargs.pop("empty_ok", False)
+        if not public and not annotations:
+            if not eok:
+                raise ValueError("Enum type is empty")
+        if bad := (pub_set := set(public)) - (an_set := set(annotations)):
+            raise ValueError(f"All enum entries must be type annotated: {bad}")
+        if bad := an_set - pub_set:
+            raise ValueError(f"All type annotated entries must have a value: {bad}")
+        for i, typ in annotations.items():
+            if not isinstance(attrs[i], typ):
+                raise TypeError(f"{i} is not of type {typ}")
+        # Disallow duplicate values
+        counts = collections.Counter(public.values())
+        if dups := {i: k for i, k in public.items() if counts[k] > 1}:
+            raise ValueError(f"Duplicate values: {dups}")
+        # Construct class
+        return type.__new__(mcs, name, bases, attrs, **kwargs)
+
+    # Disallow modification
+
+    def __delattr__(cls, *_):
+        raise AttributeError("This class cannot be modified")
+
+    def __setattr__(cls, *_):
+        raise AttributeError("This class cannot be modified")
+
+
+class Enum(metaclass=EnumType, empty_ok=True):
+    """
+    A uninstantiable Enum base type
+    Subclasses must provide type-annotated fields with unique values
+    Fields may not be prefixed with "_"
+    Derived classes will not be modifiable
+    """

zstdlib-0.0.2/zstdlib/log/__init__.py

@@ -0,0 +1,2 @@
+from .cute import CuteFormatter
+from . import trace

zstdlib-0.0.2/zstdlib/log/cute.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+from logging import CRITICAL, ERROR, WARNING, INFO, DEBUG, Formatter
+from traceback import format_exception
+from typing import TYPE_CHECKING
+from zlib import adler32
+from copy import copy
+
+from ..ansi import PureColor, RawColor, Color
+
+if TYPE_CHECKING:
+    from logging import LogRecord
+
+
+class CuteFormatter(Formatter):
+    """
+    A log formatter that can print log messages with colors.
+    """
+
+    __slots__ = ("colored", "_color", "_cmap", "_name_width")
+
+    def __init__(
+        self,
+        colors: dict[str, Color] | None = None,
+        *,
+        colored: bool = True,
+        name_width: int = 12,
+        fmt="%(cute_levelname)s | %(cute_time)s | %(cute_name)s | %(cute_message)s%(cute_exc)s",
+        **kwargs,
+    ):
+        """
+        log_colors may be overridden, for example, trace logs are printed dimly
+        Do not modify cute_ parameters in the fmt string; they might have special formatting that is not visible
+        Ex. %(cute_name)-8s should be done via name_width, that takes into account 0-width color codes
+        :param colors: The colors to use for the given loggers, automatic for non-specified loggers
+        :param colored: If False, no colors will be used regardless of the colors parameter
+        :param fmt: The format string to use for the log message; do not modify cute_ parameters
+        :param name_width: How wide the column containing the logger name should be (minus padding)
+        :param kwargs: Passed to logging.Formatter
+        """
+        super().__init__(fmt=fmt, **kwargs)
+        self._cmap: dict[str, Color] = {}
+        if colors is not None:
+            self.update(colors)
+        self._name_width = name_width
+        self.colored: bool = colored
+
+    def update(self, colors: dict[str, Color]):
+        """
+        Set the colors for all loggers; enables colors if disabled
+        """
+        self._cmap.update(colors)
+
+    def format(self, record: LogRecord) -> str:
+        level: str = record.levelname.ljust(8)
+        when = self.formatTime(record, self.datefmt).ljust(23)
+        name: str = record.name.ljust(self._name_width)
+        message: str = record.getMessage()
+        if self.colored:
+            # Color level
+            if record.levelno >= CRITICAL:
+                level = Color.bright_red_bg_yellow(level)
+            elif record.levelno >= ERROR:
+                level = Color.red(level)
+            elif record.levelno >= WARNING:
+                level = Color.yellow(level)
+            elif record.levelno >= INFO:
+                level = Color.blue(level)
+            elif record.levelno < DEBUG:
+                level = Color.dim(level)
+            # Color text
+            if (col := self._cmap.get(record.name, None)) is None:
+                c: int = adler32(record.name.encode()) % 7
+                col = Color(RawColor(PureColor.black.value + c)) if c != 0 else Color.default
+            if record.levelno < DEBUG:
+                col += Color.dim
+            message = col(message)
+            name = col(name)
+            # Color timestamp
+            if record.levelno < DEBUG:
+                when = Color.dim(when)
+        # Create an updated record then format that
+        new = copy(record)
+        new.__dict__.update(
+            {
+                "cute_levelname": level,
+                "cute_time": when,
+                "cute_name": name,
+                "cute_message": message,
+                "cute_exc": ("\n" + "".join(format_exception(*new.exc_info))[:-1]) if new.exc_info else "",
+            }
+        )
+        return super().format(new)

zstdlib-0.0.2/zstdlib/log/trace.py

@@ -0,0 +1,84 @@
+from threading import Lock
+import logging
+
+
+class _State:
+    start: bool = False
+    ready: bool = False
+    lock = Lock()
+
+    def __init__(self):
+        raise NotImplementedError()
+
+
+def install(*, value=logging.DEBUG // 2, force: bool = False) -> None:
+    """
+    Install TRACE, logging.trace, getLogger().trace, etc into the logging module
+    :param value: The TRACE log level; default: logging.DEBUG // 2
+    :param force: If true, force install most errors
+    """
+    with _State.lock:
+        _install(value, force)
+
+
+# Helpers
+
+
+def _define_logger_trace(lc: type, method: str, value: int) -> None:
+    # Define the function in the logger class, match name and help method style
+    def trace(self, msg, *args, **kwargs) -> None:
+        """
+        Log 'msg % args' with severity 'TRACE'.
+
+        To pass exception information, use the keyword argument exc_info with
+        a true TRACE, e.g.
+
+        logger.trace("Houston, we have a %s", "tiny problem", exc_info=True)
+        """
+        self.log(value, msg, *args, **kwargs)
+
+    setattr(lc, method, trace)
+
+
+def _define_logging_trace(method: str, value: int) -> None:
+    # Define the function in the logging module, match name and help method style
+    def trace(msg, *args, **kwargs):
+        """
+        Log a message with severity 'TRACE' on the root logger. If the logger
+        has no handlers, call basicConfig() to add a console handler with a
+        pre-defined format.
+        """
+        logging.log(value, msg, *args, **kwargs)
+
+    setattr(logging, method, trace)
+
+
+def _error_check(value: int, lgc: type, name: str, method: str) -> None:
+    if not 0 < value < logging.DEBUG:
+        raise ValueError(f"value should be within: 0 < value < {logging.DEBUG}")
+    if _State.ready:
+        raise RuntimeError("Already installed trace")
+    if _State.start:
+        raise RuntimeError("Incomplete install detected")
+    if hasattr(logging, name):
+        raise AttributeError(f"logging module already has {name} defined")
+    if hasattr(logging, method):
+        raise AttributeError(f"logging module already has {method} defined")
+    if hasattr(lgc, method):
+        raise AttributeError(f"logging.getLoggerClass() class already has {method} defined")
+
+
+def _install(value: int, force: bool) -> None:
+    lgc = logging.getLoggerClass()
+    method = "trace"
+    name = method.upper()
+    # Error check
+    if not force:
+        _error_check(value, lgc, name, method)
+    _State.start = True
+    # Add trace into the logging moule
+    logging.addLevelName(value, name)
+    setattr(logging, name, value)
+    _define_logging_trace(method, value)
+    _define_logger_trace(lgc, method, value)
+    _State.ready = True

zstdlib-0.0.2/zstdlib/singleton.py

@@ -0,0 +1,60 @@
+from threading import Condition, RLock
+from typing import Any
+
+
+class SingletonType(type):
+    """
+    A thread-safe singleton metaclass
+    """
+
+    _seen: set[type] = (
+        set()
+    )  # Objects in this have been seen by singleton before and should not be constructed again
+    _instances: dict[type, Any] = {}  # Fully constructed singleton objects
+    _lock = Condition()
+    # For preventing subclassing of Singletons
+    _types: list[type] = []
+    _types_lock = RLock()
+
+    def __new__(mcs, name, bases, attrs, **kwargs):
+        """
+        Intercept all class definitions to prevent subclassing singleton types except for Singleton
+        """
+        if "__init_subclass__" in attrs:
+            raise NotImplementedError("Singleton's should not be subclassed")
+
+        def _init_subclass(cls):
+            with mcs._types_lock:
+                if any(issubclass(cls, i) for i in mcs._types if i is not Singleton):
+                    err = "Do not derive from Singletons other than the base Singleton type"
+                    raise NotImplementedError(err)
+                mcs._types.append(cls)
+
+        attrs["__init_subclass__"] = _init_subclass
+        ret = super().__new__(mcs, name, bases, attrs, **kwargs)
+        with mcs._types_lock:
+            mcs._types.append(ret)
+        return ret
+
+    def __call__(cls, *args, **kwargs):
+        """
+        Intercept all instantiations to ensure at most one instance exists
+        """
+        # If the object has been seen before, wait for it to be available then return it
+        with cls._lock:
+            if cls in cls._seen:
+                cls._lock.wait_for(lambda: cls in cls._instances)
+                return cls._instances[cls]
+            cls._seen.add(cls)
+        # The object has not been constructed before, create it outside of any lock to avoid delays
+        obj = super().__call__(*args, **kwargs)
+        with cls._lock:
+            cls._instances[cls] = obj
+            cls._lock.notify_all()  # Notify other threads of the new object
+            return obj
+
+
+class Singleton(metaclass=SingletonType):
+    """
+    A thread-safe singleton base class
+    """

{zstdlib-0.0.1 → zstdlib-0.0.2/zstdlib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zstdlib
-Version: 0.0.1
+Version: 0.0.2
 Summary: A set of useful python utilities
 License: GPLv3
 Project-URL: Homepage, https://github.com/zwimer/zstdlib
@@ -12,3 +12,6 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+
+# zstdlib
+A set of useful python utilities

zstdlib-0.0.2/zstdlib.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+pyproject.toml
+tests/__init__.py
+tests/test_ansi.py
+tests/test_enum.py
+tests/test_singleton.py
+tests/log/__init__.py
+tests/log/base.py
+tests/log/test_cute.py
+tests/log/test_trace.py
+zstdlib/__init__.py
+zstdlib/ansi.py
+zstdlib/enum.py
+zstdlib/py.typed
+zstdlib/singleton.py
+zstdlib.egg-info/PKG-INFO
+zstdlib.egg-info/SOURCES.txt
+zstdlib.egg-info/dependency_links.txt
+zstdlib.egg-info/top_level.txt
+zstdlib/log/__init__.py
+zstdlib/log/cute.py
+zstdlib/log/trace.py

{zstdlib-0.0.1 → zstdlib-0.0.2}/zstdlib.egg-info/top_level.txt

@@ -1 +1,2 @@
+tests
 zstdlib

zstdlib-0.0.1/zstdlib/__init__.py

@@ -1,5 +0,0 @@
-__version__ = "0.0.1"
-
-from .singleton import Singleton
-from .enum import UEnum
-from . import trace

zstdlib-0.0.1/zstdlib/enum.py

@@ -1,32 +0,0 @@
-# pylint: disable=bad-mcs-method-argument,bad-mcs-classmethod-argument
-class UEnum(type):
-    """
-    Metaclass for non-instantiable Enum classes with unique values
-    These 'Enum' classes may not be modified after creation
-    """
-
-    def __new__(mcls, name, bases, attrs, **kwargs):
-        def _ni(*_, **__):
-            raise NotImplementedError("Cannot instantiate this class")
-
-        # Disallow instantiation
-        for bad in ("__init__", "__new__"):
-            if bad in attrs:
-                raise ValueError("Cannot define __init__ or __new__")
-            attrs[bad] = _ni
-        # Disallow duplicate values
-        values = set()
-        for v in (k for i, k in attrs.items() if not i.startswith("__")):
-            if v in values:
-                raise ValueError(f"Duplicate value: {v}")
-            values.add(v)
-        # Construct class
-        return type.__new__(mcls, name, bases, attrs, **kwargs)
-
-    # Disallow modification
-
-    def __delattr__(self, *_):
-        raise AttributeError("This class cannot be modified")
-
-    def __setattr__(self, *_):
-        raise AttributeError("This class cannot be modified")

zstdlib-0.0.1/zstdlib/singleton.py

@@ -1,28 +0,0 @@
-from threading import Condition
-from typing import Any
-
-
-class Singleton(type):
-    """
-    A thread-safe singleton metaclass
-    """
-
-    _seen: set[type] = (
-        set()
-    )  # Objects in this have been seen by singleton before and should not be constructed again
-    _instances: dict[type, Any] = {}  # Fully constructed singleton objects
-    _lock = Condition()
-
-    def __call__(cls, *args, **kwargs):
-        # If the object has been seen before, wait for it to be available then return it
-        with cls._lock:
-            if cls in cls._seen:
-                cls._lock.wait_for(lambda: cls in cls._instances)
-                return cls._instances[cls]
-            cls._seen.add(cls)
-        # The object has not been constructed before, create it outside of any lock to avoid delays
-        obj = super().__call__(*args, **kwargs)
-        with cls._lock:
-            cls._instances[cls] = obj
-            cls._lock.notify_all()  # Notify other threads of the new object
-            return obj

zstdlib-0.0.1/zstdlib/trace.py

@@ -1,55 +0,0 @@
-import logging
-
-
-def _define_logger_trace(LC: type, method: str, TRACE: int):
-    # Define the function in the logger class, match name and help method style
-    def trace(self, msg, *args, **kwargs) -> None:
-        """
-        Log 'msg % args' with severity 'TRACE'.
-
-        To pass exception information, use the keyword argument exc_info with
-        a true TRACE, e.g.
-
-        logger.trace("Houston, we have a %s", "tiny problem", exc_info=True)
-        """
-        self.log(TRACE, msg, *args, **kwargs)
-
-    setattr(LC, method, trace)
-
-
-def _define_logging_trace(method: str, TRACE: int):
-    # Define the function in the logging module, match name and help method style
-    def trace(msg, *args, **kwargs):
-        """
-        Log a message with severity 'TRACE' on the root logger. If the logger
-        has no handlers, call basicConfig() to add a console handler with a
-        pre-defined format.
-        """
-        logging.log(TRACE, msg, *args, **kwargs)
-
-    setattr(logging, method, trace)
-
-
-def install() -> None:
-    """
-    Install TRACE, logging.trace, getLogger().trace, etc into the logging module
-    """
-    if logging.DEBUG < 2:
-        raise ValueError("logging.DEBUG is too small")
-    TRACE: int = logging.DEBUG // 2
-    name = "TRACE"
-    method = name.lower()
-
-    # Error check
-    if hasattr(logging, name):
-        raise AttributeError(f"logging module already has {name} defined")
-    if hasattr(logging, method):
-        raise AttributeError(f"logging module already has {method} defined")
-    if hasattr(LC := logging.getLoggerClass(), method):
-        raise AttributeError(f"logging.getLoggerClass() class already has {method} defined")
-
-    # Add trace into the logging moule
-    logging.addLevelName(TRACE, name)
-    setattr(logging, name, TRACE)
-    _define_logger_trace(LC, method, TRACE)
-    _define_logging_trace(method, TRACE)

zstdlib-0.0.1/zstdlib.egg-info/SOURCES.txt

@@ -1,11 +0,0 @@
-LICENSE
-pyproject.toml
-zstdlib/__init__.py
-zstdlib/enum.py
-zstdlib/py.typed
-zstdlib/singleton.py
-zstdlib/trace.py
-zstdlib.egg-info/PKG-INFO
-zstdlib.egg-info/SOURCES.txt
-zstdlib.egg-info/dependency_links.txt
-zstdlib.egg-info/top_level.txt