Add support for frozen (read only) schemas

docs/source/changelog.rst

@@ -11,6 +11,7 @@ v1.2.0
 New features
 ~~~~~~~~~~~~
 
+- Add support for :ref:`frozen (read only) schemas <guide-schema-frozen-schemas>`.
 - Add :exc:`FieldNotSet` exception to be raised on accessing fields without values.
 - Add :meth:`Schema.copy` method for copying schema instances.
 - Add :meth:`Schema.preprocess_data` for preprocessing of input data.

docs/source/guide/schema.rst

@@ -231,6 +231,30 @@ would be used.
 
 See :ref:`guide-config-schema-config` for information on manipulating schema configuration.
 
+.. _guide-schema-frozen-schemas:
+
+Frozen Schemas
+--------------
+
+Frozen schemas are schemas whose fields cannot be updated once initialized. In other
+words, these schemas are marked as read only.
+
+In order to mark a schema as "frozen", the :attr:`SchemaConfig.frozen` attribute is set
+to ``True``. Whenever a field is attempted to be updated, a :exc:`SchemaFrozenError` is raised.
+
+Example::
+
+    class User(oblate.Schema):
+        id = fields.Integer()
+        username = fields.String()
+
+        class Config(oblate.SchemaConfig):
+            frozen = True
+
+    user = User({'id': 1, 'username': 'test'})
+    user.update({'id': 2})  # SchemaFrozenError: User schema is frozen and cannot be updated.
+    user.id = 1  # SchemaFrozenError: User schema is frozen and cannot be updated.
+
 .. _guide-schema-passing-unknown-fields:
 
 Passing unknown fields

docs/source/reference/exceptions.rst

@@ -9,6 +9,9 @@ Exceptions
 .. autoexception:: FieldNotSet
     :members:
 
+.. autoexception:: SchemaFrozenError
+    :members:
+
 .. autoexception:: FieldError
     :members:
 

oblate/configs.py

@@ -174,3 +174,10 @@ class Config(oblate.SchemaConfig):
     This configuration can be overriden per initialization/update using the
     ``ignore_extra`` parameter in :class:`Schema` initialization.
     """
+
+    frozen = False
+    """Whether the schema is read only.
+
+    When set to True, the schema cannot be updated once initialized. Defaults
+    to False.
+    """

oblate/exceptions.py

@@ -32,6 +32,7 @@
 __all__ = (
     'OblateException',
     'FieldNotSet',
+    'SchemaFrozenError',
     'FieldError',
     'ValidationError'
 )
@@ -71,6 +72,19 @@ def __init__(self, field: Field[Any, Any], schema: Schema, field_name: str) -> N
         super().__init__(f'Field {field._name!r} has no value set', field._name, schema)
 
 
+class SchemaFrozenError(OblateException):
+    """An exception raised when update is performed on a frozen schema.
+
+    Attributes
+    ----------
+    schema: :class:`Schema`
+        The schema that was attempted to be updated.
+    """
+    def __init__(self, schema: Schema) -> None:
+        self.schema = schema
+        super().__init__(f'{schema.__class__.__name__} schema is frozen and cannot be updated')
+
+
 class FieldError(OblateException):
     """An error raised when validation fails for a field.
 

oblate/fields/base.py

@@ -41,7 +41,7 @@
 from oblate.schema import Schema
 from oblate.validate import Validator, ValidatorCallbackT, InputT
 from oblate.utils import MISSING, current_field_key, current_schema
-from oblate.exceptions import FieldError
+from oblate.exceptions import FieldError, SchemaFrozenError
 from oblate.contexts import ErrorContext
 from oblate.configs import config
 
@@ -174,6 +174,9 @@ def __get__(self, instance: Optional[Schema], owner: Type[Schema]) -> Union[Fina
         return instance.get_value_for(self._name)
 
     def __set__(self, instance: Schema, value: RawValueT) -> None:
+        if instance.__config__.frozen:
+            raise SchemaFrozenError(instance)
+
         schema_token = current_schema.set(instance)
         field_name = current_field_key.set(self._name)
         try:

oblate/schema.py

@@ -37,7 +37,7 @@
 from typing_extensions import Self
 from oblate.contexts import SchemaContext, LoadContext, DumpContext
 from oblate.utils import MISSING, current_field_key, current_context, current_schema
-from oblate.exceptions import FieldError, FieldNotSet
+from oblate.exceptions import FieldError, FieldNotSet, SchemaFrozenError
 from oblate.configs import config, SchemaConfig
 
 import collections.abc
@@ -403,6 +403,9 @@ def update(self, data: Mapping[str, Any], /, *, ignore_extra: bool = MISSING) ->
         ValidationError
             The validation failed.
         """
+        if self.__config__.frozen:
+            raise SchemaFrozenError(self)
+
         if ignore_extra is MISSING:
             ignore_extra = self.__config__.ignore_extra
 

tests/test_configs.py

@@ -132,3 +132,31 @@ class Config(oblate.SchemaConfig):
 
     with pytest.raises(RuntimeError):
         schema.get_value_for('test')
+
+
+def test_schema_config_frozen():
+    class _SchemaDefault(oblate.Schema):
+        id = oblate.fields.Integer()
+
+    class _SchemaFrozen(oblate.Schema):
+        id = oblate.fields.Integer()
+
+        class Config(oblate.SchemaConfig):
+            frozen = True
+
+    s = _SchemaDefault({'id': 1})
+    assert s.id == 1
+
+    s.update({'id': 2})
+    assert s.id == 2
+
+    s.id = 3
+    assert s.id == 3
+
+    schema = _SchemaFrozen({'id': 1})
+
+    with pytest.raises(oblate.SchemaFrozenError, match='_SchemaFrozen schema is frozen and cannot be updated'):
+        schema.update({'id': 2})
+
+    with pytest.raises(oblate.SchemaFrozenError, match='_SchemaFrozen schema is frozen and cannot be updated'):
+        schema.id = 3