convert Len to GroupedMetadata, add MinLen and MaxLen (#21)

samuelcolvin · web-flow · commit 9747ec3c89e2 · 2022-09-27T10:51:32.000-07:00
* convert Len to GroupedMetadata

* oops, fix test case

* simplify tests, fix linting

* add MinLen, MaxLen to README
diff --git a/README.md b/README.md
@@ -87,9 +87,14 @@ it easy to cause silent data corruption due to floating-point imprecision.
 
 We encourage libraries to carefully document which interpretation they implement.
 
-### Len
+### MinLen, MaxLen, Len
 
 `Len()` implies that `min_inclusive <= len(value) < max_exclusive`.
+
+As well as `Len()` which can optionally include upper and lower bounds, we also
+provide `MinLen(x)` and `MaxLen(y)` which are equivalent to `Len(min_inclusive=x)` 
+and `Len(max_exclusive=y)` respectively.
+
 We recommend that libraries interpret `slice` objects identically
 to `Len()`, making all the following cases equivalent:
 
@@ -99,12 +104,13 @@ to `Len()`, making all the following cases equivalent:
 * `Annotated[list, slice(0, 10)]`
 * `Annotated[list, Len(0, 10)]`
 * `Annotated[list, Len(max_exclusive=10)]`
+* `Annotated[list, MaxLen(10)]`
 
-And of course you can describe lists of three or more elements (`Len(min_inclusive=3)`),
+And of course you can describe lists of three or more elements (`Len(min_inclusive=3)` or `MinLen(3)`),
 four, five, or six elements (`Len(4, 7)` - note exclusive-maximum!) or *exactly*
 eight elements (`Len(8, 9)`).
 
-Implementors: note that Len() should always have an integer value for
+Implementors: note that `Len()` should always have an integer value for
 `min_inclusive`, but `slice` objects can also have `start=None`.
 
 ### Timezone
@@ -167,7 +173,7 @@ class Field(GroupedMetadata):
 
 Libraries consuming annotated-types constraints should check for `GroupedMetadata` and unpack it by iterating over the object and treating the results as if they had been "unpacked" in the `Annotated` type.  The same logic should be applied to the [PEP 646 `Unpack` type](https://peps.python.org/pep-0646/), so that `Annotated[T, Field(...)]`, `Annotated[T, Unpack[Field(...)]]` and `Annotated[T, *Field(...)]` are all treated consistently.
 
-Our own `annotated_types.Interval` class is a `GroupedMetadata` which unpacks itself into `Gt`, `Lt`, etc., so this is not an abstract concern.
+Our own `annotated_types.Interval` class is a `GroupedMetadata` which unpacks itself into `Gt`, `Lt`, etc., so this is not an abstract concern.  Similarly, `annotated_types.Len` is a `GroupedMetadata` which unpacks itself into `MinLen` (optionally) and `MaxLen`.
 
 ### Consuming metadata
 
diff --git a/annotated_types/__init__.py b/annotated_types/__init__.py
@@ -33,6 +33,8 @@
     'Le',
     'Interval',
     'MultipleOf',
+    'MinLen',
+    'MaxLen',
     'Len',
     'Timezone',
     'Predicate',
@@ -219,7 +221,29 @@ class MultipleOf(BaseMetadata):
 
 
 @dataclass(frozen=True, **SLOTS)
-class Len(BaseMetadata):
+class MinLen(BaseMetadata):
+    """
+    MinLen() implies minimum inclusive length.
+
+    For more details, see ``Len()`` below.
+    """
+
+    min_inclusive: Annotated[int, Ge(0)]
+
+
+@dataclass(frozen=True, **SLOTS)
+class MaxLen(BaseMetadata):
+    """
+    MaxLen() implies maximum exclusive length.
+
+    For more details, see ``Len()`` below.
+    """
+
+    max_exclusive: Annotated[int, Ge(0)]
+
+
+@dataclass(frozen=True, **SLOTS)
+class Len(GroupedMetadata):
     """Len() implies that ``min_inclusive <= len(value) < max_exclusive``.
 
     We also recommend that libraries interpret ``slice`` objects identically
@@ -239,6 +263,13 @@ class Len(BaseMetadata):
     min_inclusive: Annotated[int, Ge(0)] = 0
     max_exclusive: Optional[Annotated[int, Ge(0)]] = None
 
+    def __iter__(self) -> Iterator[BaseMetadata]:
+        """Unpack a Len into zone or more single-bounds."""
+        if self.min_inclusive > 0:
+            yield MinLen(self.min_inclusive)
+        if self.max_exclusive is not None:
+            yield MaxLen(self.max_exclusive)
+
 
 @dataclass(frozen=True, **SLOTS)
 class Timezone(BaseMetadata):
diff --git a/annotated_types/test_cases.py b/annotated_types/test_cases.py
@@ -80,14 +80,18 @@ def cases() -> Iterable[Case]:
 
     # lengths
 
+    yield Case(Annotated[str, at.MinLen(3)], ('123', '1234', 'x' * 10), ('', '1', '12'))
     yield Case(Annotated[str, at.Len(3)], ('123', '1234', 'x' * 10), ('', '1', '12'))
     yield Case(Annotated[str, 3:], ('123', '1234', 'x' * 10), ('', '1', '12'))
     yield Case(Annotated[str, 3:None], ('123', '1234', 'x' * 10), ('', '1', '12'))
+    yield Case(Annotated[List[int], at.MinLen(3)], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2]))
     yield Case(Annotated[List[int], at.Len(3)], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2]))
     yield Case(Annotated[List[int], 3:], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2]))
     yield Case(Annotated[List[int], 3:None], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2]))
 
+    yield Case(Annotated[str, at.MaxLen(4)], ('', '123'), ('1234', 'x' * 10))
     yield Case(Annotated[str, at.Len(0, 4)], ('', '123'), ('1234', 'x' * 10))
+    yield Case(Annotated[List[str], at.MaxLen(4)], ([], ['a', 'bcdef'], ['a', 'b', 'c']), (['a'] * 4, ['b'] * 5))
     yield Case(Annotated[List[str], at.Len(0, 4)], ([], ['a', 'bcdef'], ['a', 'b', 'c']), (['a'] * 4, ['b'] * 5))
     yield Case(Annotated[str, 0:4], ('', '123'), ('1234', 'x' * 10))
     yield Case(Annotated[str, :4], ('', '123'), ('1234', 'x' * 10))
diff --git a/tests/test_main.py b/tests/test_main.py
@@ -43,17 +43,14 @@ def check_multiple_of(constraint: Constraint, val: Any) -> bool:
     return val % constraint.multiple_of == 0
 
 
-def check_len(constraint: Constraint, val: Any) -> bool:
-    if isinstance(constraint, slice):
-        constraint = annotated_types.Len(constraint.start or 0, constraint.stop)
-    assert isinstance(constraint, annotated_types.Len)
-    if constraint.min_inclusive is None:
-        raise TypeError
-    if len(val) < constraint.min_inclusive:
-        return False
-    if constraint.max_exclusive is not None and len(val) >= constraint.max_exclusive:
-        return False
-    return True
+def check_min_len(constraint: Constraint, val: Any) -> bool:
+    assert isinstance(constraint, annotated_types.MinLen)
+    return len(val) >= constraint.min_inclusive
+
+
+def check_max_len(constraint: Constraint, val: Any) -> bool:
+    assert isinstance(constraint, annotated_types.MaxLen)
+    return len(val) < constraint.max_exclusive
 
 
 def check_predicate(constraint: Constraint, val: Any) -> bool:
@@ -84,9 +81,9 @@ def check_timezone(constraint: Constraint, val: Any) -> bool:
     annotated_types.Le: check_le,
     annotated_types.MultipleOf: check_multiple_of,
     annotated_types.Predicate: check_predicate,
-    annotated_types.Len: check_len,
+    annotated_types.MinLen: check_min_len,
+    annotated_types.MaxLen: check_max_len,
     annotated_types.Timezone: check_timezone,
-    slice: check_len,
 }
 
 
@@ -96,10 +93,12 @@ def get_constraints(tp: type) -> Iterator[Constraint]:
     args = iter(get_args(tp))
     next(args)
     for arg in args:
-        if isinstance(arg, (annotated_types.BaseMetadata, slice)):
+        if isinstance(arg, annotated_types.BaseMetadata):
             yield arg
         elif isinstance(arg, annotated_types.GroupedMetadata):
             yield from arg
+        elif isinstance(arg, slice):
+            yield from annotated_types.Len(arg.start or 0, arg.stop)
 
 
 def is_valid(tp: type, value: Any) -> bool:
