Add setting to disable list diff minimization

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - Added support to treat `Mapping` type annotations as dictionaries.
 - Fixed handling of default values for `dataclass` attributes.
+- Added `MINIMIZE_LIST_DIFFS` setting to control the semantic representation of empty lists.
 
 # 0.10 (2020-07-03)
 

datafiles/converters/containers.py

@@ -5,6 +5,7 @@
 
 import log
 
+from .. import settings
 from ..utils import Missing, get_default_field_value
 from ._bases import Converter
 
@@ -81,7 +82,10 @@ def to_preserialization_data(cls, python_value, *, default_to_skip=None):
         if data == default_to_skip:
             data.clear()
 
-        return data or [None]
+        if settings.MINIMIZE_LIST_DIFFS:
+            return data or [None]
+
+        return data
 
 
 class Dictionary(Converter):

datafiles/settings.py

@@ -6,4 +6,6 @@
 
 INDENT_YAML_BLOCKS = True
 
+MINIMIZE_LIST_DIFFS = True
+
 YAML_LIBRARY = 'ruamel.yaml'

datafiles/tests/test_converters.py

@@ -7,7 +7,7 @@
 import pytest
 from ruamel.yaml.scalarstring import LiteralScalarString
 
-from datafiles import converters
+from datafiles import converters, settings
 
 
 @dataclass
@@ -313,6 +313,11 @@ def when_dataclass_with_default(expect):
             )
             expect(data) == {'flag': True}
 
+        def when_empty_list_and_diff_minimization_disabled(expect, monkeypatch):
+            monkeypatch.setattr(settings, 'MINIMIZE_LIST_DIFFS', False)
+            data = StringList.to_preserialization_data([])
+            expect(data) == []
+
 
 def describe_register():
     def with_new_type(expect):

docs/settings.md

@@ -1,6 +1,6 @@
 <h1>Settings</h1>
 
-For libraries that wish to temporarily alter any of the previously described behavior, a handful of settings can be set at the module level. All boolean settings default to `True` unless otherwise noted.
+For clients that wish to temporarily alter any of the previously described behaviors, a handful of settings can be controlled at the module level. All values default to `True` unless otherwise noted.
 
 # `HIDE_TRACEBACK_IN_HOOKS`
 
@@ -14,7 +14,7 @@ datafiles.settings.HIDE_TRACEBACK_IN_HOOKS = False
 
 # `HOOKS_ENABLED`
 
-When running unit tests for a library using `datafiles`,
+When running unit tests for a client using `datafiles`,
 it can be helpful to disable automatic loading/saving of models for performance and to avoid writing files to disk:
 
 ```python
@@ -36,7 +36,7 @@ items:
   - 3
 ```
 
-To make it easier to upgrade to this version, a library can disable this functionality:
+To make it easier to upgrade to this version, a client can disable this functionality:
 
 ```python
 import datafiles
@@ -51,6 +51,26 @@ items:
 - 1
 - 2
 - 3
+
+# `MINIMIZE_LIST_DIFFS`
+
+When serializing lists, `datafiles` intentionally deviates from the semantic representation of an empty list to optimize for the use case of storing YAML files in version control.
+
+By storing any empty list of `items` as:
+
+```yaml
+items:
+  -
+```
+
+adding or removing an item always results in a one-line change. Where as adding items to `items: []` produces a noisier diff and requires knowledge of the YAML specification to edit files by hand.
+
+To disable this behavior:
+
+```python
+import datafiles
+
+datafiles.settings.MINIMIZE_LIST_DIFFS = False
 ```
 
 # `YAML_LIBRARY`

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 
 name = "datafiles"
-version = "0.11b2"
+version = "0.11b3"
 description = "File-based ORM for dataclasses."
 
 license = "MIT"