Validate [metadata].schema_version

It's okay to be missing, but if it's given it must be an expected
version (i.e. currently, 1).

Author: warsaw

Lib/site.py

@@ -207,7 +207,14 @@ def _read_site_toml(sitedir, name):
         _trace(f"Error parsing {fullname!r}: {exc}")
         return None
 
-    metadata = data.get("metadata", [])
+    metadata = data.get("metadata", {})
+    # Validate the TOML schema version.  PEP XXX defines schema_version == 1.  Both the [metadata]
+    # section and [metadata].schema_version are optional, but if missing, future compatibility
+    # cannot be guaranteed.
+    if (schema_version := metadata.get("schema_version")) is not None:
+        if schema_version != 1:
+            _trace(f"Unsupported [metadata].schema_version: {schema_version}")
+            return None
 
     # Validate [paths].dirs
     dirs = []

Lib/test/test_site.py

@@ -961,6 +961,27 @@ def test_read_site_toml_basic(self):
         self.assertEqual(tomldata.dirs, ['subdir'])
         self.assertEqual(tomldata.init, ['os'])
 
+    def test_missing_schema_version_is_okay(self):
+        # It's okay for the schema_version to be missing, or even the [metadata] section entirely
+        # (which is tested below).  A missing schema_version just means that no future compatibility
+        # can be guaranteed.
+        name = self._make_site_toml("""\
+[metadata]
+""")
+        tomldata = site._read_site_toml(self.sitedir, name)
+        self.assertIsNotNone(tomldata)
+        self.assertEqual(tomldata.metadata, {})
+
+    def test_unexpected_schema_version_is_not_okay(self):
+        # If [metadata].schema_version exists, but isn't a supported number, then the entire TOML
+        # file is invalid and ignored.
+        name = self._make_site_toml("""\
+[metadata]
+schema_version = 801
+""")
+        tomldata = site._read_site_toml(self.sitedir, name)
+        self.assertIsNone(tomldata)
+
     def test_read_site_toml_parse_error(self):
         # Invalid pkg.site.toml content is skipped.
         name = self._make_site_toml("not valid [[[toml")
@@ -996,7 +1017,7 @@ def test_read_site_toml_empty_file(self):
         # Empty .site.toml is a no-op.
         name = self._make_site_toml("")
         tomldata = site._read_site_toml(self.sitedir, name)
-        self.assertEqual(tomldata.metadata, [])
+        self.assertEqual(tomldata.metadata, {})
         self.assertEqual(tomldata.dirs, [])
         self.assertEqual(tomldata.init, [])