firstclass 0.0.3__tar.gz → 0.1.0__tar.gz

{firstclass-0.0.3/firstclass.egg-info → firstclass-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firstclass
-Version: 0.0.3
+Version: 0.1.0
 Summary: dataclass with bytes, ctypes, C struct, JSON and XML serialization
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -112,6 +112,13 @@ bitfields, inheritance, virtual members, unknown types (`#include`d headers are
 Plain C enums are 32-bit like C unless `: type` is given. C field names that are Python keywords
 (`class`, `from`, ...) get a trailing underscore (`class_`).
 
+## Comparison
+
+Like a dataclass, `==` / `!=` compare field by field. Unlike a plain dataclass, ordering is on by
+default: `<`, `<=`, `>`, `>=` compare fields in declaration order, like tuples, so you can `sorted()`,
+`min()` and `max()` instances. Comparing with another class raises `TypeError` (`==` is just `False`).
+Switch it off with `@firstclass(order=False)`; `eq=False` turns off both.
+
 ## Layout options
 
 ```python

firstclass-0.0.3/PKG-INFO → firstclass-0.1.0/README.md

@@ -1,10 +1,3 @@
-Metadata-Version: 2.4
-Name: firstclass
-Version: 0.0.3
-Summary: dataclass with bytes, ctypes, C struct, JSON and XML serialization
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
 # firstclass
 
 `@firstclass` works like `@dataclass` (same keyword args) and adds conversion to and from
@@ -112,6 +105,13 @@ bitfields, inheritance, virtual members, unknown types (`#include`d headers are
 Plain C enums are 32-bit like C unless `: type` is given. C field names that are Python keywords
 (`class`, `from`, ...) get a trailing underscore (`class_`).
 
+## Comparison
+
+Like a dataclass, `==` / `!=` compare field by field. Unlike a plain dataclass, ordering is on by
+default: `<`, `<=`, `>`, `>=` compare fields in declaration order, like tuples, so you can `sorted()`,
+`min()` and `max()` instances. Comparing with another class raises `TypeError` (`==` is just `False`).
+Switch it off with `@firstclass(order=False)`; `eq=False` turns off both.
+
 ## Layout options
 
 ```python

{firstclass-0.0.3 → firstclass-0.1.0}/firstclass/_core.py

@@ -279,6 +279,9 @@ class Schema:
 def firstclass(cls=None, /, *, byteorder: str = "little", align: bool = False, **dataclass_kwargs):
     """Like `@dataclass` (same keyword args), plus binary/JSON/XML/ctypes/C codecs.
 
+    Unlike a plain dataclass, `order=True` is the default (compare field by field, like tuples);
+    pass `order=False` to turn it off.
+
     byteorder: 'little' (default) or 'big'.
     align: False (default) = packed layout, no padding; True = natural C alignment padding.
     """
@@ -286,7 +289,9 @@ def firstclass(cls=None, /, *, byteorder: str = "little", align: bool = False, *
     def wrap(cls):
         if not isinstance(cls, type):
             raise TypeError(f"@firstclass needs a class, got {type(cls).__name__}")
-        dc = dataclasses.dataclass(cls, **dataclass_kwargs)
+        kwargs = dict(dataclass_kwargs)
+        kwargs.setdefault("order", kwargs.get("eq", True))  # ==, <, <=, >, >= by field order
+        dc = dataclasses.dataclass(cls, **kwargs)
         clash = [f.name for f in dataclasses.fields(dc) if f.name in _METHODS or f.name == "__firstclass__"]
         if clash:
             raise TypeError(f"{dc.__name__}: field names clash with firstclass methods: {clash}")

firstclass-0.0.3/README.md → firstclass-0.1.0/firstclass.egg-info/PKG-INFO

@@ -1,3 +1,10 @@
+Metadata-Version: 2.4
+Name: firstclass
+Version: 0.1.0
+Summary: dataclass with bytes, ctypes, C struct, JSON and XML serialization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
 # firstclass
 
 `@firstclass` works like `@dataclass` (same keyword args) and adds conversion to and from
@@ -105,6 +112,13 @@ bitfields, inheritance, virtual members, unknown types (`#include`d headers are
 Plain C enums are 32-bit like C unless `: type` is given. C field names that are Python keywords
 (`class`, `from`, ...) get a trailing underscore (`class_`).
 
+## Comparison
+
+Like a dataclass, `==` / `!=` compare field by field. Unlike a plain dataclass, ordering is on by
+default: `<`, `<=`, `>`, `>=` compare fields in declaration order, like tuples, so you can `sorted()`,
+`min()` and `max()` instances. Comparing with another class raises `TypeError` (`==` is just `False`).
+Switch it off with `@firstclass(order=False)`; `eq=False` turns off both.
+
 ## Layout options
 
 ```python

{firstclass-0.0.3 → firstclass-0.1.0}/firstclass.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ firstclass.egg-info/PKG-INFO
 firstclass.egg-info/SOURCES.txt
 firstclass.egg-info/dependency_links.txt
 firstclass.egg-info/top_level.txt
+tests/test_compare.py
 tests/test_ctypes_types.py
 tests/test_edge_cases.py
 tests/test_enum_bitfield.py

{firstclass-0.0.3 → firstclass-0.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "firstclass"
-version = "0.0.3"
+version = "0.1.0"
 description = "dataclass with bytes, ctypes, C struct, JSON and XML serialization"
 readme = "README.md"
 requires-python = ">=3.10"

firstclass-0.1.0/tests/test_compare.py

@@ -0,0 +1,221 @@
+import dataclasses
+import enum
+import unittest
+
+from firstclass import (
+    array_t, bitfield, bytes_t, char_array, enum_t, firstclass, float64_t, from_header, uint8_t, uint16_t,
+)
+
+
+class Level(enum.IntEnum):
+    LOW = 1
+    HIGH = 5
+
+
+@firstclass
+class Version:
+    major: uint8_t
+    minor: uint8_t
+    patch: uint16_t = 0
+
+
+@firstclass
+class Rich:
+    name: char_array[4]
+    level: enum_t[Level, uint8_t]
+    items: array_t[uint8_t, 2]
+    blob: bytes_t[2]
+    ratio: float64_t
+    bits: bitfield[uint8_t, 3]
+    inner: Version
+
+
+def rich(**kw):
+    base = dict(name="a", level=Level.LOW, items=[1, 2], blob=b"\x00\x01", ratio=1.0, bits=1,
+                inner=Version(1, 0))
+    base.update(kw)
+    return Rich(**base)
+
+
+class Equality(unittest.TestCase):
+    def test_eq_and_ne(self):
+        self.assertEqual(Version(1, 2, 3), Version(1, 2, 3))
+        self.assertNotEqual(Version(1, 2, 3), Version(1, 2, 4))
+        self.assertTrue(Version(1, 2) == Version(1, 2, 0))
+        self.assertFalse(Version(1, 2) != Version(1, 2))
+
+    def test_equality_survives_a_bytes_roundtrip(self):
+        r = rich()
+        self.assertEqual(Rich.from_bytes(r.to_bytes()), r)
+
+    def test_different_classes_are_never_equal(self):
+        @firstclass
+        class Other:
+            major: uint8_t
+            minor: uint8_t
+            patch: uint16_t = 0
+        self.assertNotEqual(Version(1, 2), Other(1, 2))
+        self.assertFalse(Version(1, 2) == (1, 2, 0))
+
+    def test_not_hashable_unless_frozen(self):
+        with self.assertRaises(TypeError):
+            hash(Version(1, 2))
+
+        @firstclass(frozen=True)
+        class Frozen:
+            a: uint8_t
+        self.assertEqual(hash(Frozen(1)), hash(Frozen(1)))
+        self.assertEqual({Frozen(1), Frozen(1), Frozen(2)}, {Frozen(1), Frozen(2)})
+
+
+class Ordering(unittest.TestCase):
+    def test_all_four_operators(self):
+        a, b = Version(1, 2, 3), Version(1, 3, 0)
+        self.assertTrue(a < b)
+        self.assertTrue(a <= b)
+        self.assertTrue(b > a)
+        self.assertTrue(b >= a)
+        self.assertFalse(a > b)
+        self.assertFalse(a >= b)
+        self.assertFalse(b < a)
+        self.assertFalse(b <= a)
+
+    def test_equal_values(self):
+        a, b = Version(1, 2, 3), Version(1, 2, 3)
+        self.assertTrue(a <= b)
+        self.assertTrue(a >= b)
+        self.assertFalse(a < b)
+        self.assertFalse(a > b)
+
+    def test_lexicographic_in_field_order(self):
+        self.assertTrue(Version(2, 0, 0) > Version(1, 255, 65535))
+        self.assertTrue(Version(1, 1, 0) > Version(1, 0, 65535))
+        self.assertTrue(Version(0, 0, 1) > Version(0, 0, 0))
+
+    def test_sorted_min_max(self):
+        vs = [Version(1, 2, 0), Version(0, 9, 9), Version(1, 0, 5), Version(1, 2, 1)]
+        self.assertEqual(sorted(vs), [Version(0, 9, 9), Version(1, 0, 5), Version(1, 2, 0), Version(1, 2, 1)])
+        self.assertEqual(max(vs), Version(1, 2, 1))
+        self.assertEqual(min(vs), Version(0, 9, 9))
+        self.assertEqual(sorted(vs, reverse=True)[0], Version(1, 2, 1))
+
+    def test_ordering_matches_after_roundtrip(self):
+        vs = [Version(3, 1), Version(1, 4), Version(2, 2)]
+        back = [Version.from_bytes(v.to_bytes()) for v in vs]
+        self.assertEqual(sorted(back), sorted(vs))
+
+    def test_comparing_with_other_types_raises(self):
+        with self.assertRaises(TypeError):
+            Version(1, 2) < (1, 2, 0)
+        with self.assertRaises(TypeError):
+            Version(1, 2) >= 5
+
+        @firstclass
+        class Other:
+            major: uint8_t
+            minor: uint8_t
+            patch: uint16_t = 0
+        with self.assertRaises(TypeError):
+            Version(1, 2) < Other(1, 3)
+
+    def test_every_field_kind_participates(self):
+        base = rich()
+        self.assertTrue(rich(name="b") > base)
+        self.assertTrue(rich(level=Level.HIGH) > base)
+        self.assertTrue(rich(items=[1, 3]) > base)
+        self.assertTrue(rich(blob=b"\x00\x02") > base)
+        self.assertTrue(rich(ratio=1.5) > base)
+        self.assertTrue(rich(bits=2) > base)
+        self.assertTrue(rich(inner=Version(1, 1)) > base)
+        self.assertTrue(base < rich(inner=Version(2, 0)))
+
+    def test_first_differing_field_decides(self):
+        self.assertTrue(rich(name="b", ratio=0.0) > rich(name="a", ratio=99.0))
+
+    def test_nested_classes_are_orderable(self):
+        @firstclass
+        class Pair:
+            lo: Version
+            hi: Version
+        self.assertTrue(Pair(Version(1, 0), Version(9, 9)) < Pair(Version(1, 1), Version(0, 0)))
+
+    def test_works_for_every_byte_order_and_alignment(self):
+        for kw in ({}, {"byteorder": "big"}, {"align": True}):
+            with self.subTest(kw):
+                @firstclass(**kw)
+                class V:
+                    a: uint8_t
+                    b: uint16_t
+                self.assertTrue(V(1, 2) < V(1, 3))
+                self.assertTrue(V(2, 0) > V(1, 9))
+
+
+class Options(unittest.TestCase):
+    def test_order_false_disables_ordering_only(self):
+        @firstclass(order=False)
+        class NoOrder:
+            a: uint8_t
+        self.assertEqual(NoOrder(1), NoOrder(1))
+        with self.assertRaises(TypeError):
+            NoOrder(1) < NoOrder(2)
+
+    def test_eq_false_means_no_ordering_either(self):
+        @firstclass(eq=False)
+        class NoEq:
+            a: uint8_t
+        x, y = NoEq(1), NoEq(1)
+        self.assertNotEqual(x, y)  # identity comparison
+        self.assertEqual(x, x)
+        with self.assertRaises(TypeError):
+            x < y
+
+    def test_eq_false_with_explicit_order_is_a_dataclass_error(self):
+        with self.assertRaises(ValueError):
+            @firstclass(eq=False, order=True)
+            class Bad:
+                a: uint8_t
+
+    def test_order_true_explicit_is_fine(self):
+        @firstclass(order=True)
+        class Explicit:
+            a: uint8_t
+        self.assertTrue(Explicit(1) < Explicit(2))
+
+    def test_field_compare_false_is_ignored(self):
+        @firstclass
+        class Skip:
+            a: uint8_t
+            noise: uint8_t = dataclasses.field(default=0, compare=False)
+        self.assertEqual(Skip(1, 5), Skip(1, 9))
+        self.assertFalse(Skip(1, 9) < Skip(1, 5))
+        self.assertTrue(Skip(1, 0) < Skip(2, 0))
+
+    def test_functools_total_ordering_not_needed(self):
+        for name in ("__lt__", "__le__", "__gt__", "__ge__", "__eq__"):
+            self.assertIn(name, vars(Version))
+
+
+class HeaderGenerated(unittest.TestCase):
+    def test_generated_classes_compare(self):
+        t = from_header(text="""
+            enum class Lvl : uint8_t { A = 1, B };
+            struct Ver { uint8_t major; uint8_t minor; };
+            struct Msg { struct Ver ver; Lvl lvl; char tag[4]; };
+        """)
+        a = t.Msg(t.Ver(1, 0), t.Lvl.A, "x")
+        b = t.Msg(t.Ver(1, 0), t.Lvl.B, "a")
+        self.assertTrue(a < b)
+        self.assertTrue(t.Ver(1, 9) < t.Ver(2, 0))
+        self.assertEqual(sorted([b, a]), [a, b])
+        self.assertEqual(t.Msg.from_bytes(a.to_bytes()), a)
+
+    def test_generated_classes_from_two_parses_are_different_types(self):
+        src = "struct Ver { uint8_t major; };"
+        a, b = from_header(text=src), from_header(text=src)
+        self.assertNotEqual(a.Ver(1), b.Ver(1))
+        with self.assertRaises(TypeError):
+            a.Ver(1) < b.Ver(2)
+
+
+if __name__ == "__main__":
+    unittest.main()

{firstclass-0.0.3 → firstclass-0.1.0}/tests/test_edge_cases.py

@@ -323,7 +323,7 @@ class DataclassBehaviour(unittest.TestCase):
         self.assertEqual(s.to_bytes(), b"\xc8\x05")
 
     def test_decorator_forms(self):
-        self.assertTrue(dataclasses.is_dataclass(firstclass(Small)))
+        self.assertTrue(dataclasses.is_dataclass(firstclass(type("Fresh", (), {"__annotations__": {"a": uint8_t}}))))
         with self.assertRaises(TypeError):
             firstclass(5)
         with self.assertRaises(ValueError):