v0.3 - Make atoms and rationals handle only specific types.

- Update docs

Author: bsamuel-ui

README.md

@@ -31,25 +31,30 @@ may change.
 
 ### Supported types
 
- * Atoms including `None`, `bool`, `int`, `float`, `str`
- * The `decimal.Decimal` class, represented as itself and in string form.
+ * Atoms including `None`, `bool`, `int`, `float`, `str`.
+    * Floats may optionally be represented as strings.
+ * The `decimal.Decimal` class, represented as itself or in string form.
  * The `datetime.date` and `datetime.datetime` classes, represented in ISO8601 form.
+ * Preliminary support for `datetime.timedelta` as ISO8601 time durations.
  * Subclasses of `enum.Enum`, represented by the string names.
     * Also, a `faux_enums` rule will accept an Enum type if you just use strings in your
       code.
  * The `typing.Optional[E]` type allows a JSON `null` to be substituted for a value.
  * Collections including `typing.List[E]`, `typing.Tuple[E, ...]`, `typing.Set[E]` and
    `typing.FrozenSet[E]`.
-    * The ellipsis is part of the syntax! It indicates a homogenous tuple, essentially a
+    * The `...` is [literal][ellipsis] and indicates a homogenous tuple, essentially a
       frozen list.
  * The `typing.Dict[K, V]` type allows a JSON object to represent a homogenous `dict`.
     * Restriction: the keys must be strings, ints, enums or dates.
  * Python classes implemented using `attrs.attrs`, `dataclasses.dataclass` are
    represented as JSON dicts and
  * Named tuples via `typing.NamedTuple` and heterogenous tuples via `typing.Tuple`.
-    * Really, you probably want to convert these to `attrs.`
+    * Though, you should consider converting these to `dataclass`.
  * The `typing.Union[A, B, C]` rule will recognize alternate types by inspection.
 
+In addition, `dataclass` and `attrs` classes support hooks to let you completely customize
+their JSON representation.
+
 ## Usage
 
 This example is also implemented in unit tests. First, let's declare some classes.
@@ -151,11 +156,11 @@ Thus we have:
  * `dict` and `Dict[K, V]`
 
 Tuple is a special case. In Python, they're often used to mean "frozenlist", so
-`Tuple[E, ...]` (the `...` is the actual syntax!) indicates all elements have the type
+`Tuple[E, ...]` (the `...` is [the Ellipsis object][ellipsis]) indicates all elements have the type
 `E`.
 
 They're also used to represent an unnamed record. In this case, you can use
-`Tuple[A, B, C, D]` or however many types. But don't do that, just make a `dataclass`.
+`Tuple[A, B, C, D]` or however many types. It's generally better to use a `dataclass`.
 
 The standard rules don't support:
 
@@ -299,17 +304,18 @@ _Union types._ You can use `typing.Union` to allow a member to be one of some nu
 alternates, but there are some caveats. You should use the `.is_ambiguous()` method of
 RuleSet to warn you of these.
 
-_Rules accept subclasses._ If you subclass `int`, the atoms rule will match it, and then
-the converter will call `int` against your instance. I haven't taken the time to examine
-what exactly to do.
+_Atom rules accept specific types._ At present, the rules for atomic types (`int`,
+ `str`, `bool`, `date`, `float`, `Decimal`) must be declared as exactly those types. With
+multiple inheritance, it's not clear which rule should apply
 
 _Checks are stricter than converters._ For example, a check for `int` will check whether
 the value is an integer, whereas the converter simply calls `int` on it. Thus there are
-many inputs for where `MyType` would pass but `Union[MyType, Dummy]` will fail. (Note
+inputs for where `MyType` would pass but `Union[MyType, Dummy]` will fail. (Note
 that `Optional` is special cased to look for `None` and doesn't have this problem.)
 
 _Numbers are hard._ See the rules named `floats`, `floats_nan_str`, `decimals`,
-`decimals_as_str` for details on how to get numbers to transmit reliably.
+`decimals_as_str` for details on how to get numbers to transmit reliably. There is no rule for
+fractions or complex numbers as there's no canonical way to transmit them via JSON.
 
 ## Maintenance
 
@@ -360,3 +366,4 @@ union. [↩](#a2)
 [attrs]: https://attrs.readthedocs.io/en/stable/
 [dataclasses]: https://docs.python.org/3/library/dataclasses.html
 [sharp]: https://github.com/UnitedIncome/json-syntax/blob/master/README.md#sharp-edges
+[ellipsis]: https://docs.python.org/3/library/stdtypes.html#the-ellipsis-object

json_syntax/helpers.py

@@ -27,8 +27,8 @@ def has_origin(typ, origin, num_args=None):
     The typing classes use dunder properties such that ``__origin__`` is the generic
     class and ``__args__`` are the type arguments.
 
-    Note: in python3.6, the ``__origin__`` attribute changed to reflect native types.
-    This call attempts to work around that so that python3.5 "just works."
+    Note: in python3.7, the ``__origin__`` attribute changed to reflect native types.
+    This call attempts to work around that so that 3.5 and 3.6 "just work."
     """
     t_origin = get_origin(typ)
     if not isinstance(origin, tuple):
@@ -180,9 +180,6 @@ def is_attrs_field_required(field):
 
 def _add_context(context, exc):
     try:
-        if exc is None:
-            return
-
         args = list(exc.args)
         arg_num, point = getattr(exc, "_context", (None, None))
 
@@ -242,7 +239,8 @@ def __enter__(self):
         pass
 
     def __exit__(self, exc_type, exc_value, traceback):
-        _add_context(self.context, exc_value)
+        if exc_value is not None:
+            _add_context(self.context, exc_value)
 
 
 def err_ctx(context, func):

json_syntax/ruleset.py

@@ -55,13 +55,13 @@ def lookup(self, verb, typ, accept_missing=False):
             self.cache.de_flight(verb=verb, typ=typ, forward=forward)
 
         if action is None and not accept_missing:
-            raise ValueError("Failed: lookup({!s}, {!r}".format(verb, typ))
+            raise TypeError("Failed: lookup({!s}, {!r})".format(verb, typ))
 
     def fallback(self, verb, typ):
         if verb == PATTERN:
             return pattern.Unknown
         else:
-            return None
+            raise TypeError("Failed: lookup({!s}, {!r}); no fallback provided".format(verb, typ))
 
     def is_ambiguous(self, typ, threshold=pattern.Matches.always):
         pat = self.lookup(verb=PATTERN, typ=typ)

json_syntax/std.py

@@ -55,16 +55,12 @@ def atoms(verb, typ, ctx):
         if verb in (JSON2PY, PY2JSON):
             if typ is NoneType:
                 return convert_none
-            for base in (str, bool, int):
-                if issubclass(typ, base):
+            for base in (str, bool, int):  # n.b. bool is a subclass of int.
+                if typ == base:
                     return base
-        elif verb == INSP_PY:
-            for base in (NoneType, str, bool, int):
-                if issubclass(typ, base):
-                    return partial(check_isinst, typ=base)
-        elif verb == INSP_JSON:
+        elif verb in (INSP_PY, INSP_JSON):
             for base in (NoneType, str, bool, int):
-                if issubclass(typ, base):
+                if typ == base:
                     return partial(check_isinst, typ=base)
         elif verb == PATTERN:
             for base, node in [
@@ -73,7 +69,7 @@ def atoms(verb, typ, ctx):
                 (bool, pat.Bool),
                 (int, pat.Number),
             ]:
-                if issubclass(typ, base):
+                if typ == base:
                     return node
 
 
@@ -89,7 +85,7 @@ def floats(verb, typ, ctx):
     This rule simply treats them as regular float values. If you want to catch them, you can set ``allow_nan=False``
     in ``json.dump()``.
     """
-    if issub_safe(typ, float):
+    if typ == float:
         if verb in (JSON2PY, PY2JSON):
             return float
         elif verb == INSP_PY:
@@ -108,7 +104,7 @@ def floats_nan_str(verb, typ, ctx):
 
     This rule converts special constants to string names.
     """
-    if issub_safe(typ, float):
+    if typ == float:
         if verb == JSON2PY:
             return float
         elif verb == PY2JSON:
@@ -131,7 +127,7 @@ def decimals(verb, typ, ctx):
 
     This rule will fail if passed a special constant.
     """
-    if issub_safe(typ, Decimal):
+    if typ == Decimal:
         if verb in (JSON2PY, PY2JSON):
             return Decimal
         elif verb in (INSP_JSON, INSP_PY):
@@ -148,7 +144,7 @@ def decimals_as_str(verb, typ, ctx):
 
     This rule will fail if passed a special constant.
     """
-    if issub_safe(typ, Decimal):
+    if typ == Decimal:
         if verb == JSON2PY:
             return Decimal
         elif verb == PY2JSON:
@@ -298,7 +294,7 @@ def _stringly(verb, typ, ctx):
     This is used internally by dicts.
     """
     for base in str, int:
-        if issubclass(typ, base):
+        if typ == base:
             if verb == PATTERN and base == str:
                 return pat.String.any
             if verb in (JSON2PY, PY2JSON):
@@ -308,7 +304,7 @@ def _stringly(verb, typ, ctx):
             elif verb in (INSP_JSON, PATTERN):
                 inspect = partial(check_parse_error, parser=base, error=ValueError)
                 return pat.String(typ.__name__, inspect) if verb == PATTERN else inspect
-    if issubclass(typ, (datetime, time)):
+    if typ in (datetime, time):
         return
     for rule in enums, iso_dates:
         action = rule(verb=verb, typ=typ, ctx=ctx)

poetry.lock

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "json-syntax"
-version = "0.2.1"
+version = "0.3"
 description = "Generates functions to convert Python classes to JSON dumpable objects."
 authors = ["Ben Samuel <[email protected]>"]
 license = "MIT"

pyproject.toml

@@ -22,22 +22,15 @@ class Dir(Enum):
     DOWN = 2
 
 
-atoms = [
-    (NoneType, None, None),
-    (bool, True, True),
-]
+atoms = [(NoneType, None, None), (bool, True, True)]
 
-nums = [
-    (int, 5, 5),
-    (float, 3.3, 3.3),
-    (Decimal, Decimal("5.5"), Decimal("5.5")),
-]
+nums = [(int, 5, 5), (float, 3.3, 3.3), (Decimal, Decimal("5.5"), Decimal("5.5"))]
 
 strings = [
     (str, "str", "str"),
     (date, date(2010, 10, 10), "2010-10-10"),
     (datetime, datetime(2011, 11, 11, 11, 11, 11), "2011-11-11T11:11:11"),
-    (Dir, Dir.UP, "UP")
+    (Dir, Dir.UP, "UP"),
 ]
 
 arrays = [