converters: Make it possible to have version-specific fields in the API

Author: encukou

naucse/converters.py

@@ -275,7 +275,33 @@ def _classname(cls):
     return f'{cls.__module__}.{cls.__qualname__}'
 
 
-class Field:
+class AbstractField:
+    """Descriptor for a Model's attribute that is loaded/dumped to JSON
+
+    See Field for the API.
+    """
+
+    def __get__(self, instance, owner):
+        """Debug helper
+
+        An initialized model instance should have values for all its fields
+        in its __dict__.
+
+        However, when loading, not all fields have been initialized yet.
+        Attempts to get the value of such a field will raise an informative
+        error, rather than return the Field object from the model class.
+        """
+        if instance is None:
+            # Getting a class attribute -- return this Field
+            return self
+        else:
+            # Getting an instnce attribute -- raise an error
+            type_name = owner.__name__
+            raise AttributeError(
+                f'{self.name!r} of {type_name} object was not yet loaded'
+            )
+
+class Field(AbstractField):
     """Descriptor for a Model's attribute that is loaded/dumped to JSON
 
     `converter`: Converter to use for the attribute.
@@ -406,26 +432,6 @@ def put_schema_into(self, object_schema, context):
         if not context.is_input:
             object_schema['additionalProperties'] = False
 
-    def __get__(self, instance, owner):
-        """Debug helper
-
-        An initialized model instance should have values for all its fields
-        in its __dict__.
-
-        However, when loading, not all fields have been initialized yet.
-        Attempts to get the value of such a field will raise an informative
-        error, rather than return the Field object from the model class.
-        """
-        if instance is None:
-            # Getting a class attribute -- return this Field
-            return self
-        else:
-            # Getting an instnce attribute -- raise an error
-            type_name = owner.__name__
-            raise AttributeError(
-                f'{self.name!r} of {type_name} object was not yet loaded'
-            )
-
     def default_factory(self):
         """Decorate a function that will be called to produce a default value
 
@@ -450,20 +456,96 @@ def _decorator(func):
         return _decorator
 
 
+class VersionField(AbstractField):
+    """Chooses Field based on the API version
+
+    `fields` should be a {version introduced: field} mapping.
+    When loading/dumping/getting schema, VersionField picks the field for
+    tat version and forwards the operation to it.
+    For versions before the first specified, the field is not loaded/dumped,
+    and the instance attribute is set to None.
+
+    VersionField adds a "Added/Modified in API version" note to the JSON Schema
+    description.
+
+    Making later fields suitably backwards-compatible is the user's
+    responsibility.
+    """
+
+    def __init__(self, fields, name=None):
+        self.fields = sorted((tuple(k), f) for k, f in fields.items())
+        self.name = name
+
+    def _field_for_context(self, context):
+        for version, field in reversed(self.fields):
+            if version <= context.version:
+                return version, field
+        return None, None
+
+    def __repr__(self):
+        return f'<{_classname(type(self))} {self.name} ({self.fields})>'
+
+    def __set_name__(self, cls, name):
+        self.name = name
+        for version, field in self.fields:
+            set_name = getattr(type(field), '__set_name__', None)
+            if set_name:
+                set_name(field, cls, name)
+
+    def load_into(self, instance, data, context, **kwargs):
+        version, field = self._field_for_context(context)
+        if field:
+            field.load_into(instance, data, context, **kwargs)
+        else:
+            setattr(instance, self.name, None)
+
+    def dump_into(self, instance, data, context):
+        version, field = self._field_for_context(context)
+        if field:
+            field.dump_into(instance, data, context)
+
+    def put_schema_into(self, object_schema, context):
+        version, field = self._field_for_context(context)
+        if field:
+            field.put_schema_into(object_schema, context)
+            try:
+                schema = object_schema['properties'][self.name]
+            except KeyError:
+                pass
+            if version == self.fields[0][0]:
+                note = 'Added in API version {}.{}'.format(*version)
+            else:
+                note = 'Modified in API version {}.{}'.format(*version)
+            if 'description' in schema:
+                schema['description'] += '\n\n' + note
+            else:
+                schema['description'] = note
+
+    def default_factory(self):
+        raise NotImplementedError('default_factory is not implemented yet')
+
+    def after_load(self):
+        raise NotImplementedError('after_load is not implemented yet')
+
+
 class ModelConverter(BaseConverter):
     """Converter for a Model, i.e. class with several Fields"""
     def __init__(
         self, cls, *, slug=None, load_arg_names=(), extra_fields=(),
     ):
         self.cls = cls
         self.name = cls.__name__
-        self.doc = inspect.getdoc(cls).strip()
+        doc = inspect.getdoc(cls)
+        if doc:
+            self.doc = doc.strip()
+        else:
+            self.doc = ''
         self.fields = {}
         self.load_arg_names = load_arg_names
         self.slug = slug
 
         for name, field in vars(cls).items():
-            if name.startswith('__') or not isinstance(field, Field):
+            if name.startswith('__') or not isinstance(field, AbstractField):
                 continue
             self.fields[name] = field
         self.fields.update((f.name, f) for f in extra_fields)
@@ -502,7 +584,7 @@ class LoadContext:
     `version` is the API version, as a tuple of ints (major, minor).
     """
     def __init__(self, version):
-        self.version = version
+        self.version = tuple(version)
 
 
 class DumpContext:
@@ -511,7 +593,7 @@ class DumpContext:
     `version` is the API version, as a tuple of ints (major, minor).
     """
     def __init__(self, version):
-        self.version = version
+        self.version = tuple(version)
 
 
 class SchemaContext:
@@ -526,7 +608,7 @@ def __init__(self, *, is_input, version):
         self.definition_refs = {}
         self.definitions = {}
         self.is_input = is_input
-        self.version = version
+        self.version = tuple(version)
 
     def get_schema(self, converter):
         """Get schema for the given converter
@@ -616,7 +698,7 @@ def dump(instance, converter=None, *, version):
     slug = converter.slug or 'data'
     context = DumpContext(version=version)
     result = {
-        'api_version': context.version,
+        'api_version': list(context.version),
         slug: converter.dump(instance, context),
     }
     result['$schema'] = _get_schema_url(converter, instance)

test_naucse/test_converters_versions.py

@@ -0,0 +1,121 @@
+import pytest
+from jsonschema.exceptions import ValidationError
+
+from naucse.converters import Field, VersionField, load, dump, get_schema
+from naucse.converters import register_model, get_converter
+
+
+class TestModel:
+    versioned_field = VersionField({
+        # (Versions are out of order to test that VersionField sorts them)
+        (0, 1): Field(str, optional=True, doc='Introducing new field'),
+        (1, 0): Field(int, optional=True, doc="Let's make it an int"),
+        (0, 5): Field(bool, optional=True, doc="Actually it's a bool"),
+        (2, 0): Field(int, doc='No longer optional'),
+    })
+
+register_model(TestModel)
+get_converter(TestModel).get_schema_url = lambda *a, **ka: ""
+
+TEST_DATA = {
+    (0, 1): "a",
+    (0, 2): "b",
+    (0, 5): True,
+    (0, 6): False,
+    (1, 0): 123,
+    (2, 1): 456,
+}
+
+
+@pytest.mark.parametrize(
+    'version',
+    ((0, 0), (0, 1), (0, 2), (0, 5), (0, 6), (1, 0)),
+)
+def test_load_nothing(version):
+    result = load(TestModel, {
+        'api_version': list(version),
+        'data': {},
+    })
+    assert result.versioned_field == None
+
+
+def test_not_optional():
+    with pytest.raises(ValidationError):
+        load(TestModel, {
+            'api_version': [2, 0],
+            'data': {},
+        })
+
+
+@pytest.mark.parametrize(('version', 'data'), TEST_DATA.items())
+def test_load_data(version, data):
+    result = load(TestModel, {
+        'api_version': list(version),
+        'data': {'versioned_field': data},
+    })
+    assert result.versioned_field == data
+
+
+@pytest.mark.parametrize(
+    ('version', 'data'),
+    (
+        ((0, 0), 123),
+        ((0, 0), "ab"),
+        ((0, 1), True),
+        ((1, 0), "ab"),
+        ((1, 1), "ab"),
+    ),
+)
+def test_load_wrong_data(version, data):
+    with pytest.raises(ValidationError):
+        result = load(TestModel, {
+            'api_version': (0, 0),
+            'data': {'versioned_field': 123},
+        })
+
+
+@pytest.mark.parametrize(('version', 'data'), TEST_DATA.items())
+def test_dump_data(version, data):
+    data_dict = {
+        'api_version': list(version),
+        'data': {'versioned_field': data},
+    }
+    result = load(TestModel, data_dict)
+    assert dump(result, version=version) == {'$schema': '', **data_dict}
+
+
+@pytest.mark.parametrize(('version', 'data'), TEST_DATA.items())
+def test_dump_v0(version, data):
+    data_dict = {
+        'api_version': list(version),
+        'data': {'versioned_field': data},
+    }
+    result = load(TestModel, data_dict)
+    assert dump(result, version=(0, 0)) == {
+        '$schema': '',
+        'api_version': [0, 0],
+        'data': {},
+    }
+
+
+@pytest.mark.parametrize(
+    ('version', 'expected'),
+    {
+        (0, 0): None,
+        (0, 1): "Introducing new field\n\nAdded in API version 0.1",
+        (0, 2): "Introducing new field\n\nAdded in API version 0.1",
+        (0, 5): "Actually it's a bool\n\nModified in API version 0.5",
+        (1, 0): "Let's make it an int\n\nModified in API version 1.0",
+        (1, 1): "Let's make it an int\n\nModified in API version 1.0",
+        (2, 1): 'No longer optional\n\nModified in API version 2.0',
+    }.items()
+)
+def test_doc(version, expected):
+    schema = get_schema(TestModel, is_input=True, version=version)
+    print(schema)
+    properties = schema['properties']['data']['properties']
+    if expected == None:
+        assert 'versioned_field' not in properties
+    else:
+        doc = properties['versioned_field']['description']
+        assert doc == expected