From 121e10c29c5b412fddf0326939f1fe46c3ad9d4a Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Thu, 29 Jul 2021 16:30:12 -0700
Subject: [PATCH] Doumentation and test for utils.parse_metadata(), closes
 #1405

---
 docs/internals.rst  | 18 ++++++++++++++++++
 tests/test_utils.py | 16 ++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/docs/internals.rst b/docs/internals.rst
index 98df998a..1e41cacd 100644
--- a/docs/internals.rst
+++ b/docs/internals.rst
@@ -795,3 +795,21 @@ By default all actors are denied access to the ``view-database`` permission for
 Plugins can access this database by calling ``db = datasette.get_database("_internal")`` and then executing queries using the :ref:`Database API <internals_database>`.
 
 You can explore an example of this database by `signing in as root <https://latest.datasette.io/login-as-root>`__ to the ``latest.datasette.io`` demo instance and then navigating to `latest.datasette.io/_internal <https://latest.datasette.io/_internal>`__.
+
+.. _internals_utils:
+
+The datasette.utils module
+==========================
+
+The ``datasette.utils`` module contains various utility functions used by Datasette. As a general rule you should consider anything in this module to be unstable - functions and classes here could change without warning or be removed entirely between Datasette releases, without being mentioned in the release notes.
+
+The exception to this rule is anythang that is documented here. If you find a need for an undocumented utility function in your own work, consider `opening an issue <https://github.com/simonw/datasette/issues/new>`__ requesting that the function you are using be upgraded to documented and supported status.
+
+.. _internals_utils_parse_metadata:
+
+parse_metadata(content)
+-----------------------
+
+This function accepts a string containing either JSON or YAML, expected to be of the format described in :ref:`metadata`. It returns a nested Python dictionary representing the parsed data from that string.
+
+If the metadata cannot be parsed as either JSON or YAML the function will raise a ``utils.BadMetadataError`` exception.
diff --git a/tests/test_utils.py b/tests/test_utils.py
index be3daf2e..97b70ee5 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -610,3 +610,19 @@ async def test_initial_path_for_datasette(tmp_path_factory, dbs, expected_path):
     )
     path = await utils.initial_path_for_datasette(datasette)
     assert path == expected_path
+
+
+@pytest.mark.parametrize(
+    "content,expected",
+    (
+        ("title: Hello", {"title": "Hello"}),
+        ('{"title": "Hello"}', {"title": "Hello"}),
+        ("{{ this }} is {{ bad }}", None),
+    ),
+)
+def test_parse_metadata(content, expected):
+    if expected is None:
+        with pytest.raises(utils.BadMetadataError):
+            utils.parse_metadata(content)
+    else:
+        assert utils.parse_metadata(content) == expected