zstdlib 0.0.9__tar.gz → 0.1.0__tar.gz

{zstdlib-0.0.9 → zstdlib-0.1.0}/PKG-INFO

@@ -1,17 +1,18 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: zstdlib
-Version: 0.0.9
+Version: 0.1.0
 Summary: A set of useful python utilities
 License: GPLv3
 Project-URL: Homepage, https://github.com/zwimer/zstdlib
 Keywords: remote,pipe
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Dynamic: license-file
 
 # zstdlib
 A set of useful python utilities

{zstdlib-0.0.9 → zstdlib-0.1.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "zstdlib"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.12",
     "Development Status :: 5 - Production/Stable",
     "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
 ]
@@ -14,7 +14,7 @@ keywords = ["remote", "pipe"]
 license = {text = "GPLv3"}
 description = "A set of useful python utilities"
 urls = {Homepage = "https://github.com/zwimer/zstdlib"}
-requires-python = ">= 3.10"
+requires-python = ">= 3.12"
 # dependencies = [
 #     # Client
 #     "zstandard[cffi]",
@@ -63,7 +63,7 @@ disable = [
 
 [tool.black]
 line-length = 110
-target-version = ["py310", "py311", "py312", "py313"]
+target-version = ["py312", "py313"]
 
 [tool.ruff]
 line-length = 110

{zstdlib-0.0.9 → zstdlib-0.1.0}/tests/test_enum.py

@@ -63,9 +63,9 @@ class TestEnumType(unittest.TestCase):
         class ET10(metaclass=EnumType):
             arg1: int = 0
 
-        with self.assertRaises(NotImplementedError):
+        with self.assertRaises(TypeError):
             ET10()
-        with self.assertRaises(NotImplementedError):
+        with self.assertRaises(TypeError):
             ET10.__init__({})
 
 
@@ -127,9 +127,9 @@ class TestEnum(unittest.TestCase):
         class E10(Enum):
             arg1: int = 0
 
-        with self.assertRaises(NotImplementedError):
+        with self.assertRaises(TypeError):
             E10()
-        with self.assertRaises(NotImplementedError):
+        with self.assertRaises(TypeError):
             E10.__init__({})
 
 

{zstdlib-0.0.9 → zstdlib-0.1.0}/tests/test_frozen.py

@@ -28,6 +28,7 @@ class TestFreezable(unittest.TestCase):
             f1.a = 2
         with self.assertRaises(AttributeError):
             del f1.a
+        f1.freeze()  # Should not raise an error
 
     def test_thaw(self):
         class F1(Freezable):
@@ -49,13 +50,30 @@ class TestFreezable(unittest.TestCase):
 
         f1 = F1()
         f1.a = 1
+        f1.freeze()  # To ensure that .freeze(permanent=True) works when already frozen too
         f1.freeze(permanent=True)
+        f1.freeze(permanent=True)  # Should not raise an error
         self.assertEqual(f1.a, 1)
         with self.assertRaises(RuntimeError):
             f1.thaw()
         with self.assertRaises(AttributeError):
             f1.a = 1
 
+    def test_properties(self):
+
+        class F1(Freezable):
+            pass
+
+        f1 = F1()
+        self.assertFalse(f1.frozen)
+        self.assertTrue(f1.thawable)
+        f1.freeze()
+        self.assertTrue(f1.frozen)
+        self.assertTrue(f1.thawable)
+        f1.freeze(permanent=True)
+        self.assertTrue(f1.frozen)
+        self.assertFalse(f1.thawable)
+
 
 class TestFrozen(unittest.TestCase):
 
@@ -77,35 +95,35 @@ class TestFrozen(unittest.TestCase):
 
     def test_metadata(self):
         @frozen
-        class F2:
+        class F1:
             def __init__(self, a: int = 1, *, b: bool = False) -> None:
                 """
                 init doc
                 """
 
-        f2 = F2()
-        self.assertEqual(f2.__init__.__doc__.strip(), "init doc")
-        self.assertEqual(f2.__init__.__name__, "__init__")
-        self.assertEqual(f2.__init__.__qualname__, "TestFrozen.test_metadata.<locals>.F2.__init__")
-        self.assertTupleEqual(f2.__init__.__defaults__, (1,))
-        self.assertDictEqual(f2.__init__.__kwdefaults__, {"b": False})
-        self.assertDictEqual(f2.__init__.__annotations__, {"a": int, "b": bool, "return": None})
+        f1 = F1()
+        self.assertEqual(f1.__init__.__doc__.strip(), "init doc")
+        self.assertEqual(f1.__init__.__name__, "__init__")
+        self.assertEqual(f1.__init__.__qualname__, "TestFrozen.test_metadata.<locals>.F2.__init__")
+        self.assertTupleEqual(f1.__init__.__defaults__, (1,))
+        self.assertDictEqual(f1.__init__.__kwdefaults__, {"b": False})
+        self.assertDictEqual(f1.__init__.__annotations__, {"a": int, "b": bool, "return": None})
 
     def test_frozen_custom(self):
         @frozen("custom")
-        class F3:
+        class F1:
             def __init__(self):
                 self.a = 1
 
             def custom(self):
                 self.a = 2
 
-        f3 = F3()
-        self.assertEqual(f3.a, 1)
-        f3.custom()
-        self.assertEqual(f3.a, 2)
+        f1 = F1()
+        self.assertEqual(f1.a, 1)
+        f1.custom()
+        self.assertEqual(f1.a, 2)
         with self.assertRaises(AttributeError):
-            f3.a = 1
+            f1.a = 1
 
 
 if __name__ == "__main__":

zstdlib-0.1.0/tests/test_io.py

@@ -0,0 +1,90 @@
+import tempfile
+import unittest
+
+from zstdlib.io import ProtectedFile, BinaryIO, TextIO, io
+
+
+class RamFile(tempfile.SpooledTemporaryFile):
+    """
+    A file-like object that stores its contents in memory.
+    """
+
+    rollover = None  # type: ignore
+
+    def __init__(self, *args, mode: str = "w+", **kwargs):
+        super().__init__(10**9, *args, mode=mode, **kwargs)
+
+    def load(self, x):
+        self.write(x)
+        self.flush()
+        self.seek(self.tell() - len(x))
+
+
+class TestIO(unittest.TestCase):
+
+    def test_init(self):
+        with RamFile(mode="wb+") as fb, RamFile() as fs:
+            ts = TextIO(fs)
+            tb = BinaryIO(fb)
+            with self.assertRaises(TypeError):
+                TextIO(fb)
+            with self.assertRaises(TypeError):
+                BinaryIO(fs)
+            self.assertIs(ts, io(fs))
+            self.assertIs(tb, io(fb))
+
+    def test_protected_file(self):
+        with RamFile() as f:
+            p = ProtectedFile(f)
+            self.assertIs(f, p.raw)
+            self.assertIs(f.mode, p.mode)
+            for i in ("read", "readline", "readlines", "readall", "seek"):
+                with self.assertRaises(AttributeError):
+                    getattr(p, i)
+
+    def test_unread(self):
+        with RamFile() as raw:
+            f = io(raw)
+            f.unread("hello")
+            self.assertEqual("hello", f._buffer)
+
+    def test_read(self):
+        with RamFile() as raw:
+            raw.load("foobaz")
+            f = io(raw)
+            # Test read of file
+            self.assertEqual("fo", f.read(2))
+            self.assertEqual("o", f.read(1))
+            # Test read of buffer
+            f.unread("bar")
+            self.assertEqual("b", f.read(1))
+            # Test read of file + buffer
+            f.unread("foob")
+            self.assertEqual("foobar", f.read(6))
+            f.unread("foobar")
+            self.assertEqual("foobarbaz", f.read())
+
+    def test_peek(self):
+        with RamFile() as raw:
+            f = io(raw)
+            f.unread("foo")
+            # Test peek of buffer
+            for i in range(3):
+                self.assertEqual("fo", f.peek(2))
+            self.assertEqual("foo", f.read())
+            # Test peek of file
+            raw.load("bar")
+            for i in range(3):
+                self.assertEqual("ba", f.peek(2))
+            self.assertEqual("bar", f.read())
+            # Test peek of both
+            f.unread("baz")
+            raw.load("qux")
+            for i in range(3):
+                for k in range(5):
+                    self.assertEqual("bazqu"[:k], f.peek(k))
+            self.assertEqual("bazqux", f.read())
+
+
+if __name__ == "__main__":
+    unittest.main()

zstdlib-0.1.0/tests/test_singleton.py

@@ -0,0 +1,139 @@
+# pylint: disable=missing-module-docstring,missing-class-docstring,missing-function-docstring,unused-variable
+from collections.abc import Callable
+from threading import Thread, Lock
+from datetime import datetime
+from time import sleep
+import unittest
+
+from zstdlib.singleton import NoInstanceError, Singleton
+
+
+class TestSingleton(unittest.TestCase):
+
+    def test_valid(self) -> None:
+        class ST1(Singleton):
+            pass
+
+        class ST2(Singleton):
+            pass
+
+        self.assertIs(ST1(), ST1())
+        self.assertIsNot(ST1(), ST2())
+
+    def test_subclass(self) -> None:
+        class ST1(Singleton):  # Ok to subtype Singleton base class
+            pass
+
+        with self.assertRaises(TypeError):  # Not ok to subtype a subtype of Singleton
+
+            class ST2(ST1):
+                pass
+
+        with self.assertRaises(TypeError):  # Not ok to define __init_subclass__ in Singleton
+
+            class ST3(Singleton):
+                def __init_subclass__(cls, **kwargs):
+                    pass
+
+    def test_instance(self):
+        class ST(Singleton):
+            def __init__(self, _):
+                pass
+
+        self.assertTrue(issubclass(NoInstanceError, TypeError))
+        with self.assertRaises(NoInstanceError):
+            _ = ST.instance()
+        obj = ST(0)
+        self.assertIs(ST.instance(), obj)
+
+        with self.assertRaises(TypeError):
+            ST.instance(4)
+
+    def test_multi_thread(self):
+        """
+        Ensure that Singleton is thread safe and that constructing an object doesn't delay other threads
+        Technically this is more of a heuristic, but failing is extremely unlikely if this is thread safe
+        Verifies that classes can construct concurrently, thread-safely, and only one instance is created
+        """
+
+        # Shared state for threads
+        start = [datetime.now()]
+        lock = Lock()
+        events = []
+        results = []
+
+        # Helper functions that can help define thread tests
+        timestamp = lambda: (datetime.now() - start[0]).total_seconds()
+
+        def mk_cls(cls: type, name: str) -> None:
+            fmt = lambda x: f"{timestamp():.1f}: {name} {x} {cls.__name__}()"
+            events.append(fmt("->"))
+            results.append(cls())
+            events.append(fmt("<-"))
+
+        def simple(name: str, cls: type, delay: float) -> Callable:
+            def _t() -> None:
+                with lock:  # Ensure all threads can start simultaneously
+                    pass
+                sleep(delay)
+                mk_cls(cls, name)
+
+            return _t
+
+        # Run all functions
+        def run_all(*funcs: Callable) -> None:
+            ts = [Thread(target=i) for i in funcs]
+            events.clear()
+            results.clear()
+            with lock:
+                for i in ts:
+                    i.start()
+                # Give threads a moment to construct then let them go
+                sleep(0.2)
+                start[0] = datetime.now()
+            for i in ts:
+                i.join()
+
+        # Verify concurrent construction of ST1 and ST2
+        class Fast(Singleton):
+            def __init__(self):
+                sleep(0.3)
+
+        class Slow(Singleton):
+            def __init__(self):
+                sleep(0.8)
+
+        run_all(simple("f1", Slow, 0), simple("f2", Fast, 0.2))
+        want = [
+            "0.0: f1 -> Slow()",
+            "0.2: f2 -> Fast()",
+            "0.5: f2 <- Fast()",
+            "0.8: f1 <- Slow()",
+        ]
+        self.assertEqual(want, events)
+        self.assertEqual(len(results), 2)
+        self.assertIs(results[0], Fast())
+        self.assertIs(results[1], Slow())
+        del Slow, Fast  # Cleanup, for safety
+
+        # Verify that multiple threads constructing the same class only construct one object
+        class ST(Singleton):
+            first = True
+
+            def __init__(self):
+                if self.first:
+                    self.first = False
+                    sleep(0.4)
+
+        run_all(simple("f1", ST, 0), simple("f2", ST, 0.2))
+        self.assertEqual(len(events), 4)
+        self.assertEqual(events[:2], ["0.0: f1 -> ST()", "0.2: f2 -> ST()"])
+        # When the first thread's init finishes, the second will stop blocking and finish
+        self.assertEqual(len(results), 2)
+        for i in results:
+            self.assertIs(i, ST())
+        del ST  # Cleanup, for safety
+
+
+if __name__ == "__main__":
+    unittest.main()

{zstdlib-0.0.9 → zstdlib-0.1.0}/zstdlib/__init__.py

@@ -1,7 +1,7 @@
-__version__ = "0.0.9"
+__version__ = "0.1.0"
 
 from .not_set import NotSetType, NotSet
 from .frozen import Freezable, frozen
 from .singleton import Singleton
 from .enum import Enum
-from . import log
+from . import log, io

{zstdlib-0.0.9 → zstdlib-0.1.0}/zstdlib/enum.py

@@ -1,10 +1,6 @@
 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
@@ -17,7 +13,7 @@ class EnumType(type):
         for bad in ("__init__", "__new__"):
             if bad in attrs:
                 raise AttributeError("Cannot define __init__ or __new__")
-            attrs[bad] = _not_implemented
+            attrs[bad] = None
         # Check annotations
         public = {i: k for i, k in attrs.items() if not i.startswith("__")}
         annotations = attrs.get("__annotations__", {})

{zstdlib-0.0.9 → zstdlib-0.1.0}/zstdlib/frozen.py

@@ -14,40 +14,53 @@ _FN_ATTRS = (
 
 
 class Freezable:
-    """
-    A base class for objects that can be frozen
-    """
+    """A base class for objects that can be frozen"""
 
     def __init__(self, *args, **kwargs) -> None:
+        # Avoid name mangling b/c we use object.__setattr__ etc. on these
+        # Instead use unlikely to collide names for member variables
         super().__init__(*args, **kwargs)  # For MRO super classes
-        if hasattr(self, "_frozen") or hasattr(self, "_can_thaw"):
-            raise ValueError("Base class defines _frozen or _can_thaw")
-        self._can_thaw: bool = True
-        self._frozen: bool = False
+        if hasattr(self, "_freezable_frozen_") or hasattr(self, "_freezable_can_thaw_"):
+            raise ValueError("Base class defines _freezable_frozen_ or _freezable_can_thaw_")
+        self._freezable_can_thaw_: bool = True
+        self._freezable_frozen_: bool = False
+
+    # Public
+
+    @property
+    def frozen(self) -> bool:
+        """Check if this object is frozen"""
+        return self._freezable_frozen_
+
+    @property
+    def thawable(self) -> bool:
+        """Check if this object can be thawed or is unfrozen"""
+        return self._freezable_can_thaw_
 
     def freeze(self, *, permanent: bool = False):
         """
         Prevent further modifications to this object
+        This function can be called on an already frozen object
         """
         if permanent:
-            self._can_thaw = False
-        self._frozen = True
+            object.__setattr__(self, "_freezable_can_thaw_", False)
+        object.__setattr__(self, "_freezable_frozen_", True)
 
     def thaw(self):
         """
         Allow modifications to this object
         """
-        if not self._can_thaw:
+        if not self._freezable_can_thaw_:
             raise RuntimeError("Cannot thaw permanently frozen object")
-        object.__setattr__(self, "_frozen", False)
+        object.__setattr__(self, "_freezable_frozen_", False)
 
     def __setattr__(self, key: str, value) -> None:
-        if getattr(self, "_frozen", False):
+        if getattr(self, "_freezable_frozen_", False):
             raise AttributeError("Cannot modify frozen object")
         super().__setattr__(key, value)
 
     def __delattr__(self, item: str) -> None:
-        if getattr(self, "_frozen", False):
+        if getattr(self, "_freezable_frozen_", False):  # B/c invoked before __init__ defines _frozen
             raise AttributeError("Cannot modify frozen object")
         super().__delattr__(item)
 
@@ -58,12 +71,13 @@ def frozen(arg: str | type):
     If passed a string, will freeze after the method with that name
     """
 
-    def shim_method(cls: type, name, new) -> None:
+    def shim_method(cls: type, name: str, new: Callable) -> None:
+        """Install shims for _FN_ATTRS; modifies new"""
         original = getattr(cls, name)
-        for i in _FN_ATTRS:
+        for i in _FN_ATTRS:  # Copy attributes of old fn onto new fn
             if hasattr(original, i):
                 setattr(new, i, getattr(original, i))
-        setattr(cls, name, new)
+        setattr(cls, name, new)  # Install
 
     def mk_frozen(cls: type, method: str) -> type:
         original_method: Callable = getattr(cls, method)
@@ -73,16 +87,16 @@ def frozen(arg: str | type):
         def new_method(self, *args, **kwargs):
             ret = original_method(self, *args, **kwargs)
             # pylint: disable=protected-access
-            self._frozen = True  # type: ignore[attr-defined]
+            self._freezable_frozen_ = True  # type: ignore[attr-defined]
             return ret
 
         def __setattr__(self, key: str, value):
-            if getattr(self, "_frozen", False):
+            if getattr(self, "_freezable_frozen_", False):
                 raise AttributeError("Cannot modify frozen object")
             return original_setattr(self, key, value)
 
         def __delattr__(self, item: str):
-            if getattr(self, "_frozen", False):
+            if getattr(self, "_freezable_frozen_", False):
                 raise AttributeError("Cannot modify frozen object")
             return original_delattr(self, item)
 

zstdlib-0.1.0/zstdlib/io.py

@@ -0,0 +1,238 @@
+from io import (
+    IOBase,
+    TextIOBase as _PyRawTextIOBase,
+    RawIOBase as _PyRawIOBase,
+    BufferedIOBase as _PyBufferedIOBase,
+)
+from threading import RLock
+from itertools import chain
+from typing import Self
+import weakref
+
+
+__all__ = ("TextIO", "BinaryIO", "io")
+
+type _BinaryBase = _PyRawIOBase | _PyBufferedIOBase
+type _TextBase = _PyRawTextIOBase
+
+
+class ProtectedFile:
+    """
+    A wrapper around an IO object that prevents access to certain attributes
+    If absolutely necessary, users can access the raw object directly via .raw
+    """
+
+    PROTECTED_PREFIXES = ("read", "seek", "getbuffer", "getvalue", "detach")
+    __slots__ = ("raw",)
+
+    def __init__(self, raw: IOBase) -> None:
+        """
+        :param raw: The raw IO object to wrap, users can access it directly if they must
+        """
+        self.raw: IOBase = raw
+
+    def __getattr__(self, item):
+        """
+        Prevent access to certain attributes
+        """
+        if any(item.startswith(i) for i in self.PROTECTED_PREFIXES):
+            raise AttributeError(f"Attribute {item} is protected")
+        return getattr(self.raw, item)
+
+    def __hash__(self) -> int:
+        return hash(self.raw)
+
+
+# See bug: https://github.com/pylint-dev/pylint/issues/9335
+# pylint: disable=undefined-variable
+class _IOWrapperBase[T: (str, bytes)]:
+    """
+    A base class for IO objects that adds additional functionality such as readuntil, unread, and peek
+    These classes are singletons with respect to their input object
+    Note: This class takes ownership of the input object, do not use it elsewhere
+    """
+
+    __slots__ = ("lock", "f", "_buffer", "_eof")
+    _instances: weakref.WeakKeyDictionary[IOBase, Self] = weakref.WeakKeyDictionary()
+    _wr_lock = RLock()
+
+    def __new__(cls, f: IOBase, binary: bool) -> Self:
+        """
+        Create a new instance of cls for raw, or return an existing instance if one exists
+        """
+        with cls._wr_lock:
+            if (ret := cls._instances.get(f, None)) is None:
+                cls._instances[f] = (ret := super().__new__(cls))
+        return ret
+
+    def __init__(self, f: IOBase, *, binary: bool) -> None:
+        """
+        Initialize the IO object with a raw IO object
+        Note: This class takes ownership of the input object, do not use it elsewhere
+        :param f: The raw IO object to wrap
+        :param binary: If True, the IO object will read/write bytes, otherwise it will read/write strings
+        """
+        self._buffer: T = (bytes if binary else str)()  # type: ignore
+        self.f = ProtectedFile(f)
+        self.lock = RLock()
+
+    def read(self, size: int = -1) -> T:
+        """
+        Read up to size characters from self.raw or until EOF
+        If size is unspecified or -1, read until EOF
+        """
+        if size == 0:
+            return self._buffer[:0]
+        with self.lock:
+            ret = self._read_buffer(size)
+            if len(ret) == size:
+                return ret
+            ret += self._read(-1 if size == -1 else (size - len(ret)))
+        return ret
+
+    def readline(self) -> T:
+        """
+        Read a line from self.raw or until EOF
+        Newline is included in the return value
+        """
+        with self.lock:
+            nl: T = "\n" if isinstance(self._buffer, str) else b"\n"
+            ret = self._read_buffer(self._buffer.find(nl)) + self._read_buffer(1)
+            if ret.endswith(nl):
+                return ret
+            return ret + self.f.raw.readline()  # type: ignore
+
+    def readlines(self) -> list[T]:
+        """
+        Read all lines from self.raw until EOF
+        """
+        with self.lock:
+            ret: list[T] = []
+            while add := self.readline():
+                ret.append(add)
+            return ret
+
+    def peek(self, size: int = -1) -> T:
+        """
+        Read size characters from self.raw or until EOF, without consuming the data
+        """
+        with self.lock:
+            self.unread(ret := self.read(size))
+        return ret
+
+    def unread(self, data: T) -> None:
+        """
+        Unread data back to the internal buffer
+        """
+        with self.lock:
+            self._buffer = data + self._buffer
+
+    def readuntil(self, until: T, *, eof_ok: bool = True) -> T:
+        """
+        Read until until is found in f. If eof_ok is False, raise EOFError if until is not found before EOF.
+        :param until: The str/bytes to read until
+        :param inclusive: If True, the returned value will end with until
+        :param eof_ok: if False, raise EOFError if until is not found before EOF
+        :return: The data read from self.raw, up to and including until
+        """
+        if isinstance(until, str) ^ isinstance(self._buffer, str):
+            raise TypeError("until: expected same type as buffer")
+        if len(until) == 0:
+            raise ValueError("until may not be empty")
+        with self.lock:
+            if until in self._buffer:
+                return self._read_buffer(self._buffer.find(until) + len(until))
+            buffer = [self._read_buffer()]
+            # Use bytearray to avoid multiple concatenations
+            # Read until until is found, avoid small read() syscall's because they are slow
+            while (n := self._remainder(buffer, until)) and (add := self._read(n)):
+                buffer.append(add)
+            ret = buffer[0][:0].join(buffer)
+            if not ret.endswith(until) and not eof_ok:
+                raise EOFError("until: not found before EOF")
+            return ret
+
+    #
+    # Helper functions
+    #
+
+    def _read(self, size) -> T:
+        ret: T = self.f.raw.read(size)  # type: ignore
+        return ret if ret else self._buffer[:0]  # Some .read's can return None
+
+    def _read_buffer(self, size: int = -1) -> T:
+        if size == -1:
+            size = len(self._buffer)
+        ret: T = self._buffer[:size]
+        self._buffer = self._buffer[size:]
+        return ret
+
+    @staticmethod
+    def _remainder(data: list[T], suffix: T) -> int:
+        assert suffix, "suffix: expected non-empty str or bytes"
+        rev = chain.from_iterable(reversed(i) for i in reversed(data))
+        for index, (i, k) in enumerate(zip(rev, reversed(suffix))):
+            if i != k:
+                return len(suffix) - index
+        return 0
+
+    #
+    # Protection
+    #
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, self.f))
+
+    __deepcopy__ = None  # type: ignore
+    __copy__ = None  # type: ignore
+
+
+def _mode(f: IOBase, binary: bool | None) -> bool:
+    mode = getattr(f, "mode", "")
+    binary = binary or "b" in mode or isinstance(f, (_PyRawIOBase, _PyBufferedIOBase))
+    text = (binary is False) or (mode and "b" not in mode) or isinstance(f, _PyRawTextIOBase)
+    if not text and not binary:
+        raise TypeError("Cannot determine if IO object is text or binary")
+    if text and binary:
+        raise TypeError("IO object is both text and binary")
+    return text
+
+
+class TextIO(_IOWrapperBase[str]):
+    """
+    A wrapper around TextIO objects that add additional functionality such as readuntil, unread, and peek
+    """
+
+    def __new__(cls, f: IOBase):
+        if not _mode(f, binary=False):
+            raise TypeError("raw should be a non-binary IO object")
+        return super().__new__(cls, f, binary=False)
+
+    def __init__(self, f: IOBase):
+        super().__init__(f, binary=False)
+
+
+class BinaryIO(_IOWrapperBase[bytes]):
+    """
+    A wrapper around BinaryIO objects that add additional functionality such as readuntil, unread, and peek
+    """
+
+    def __new__(cls, f: IOBase):
+        if _mode(f, binary=True):
+            raise TypeError("raw should be a binary IO object")
+        return super().__new__(cls, f, binary=True)
+
+    def __init__(self, f: IOBase):
+        super().__init__(f, binary=False)
+
+
+def io(raw: IOBase, binary: bool | None = None) -> TextIO | BinaryIO:
+    """
+    Convert an IO object to a TextIO or BinaryIO object
+        For raw to be valid, one of the three must be true:
+        1. raw is an io.TextIOBase, io.RawIOBase, or io.BufferedIOBase object
+        2. raw has a .mode string attribute
+        3. binary must be set
+    If the three detection methods disagree on if raw is binary, a TypeError is raised
+    """
+    return TextIO(raw) if _mode(raw, binary) else BinaryIO(raw)

{zstdlib-0.0.9 → zstdlib-0.1.0}/zstdlib/log/trace.py

@@ -3,13 +3,11 @@ import logging
 
 
 class _State:
+    __init__ = None  # type: ignore
     start: bool = False
     ready: bool = False
     lock = Lock()
 
-    def __init__(self):
-        raise NotImplementedError()
-
 
 def install(*, value=logging.DEBUG // 2, force: bool = False) -> None:
     """

zstdlib-0.1.0/zstdlib/singleton.py

@@ -0,0 +1,80 @@
+from typing import TypeVar, Self, Any, cast
+from collections import defaultdict
+from threading import RLock
+from functools import cache
+
+
+T = TypeVar("T")
+
+
+class _None:
+    """A unique NoneType"""
+
+
+class NoInstanceError(TypeError):
+    """A TypeError raised when trying to get a Singleton instance before constructing it"""
+
+
+def _no_subclass(*_, **__):
+    raise TypeError("Singleton subclasses may not be subclassed")
+
+
+class _SingletonType(type):
+    """
+    A thread-safe singleton metaclass
+    Singleton types may not be subclassed except for the base Singleton type
+    """
+
+    _disallow_init_subclass = False  # If True, disallow __init_subclass__ in __new__'s attrs
+    _instances: dict[type, Any] = {}  # Fully constructed and initialized singleton types
+    # Lock is preferred to RLock, but could deadlock if user write a constructor that invokes itself
+    _cls_locks: dict[type, RLock] = defaultdict(RLock)
+    _lock = RLock()
+
+    def __new__(mcs, name, bases, attrs, **kwargs):
+        """Define a new Singleton type"""
+        ret = super().__new__(mcs, name, bases, attrs, **kwargs)
+        if mcs._disallow_init_subclass and "__init_subclass__" in attrs:
+            raise TypeError("Singleton subclasses may not define __init_subclass__")
+        with mcs._lock:
+            mcs._cls_locks[ret] = RLock()
+        return ret
+
+    def __call__(cls, *args, **kwargs):
+        """Intercept all instantiations to ensure at most one instance exists"""
+        with cls._lock:
+            cls_lock = cls._cls_locks[cls]
+        with cls_lock:
+            if (ret := cls._instances.get(cls, _None)) is _None:
+                cls._instances[cls] = (ret := super().__call__(*args, **kwargs))
+        return ret
+
+    @classmethod
+    @cache
+    def instance(mcs, t: type[T]) -> T:
+        """Get the instance of cls"""
+        if not isinstance(t, mcs):
+            raise TypeError(f"{t} is not a Singleton type")
+        with mcs._lock:
+            cls_lock = mcs._cls_locks[t]
+        with cls_lock:
+            if (got := mcs._instances.get(t, _None)) is _None:
+                raise NoInstanceError(f"No instance of {t} found")
+        return got
+
+
+class Singleton(metaclass=_SingletonType):
+    """A thread-safe singleton base class"""
+
+    @classmethod
+    def instance(cls) -> Self:
+        """Blocking get the instance of cls; raise if not constructed"""
+        return cast(_SingletonType, type(cls)).instance(cls)
+
+    def __init_subclass__(cls, *args, **kwargs):
+        """Disallow subclassing"""
+        cls.__init_subclass__ = _no_subclass
+
+
+# Disallow __init_subclass__ in Singleton subclasses
+_SingletonType._disallow_init_subclass = True  # pylint: disable=protected-access

{zstdlib-0.0.9 → zstdlib-0.1.0}/zstdlib.egg-info/PKG-INFO

@@ -1,17 +1,18 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: zstdlib
-Version: 0.0.9
+Version: 0.1.0
 Summary: A set of useful python utilities
 License: GPLv3
 Project-URL: Homepage, https://github.com/zwimer/zstdlib
 Keywords: remote,pipe
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Dynamic: license-file
 
 # zstdlib
 A set of useful python utilities

{zstdlib-0.0.9 → zstdlib-0.1.0}/zstdlib.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ tests/not_set.py
 tests/test_ansi.py
 tests/test_enum.py
 tests/test_frozen.py
+tests/test_io.py
 tests/test_singleton.py
 tests/log/__init__.py
 tests/log/base.py
@@ -15,6 +16,7 @@ zstdlib/__init__.py
 zstdlib/ansi.py
 zstdlib/enum.py
 zstdlib/frozen.py
+zstdlib/io.py
 zstdlib/not_set.py
 zstdlib/py.typed
 zstdlib/singleton.py

zstdlib-0.0.9/tests/test_singleton.py

@@ -1,126 +0,0 @@
-# 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.singleton 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.9/zstdlib/singleton.py

@@ -1,58 +0,0 @@
-from threading import Condition, RLock
-from typing import Any
-
-
-class SingletonType(type):
-    """
-    A thread-safe singleton metaclass
-    """
-
-    _seen: set[type] = set()  # Types that should not be constructed again
-    _instances: dict[type, Any] = {}  # Fully constructed and initialized singleton types
-    _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 or implement __init_subclass__")
-
-        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 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
-    """