Merge pull request #338 from jacebrowning/json5

Add JSON5 support

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Release Notes
 
+## 2.3 (2024-10-30)
+
+- Added support for the [JSON5](https://json5.org) file format.
+
 ## 2.2.3 (2024-05-26)
 
 - Added caching to default factory calls.

Makefile

@@ -127,8 +127,7 @@ notebooks: install
 	@ cd notebooks; for filename in *.ipynb; do \
 	  poetry run papermill $$filename $$filename; \
 	done
-	git config filter.nbstripout.extrakeys 'cell.id cell.metadata.execution cell.metadata.papermill metadata.papermill'
-	poetry run nbstripout --keep-output notebooks/*.ipynb
+	poetry run nbstripout --keep-output --extra-keys="cell.metadata.papermill metadata.papermill" notebooks/*.ipynb
 
 # RELEASE #####################################################################
 

datafiles/formats.py

@@ -7,7 +7,9 @@
 from pathlib import Path
 from typing import IO, Dict, List, Union
 
+import json5
 import log
+from ruamel.yaml import YAML as _YAML
 
 from . import types, utils
 
@@ -54,6 +56,22 @@ def serialize(cls, data):
         return json.dumps(data, indent=2)
 
 
+class JSON5(Formatter):
+    """Formatter for "JSON for Humans" language."""
+
+    @classmethod
+    def extensions(cls):
+        return {".json5"}
+
+    @classmethod
+    def deserialize(cls, file_object):
+        return json5.load(file_object)
+
+    @classmethod
+    def serialize(cls, data):
+        return json5.dumps(data, indent=2)
+
+
 class TOML(Formatter):
     """Formatter for (round-trip) Tom's Obvious Minimal Language."""
 
@@ -83,8 +101,6 @@ def extensions(cls):
 
     @classmethod
     def deserialize(cls, file_object):
-        from ruamel.yaml import YAML as _YAML
-
         yaml = _YAML()
         yaml.preserve_quotes = True  # type: ignore
         try:
@@ -95,8 +111,6 @@ def deserialize(cls, file_object):
 
     @classmethod
     def serialize(cls, data):
-        from ruamel.yaml import YAML as _YAML
-
         yaml = _YAML()
         yaml.register_class(types.List)
         yaml.register_class(types.Dict)

datafiles/tests/test_formats.py

@@ -59,6 +59,12 @@ def with_empty_file(expect, path):
             data = formats.deserialize(path, ".json")
             expect(data) == {}
 
+    def describe_json5():
+        def with_empty_file(expect, path):
+            path.write_text("{}")
+            data = formats.deserialize(path, ".json5")
+            expect(data) == {}
+
     def describe_toml():
         def with_empty_file(expect, path):
             data = formats.deserialize(path, ".toml")

docs/api/manager.md

@@ -12,7 +12,7 @@ class MyModel:
     my_value: int = 0
 ```
 
-Many of the following examples are also shown in this [Jupyter Notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/manager_api.ipynb).
+Many of the following examples are also shown in [this notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/manager_api.ipynb).
 
 ## `get()`
 

docs/api/mapper.md

@@ -16,7 +16,7 @@ class MyModel:
 >>> model = MyModel("foo")
 ```
 
-Many of the following examples are also shown in this [Jupyter Notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/mapper_api.ipynb).
+Many of the following examples are also shown in [this notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/mapper_api.ipynb).
 
 ## `path`
 

docs/formats.md

@@ -25,14 +25,15 @@ my_int: 42
 my_str: Hello, world!
 ```
 
-Where possible, comments and whitespace are preserved in files as shown in this [Jupyter Notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/roundtrip_comments.ipynb).
+Where possible, comments and whitespace are preserved in files as shown in [this notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/roundtrip_comments.ipynb).
 
 ## JSON
 
 The [JSON language](https://www.json.org/) is also supported.
 Any of the following file extensions will use this format:
 
 - `.json`
+- `.json5`
 
 Sample output:
 
@@ -56,7 +57,7 @@ Sample output:
 }
 ```
 
-Additional examples can be found in this [Jupyter Notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/format_options.ipynb).
+Additional examples can be found in [this notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/format_options.ipynb).
 
 ## TOML
 
@@ -83,7 +84,7 @@ value = 2
 value = 0
 ```
 
-Additional examples can be found in this [Jupyter Notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/format_options.ipynb).
+Additional examples can be found in [this notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/format_options.ipynb).
 
 ## Custom Formats
 

docs/types/containers.md

@@ -17,7 +17,7 @@ from typing import List, Optional
 | `foobar: List[int]`           | `foobar = None`   | `foobar:`<br>&nbsp;&nbsp;&nbsp;&nbsp;`-`   |
 | `foobar: Optional[List[int]]` | `foobar = None`   | `foobar:`                                  |
 
-More examples can be found in this [Jupyter Notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/patched_containers.ipynb).
+More examples can be found in [this notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/patched_containers.ipynb).
 
 ## Sets
 
@@ -97,4 +97,4 @@ class Nested:
     qux: str
 ```
 
-More examples can be found in this [Jupyter Notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/nested_dataclass.ipynb).
+More examples can be found in [this notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/nested_dataclass.ipynb).

docs/types/generics.md

@@ -61,4 +61,4 @@ contents:
       - 3.14
 ```
 
-An example of using generic types can be found in this [Jupyter Notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/generic_types.ipynb).
+An example of using generic types can be found in [this notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/generic_types.ipynb).

docs/utilities.md

@@ -42,7 +42,7 @@ numbers:
   - 3
 ```
 
-Additional examples can be found in this [Jupyter Notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/file_inference.ipynb).
+Additional examples can be found in [this notebook](https://github.com/jacebrowning/datafiles/blob/main/notebooks/file_inference.ipynb).
 
 ## `frozen()`
 

notebooks/file_inference.ipynb

@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "id": "e3794ade",
+   "id": "0",
    "metadata": {
     "tags": []
    },
@@ -13,7 +13,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "e8ee27c3",
+   "id": "1",
    "metadata": {
     "tags": []
    },
@@ -40,7 +40,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "418fe5d8",
+   "id": "2",
    "metadata": {
     "tags": []
    },
@@ -67,7 +67,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "17241aab",
+   "id": "3",
    "metadata": {
     "tags": []
    },
@@ -79,7 +79,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "3c493823",
+   "id": "4",
    "metadata": {
     "tags": []
    },

notebooks/files/format_options.json5

@@ -0,0 +1,17 @@
+{
+  "my_dict": {
+    "value": 0
+  },
+  "my_list": [
+    {
+      "value": 1
+    },
+    {
+      "value": 2
+    }
+  ],
+  "my_bool": true,
+  "my_float": 1.23,
+  "my_int": 42,
+  "my_str": "Hello, world!"
+}