Merge branch 'expand-pythons'

Author: bsamuel-ui

README.md

@@ -7,8 +7,8 @@ classes using customizable rules.
 
 If you're like the authors, you tried writing a encoding function that attempted to
 encode and decode by interrogating the types at runtime, maybe calling some method like
-`asdict`. This works fine for generating JSON, but it gets sketchy when trying to decode
-the same JSON.
+`asdict`. This works fine for generating JSON, but it gets sketchy<sup
+id="a1">[1](#f1)</sup> when trying to decode the same JSON.
 
 Further, we have annotations in Python 3! Even if you're not using a type checker, just
 labeling the types of fields makes complex data structures far more comprehensible.
@@ -123,6 +123,18 @@ them, and constructs an action to represent them.
 }
 ```
 
+#### Actual usage
+
+The aim of all this is to enable reliable usage with your preferred JSON library:
+
+```python
+with open('myfile.json', 'r') as fh:
+    my_account = decode_account(json.load(fh))
+
+with open('myfile.json', 'w') as fh:
+    json.dump(encode_account(my_account))
+```
+
 ### Using generic types
 
 Generally, the [typing][] module simple provides capital letter type names that obviously
@@ -156,7 +168,7 @@ The standard rules don't support:
 A union type lets you present alternate types that the converters will attempt in
 sequence, e.g. `typing.Union[MyType, int, MyEnum]`.
 
-This is implemented in the `unions` rule as a so-called<sup id="a1">[1](#f1)</sup>
+This is implemented in the `unions` rule as a so-called<sup id="a2">[2](#f2)</sup>
 undiscriminated union. It means the module won't add any additional information to the
 value such as some kind of explicit tag.
 
@@ -229,7 +241,8 @@ class AbstractAccount:
 class AccountA(AbstractAccount):
     ...
 
-encode_account = rules.lookup(typ=Union[AccountA, AccountB, AccountC], verb='python_to_json')
+encode_account = rules.lookup(typ=Union[AccountA, AccountB, AccountC],
+                              verb='python_to_json')
 ```
 
 ### Adding custom rules
@@ -293,30 +306,36 @@ This package is maintained via the [poetry][] tool. Some useful commands:
 
  1. Setup: `poetry install`
  2. Run tests: `poetry run pytest tests/`
- 3. Reformat: `poetry run black json_syntax/ tests/`
+ 3. Reformat: `poetry run black -N json_syntax/ tests/`
 
 ### Setting up tox
 
 You'll want pyenv, then install the pythons:
 
-   curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
-   pyenv install --list | egrep '^ *3\.[4567]|^ *pypy3.5'
-   # figure out what versions you want
-   for v in 3.4.9 3.5.10 ...; do
-      pyenv install $v
-      PYENV_VERSION=$v python get-pip.py
-   done
+    curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
+    pyenv install --list | egrep '^ *3\.[4567]|^ *pypy3.5'
+    # figure out what versions you want
+    for v in 3.4.9 3.5.10 ...; do
+       pyenv install $v
+       PYENV_VERSION=$v python get-pip.py
+    done
 
-Once you install `tox` in your preferred python, you should be good to go.
+Once you install `tox` in your preferred python, running it is just `tox`.
 
 ### Notes
 
-<b id="f1">1</b>: A discriminated union has a tag that identifies the variant, such as
+<b id="f1">1</b>: Writing the encoder is deceptively easy because the instances in
+Python have complete information. The standard `json` module provides a hook to let
+you encode an object, and another hook to recognize `dict`s that have some special
+attribute. This can work quite well, but you'll have to encode *all* non-JSON types
+with dict-wrappers for the process to work in reverse. [↩](#a1)
+
+<b id="f2">2</b>: A discriminated union has a tag that identifies the variant, such as
 status codes that indicate success and a payload, or some error. Strictly, all unions
-must be discriminated in some way if different code paths are executed. In the
-`unions` rule, the discriminant is the class information in Python, and the structure of
-the JSON data. A less flattering description would be that this is a "poorly"
-discriminated union. [↩](#a1)
+must be discriminated in some way if different code paths are executed. In the `unions`
+rule, the discriminant is the class information in Python, and the structure of the JSON
+data. A less flattering description would be that this is a "poorly" discriminated
+union. [↩](#a2)
 
 [poetry]: https://poetry.eustace.io/docs/#installation
 [gradual typing]: https://www.python.org/dev/peps/pep-0483/#summary-of-gradual-typing

json_syntax/__init__.py

@@ -22,7 +22,7 @@
 )
 from .attrs import attrs_classes, named_tuples, tuples
 from .unions import unions
-from .helpers import J2P, P2J, IP, IJ  # noqa
+from .helpers import JSON2PY, PY2JSON, INSP_PY, INSP_JSON  # noqa
 
 
 def std_ruleset(

json_syntax/attrs.py

@@ -1,9 +1,8 @@
 from .helpers import (
-    IJ,
-    IP,
-    J2P,
-    JPI,
-    P2J,
+    JSON2PY,
+    PY2JSON,
+    INSP_JSON,
+    INSP_PY,
     SENTINEL,
     has_origin,
     identity,
@@ -34,7 +33,7 @@ def attrs_classes(
     """
     Handle an ``@attr.s`` or ``@dataclass`` decorated class.
     """
-    if verb not in JPI:
+    if verb not in (JSON2PY, PY2JSON, INSP_PY, INSP_JSON):
         return
     try:
         fields = typ.__attrs_attrs__
@@ -46,38 +45,38 @@ def attrs_classes(
         else:
             fields = fields.values()
 
-    if verb == IP:
+    if verb == INSP_PY:
         return partial(check_isinst, typ=typ)
 
     inner_map = []
     for field in fields:
-        if field.init or verb == P2J:
+        if field.init or verb == PY2JSON:
             tup = (
                 field.name,
                 ctx.lookup(
                     verb=verb, typ=resolve_fwd_ref(field.type, typ), accept_missing=True
                 ),
             )
-            if verb == P2J:
+            if verb == PY2JSON:
                 tup += (field.default,)
-            elif verb == IJ:
+            elif verb == INSP_JSON:
                 tup += (is_attrs_field_required(field),)
             inner_map.append(tup)
 
-    if verb == J2P:
+    if verb == JSON2PY:
         pre_hook_method = getattr(typ, pre_hook, identity)
         return partial(
             convert_dict_to_attrs,
             pre_hook=pre_hook_method,
             inner_map=tuple(inner_map),
             con=typ,
         )
-    elif verb == P2J:
+    elif verb == PY2JSON:
         post_hook = post_hook if hasattr(typ, post_hook) else None
         return partial(
             convert_attrs_to_dict, post_hook=post_hook, inner_map=tuple(inner_map)
         )
-    elif verb == IJ:
+    elif verb == INSP_JSON:
         check = getattr(typ, check, None)
         if check:
             return check
@@ -91,7 +90,7 @@ def named_tuples(verb, typ, ctx):
 
     Also handles a ``collections.namedtuple`` if you have a fallback handler.
     """
-    if verb not in JPI or not issub_safe(typ, tuple):
+    if verb not in (JSON2PY, PY2JSON, INSP_PY, INSP_JSON) or not issub_safe(typ, tuple):
         return
     try:
         fields = typ._field_types
@@ -103,7 +102,7 @@ def named_tuples(verb, typ, ctx):
         fields = [(name, None) for name in fields]
     else:
         fields = fields.items()
-    if verb == IP:
+    if verb == INSP_PY:
         return partial(check_isinst, typ=typ)
 
     defaults = {}
@@ -115,24 +114,24 @@ def named_tuples(verb, typ, ctx):
             name,
             ctx.lookup(verb=verb, typ=resolve_fwd_ref(inner, typ), accept_missing=True),
         )
-        if verb == P2J:
+        if verb == PY2JSON:
             tup += (defaults.get(name, SENTINEL),)
-        elif verb == IJ:
+        elif verb == INSP_JSON:
             tup += (name not in defaults,)
         inner_map.append(tup)
 
-    if verb == J2P:
+    if verb == JSON2PY:
         return partial(
             convert_dict_to_attrs,
             pre_hook=identity,
             inner_map=tuple(inner_map),
             con=typ,
         )
-    elif verb == P2J:
+    elif verb == PY2JSON:
         return partial(
             convert_attrs_to_dict, post_hook=None, inner_map=tuple(inner_map)
         )
-    elif verb == IJ:
+    elif verb == INSP_JSON:
         return partial(check_dict, pre_hook=identity, inner_map=tuple(inner_map))
 
 
@@ -141,18 +140,18 @@ def tuples(verb, typ, ctx):
     Handle a ``Tuple[type, type, type]`` product type. Use a ``NamedTuple`` if you don't
     want a list.
     """
-    if verb not in JPI or not has_origin(typ, tuple):
+    if verb not in (JSON2PY, PY2JSON, INSP_PY, INSP_JSON) or not has_origin(typ, tuple):
         return
     args = typ.__args__
     if Ellipsis in args:
         # This is a homogeneous tuple, use the lists rule.
         return
     inner = [ctx.lookup(verb=verb, typ=arg) for arg in args]
-    if verb == J2P:
+    if verb == JSON2PY:
         return partial(convert_tuple_as_list, inner=inner, con=tuple)
-    elif verb == P2J:
+    elif verb == PY2JSON:
         return partial(convert_tuple_as_list, inner=inner, con=list)
-    elif verb == IP:
+    elif verb == INSP_PY:
         return partial(check_tuple_as_list, inner=inner, con=tuple)
-    elif verb == IJ:
+    elif verb == INSP_JSON:
         return partial(check_tuple_as_list, inner=inner, con=list)

json_syntax/examples/flags.py

@@ -4,7 +4,7 @@
 This lets you construct a quick set of enums that are represented as strings.
 """
 
-from ..helpers import JP, II
+from ..helpers import JSON2PY, PY2JSON, INSP_JSON, INSP_PY
 from functools import partial
 
 
@@ -70,7 +70,7 @@ def flags(*, verb, typ, ctx):
     """
     if not isinstance(typ, Flag):
         return
-    if verb in JP:
+    if verb in (JSON2PY, PY2JSON):
         return partial(_convert_flag, typ.elems)
-    elif verb in II:
+    elif verb in (INSP_JSON, INSP_PY):
         return partial(_check_flag, typ.elems)

json_syntax/examples/loose_dates.py

@@ -1,4 +1,4 @@
-from json_syntax.helpers import J2P, P2J, IJ, IP
+from json_syntax.helpers import JSON2PY, PY2JSON, INSP_JSON, INSP_PY
 from json_syntax.action_v1 import check_parse_error, check_has_type
 
 from datetime import date, datetime
@@ -21,13 +21,13 @@ def convert_date_loosely(value):
 
 def iso_dates_loose(verb, typ, ctx):
     if typ == date:
-        if verb == P2J:
+        if verb == PY2JSON:
             return date.isoformat
-        elif verb == J2P:
+        elif verb == JSON2PY:
             return convert_date_loosely
-        elif verb == IP:
+        elif verb == INSP_PY:
             return partial(check_has_type, typ=date)
-        elif verb == IJ:
+        elif verb == INSP_JSON:
             return partial(
                 check_parse_error,
                 parser=convert_date_loosely,

json_syntax/helpers.py

@@ -5,13 +5,10 @@
 
 _eval_type = getattr(t, "_eval_type", None)
 logger = logging.getLogger(__name__)
-J2P = "json_to_python"
-P2J = "python_to_json"
-IJ = "inspect_json"
-IP = "inspect_python"
-II = (IJ, IP)
-JP = (J2P, P2J)
-JPI = (J2P, P2J, IP, IJ)
+JSON2PY = "json_to_python"
+PY2JSON = "python_to_json"
+INSP_JSON = "inspect_json"
+INSP_PY = "inspect_python"
 NoneType = type(None)
 SENTINEL = object()
 python_minor = sys.version_info[:2]
@@ -180,7 +177,7 @@ def is_attrs_field_required(field):
         return factory in _missing_values
 
 
-def _add_context(exc, context):
+def _add_context(context, exc):
     try:
         if exc is None:
             return