From ff3d509a144b065ea4e6dec05aba1d7164909410 Mon Sep 17 00:00:00 2001
From: Sam May <ag@eitilt.life>
Date: Thu, 15 Jun 2023 20:06:46 +0000
Subject: [PATCH] DOCS: Use actual TOML rather than a strawman
The example file looks to have been machine-generated and (being generous) written to an old version of the standard, and does not present an accurate counter-example to the YAML. This updates it to be (closer to) TOML as it might actually be written.
*Actual* actual TOML would very likely not include story/test names as the keys and instead simply something like `[map.variations.one-key]", with the full `"Mappings with defined keys (Map)"`, etc., names being defined as data-pairs within that, but I consider that a wart of the schema rather than of the language used.
---
hitch/story/map.toml | 198 +++++++++++++++++++------------------------
1 file changed, 86 insertions(+), 112 deletions(-)
diff --git a/hitch/story/map.toml b/hitch/story/map.toml
index e4c709b..40db51f 100644
--- a/hitch/story/map.toml
+++ b/hitch/story/map.toml
@@ -1,141 +1,115 @@
["Mappings with defined keys (Map)"]
-docs = "compound/mapping"
-"based on" = "strictyaml"
-description = "Mappings of one value to another are represented by : in YAML\nand parsed as python dicts.\n\nUsing StrictYAML's 'Map' you can validate that a mapping\ncontains the right keys and the right *type* of values.\n\nNote: for mappings where you don't know the exact names of\nthe keys in advance but you do know the type, use MapPattern.\n"
+ docs = "compound/mapping"
+ "based on" = "strictyaml"
+ description = """
+Mappings of one value to another are represented by : in YAML \
+and parsed as python dicts.
-["Mappings with defined keys (Map)".given]
-setup = "from collections import OrderedDict\nfrom strictyaml import Map, Int, load, as_document\nfrom collections import OrderedDict\nfrom ensure import Ensure\n\nschema = Map({\"a\": Int(), \"b\": Int(), \"c\": Int()})\n\nschema_2 = Map({u\"â\": Int(), \"b\": Int(), \"c\": Int()})\n"
-yaml_snippet = "â: 1\nb: 2\nc: 3\n"
+Using StrictYAML's 'Map' you can validate that a mapping \
+contains the right keys and the right *type* of values.
-["Mappings with defined keys (Map)".variations]
+Note: for mappings where you don't know the exact names of \
+the keys in advance but you do know the type, use MapPattern."""
-["Mappings with defined keys (Map)".variations."one key mapping"]
+ given.setup = """
+from collections import OrderedDict
+from strictyaml import Map, Int, load, as_document
+from collections import OrderedDict
+from ensure import Ensure
-["Mappings with defined keys (Map)".variations."one key mapping".given]
-yaml_snippet = "x: 1"
+schema = Map({"a": Int(), "b": Int(), "c": Int()})
-[["Mappings with defined keys (Map)".variations."one key mapping".steps]]
-Run = "Ensure(load(yaml_snippet, Map({\"x\": Int()})).data).equals(OrderedDict([('x', 1)]))\n"
+schema_2 = Map({u"â": Int(), "b": Int(), "c": Int()})"""
+ given.yaml_snippet = "â: 1\nb: 2\nc: 3"
-["Mappings with defined keys (Map)".variations."key value"]
+["Mappings with defined keys (Map)".variations."one key mapping"]
+ given.yaml_snippet = "x: 1"
+ [["Mappings with defined keys (Map)".variations."one key mapping".steps]]
+ Run = """Ensure(load(yaml_snippet, Map({"x": Int()})).data).equals(OrderedDict([('x', 1)]))"""
[["Mappings with defined keys (Map)".variations."key value".steps]]
-Run = "Ensure(load(yaml_snippet, schema_2)[u'â']).equals(1)\n"
-
-["Mappings with defined keys (Map)".variations."get item key not found"]
+ Run = "Ensure(load(yaml_snippet, schema_2)[u'â']).equals(1)"
[["Mappings with defined keys (Map)".variations."get item key not found".steps]]
-
-["Mappings with defined keys (Map)".variations."get item key not found".steps.Run]
-code = "load(yaml_snippet, schema_2)['keynotfound']"
-
-["Mappings with defined keys (Map)".variations."get item key not found".steps.Run.raises]
-message = "'keynotfound'"
-
-["Mappings with defined keys (Map)".variations."cannot use .text"]
+ Run.code = "load(yaml_snippet, schema_2)['keynotfound']"
+ Run.raises.message = "'keynotfound'"
[["Mappings with defined keys (Map)".variations."cannot use .text".steps]]
-
-["Mappings with defined keys (Map)".variations."cannot use .text".steps.Run]
-code = "load(yaml_snippet, schema_2).text"
-
-["Mappings with defined keys (Map)".variations."cannot use .text".steps.Run.raises]
-
-["Mappings with defined keys (Map)".variations."cannot use .text".steps.Run.raises.type]
-"in python 3" = "builtins.TypeError"
-"in python 2" = "exceptions.TypeError"
-
-["Mappings with defined keys (Map)".variations."cannot use .text".steps.Run.raises.message]
-"in python 3" = "YAML(OrderedDict([('â', 1), ('b', 2), ('c', 3)])) is a mapping, has no text value."
-"in python 2" = "YAML(OrderedDict([(u'\\xe2', 1), ('b', 2), ('c', 3)])) is a mapping, has no text value."
+ Run.code = "load(yaml_snippet, schema_2).text"
+ ["Mappings with defined keys (Map)".variations."cannot use .text".steps.Run.raises.type]
+ "in python 3" = "builtins.TypeError"
+ "in python 2" = "exceptions.TypeError"
+ ["Mappings with defined keys (Map)".variations."cannot use .text".steps.Run.raises.message]
+ "in python 3" = "YAML(OrderedDict([('â', 1), ('b', 2), ('c', 3)])) is a mapping, has no text value."
+ "in python 2" = "YAML(OrderedDict([(u'\\xe2', 1), ('b', 2), ('c', 3)])) is a mapping, has no text value."
["Mappings with defined keys (Map)".variations."parse snippet where key is not found in schema"]
-
-["Mappings with defined keys (Map)".variations."parse snippet where key is not found in schema".given]
-yaml_snippet = "a: 1\nb: 2\nâ: 3 \n"
-
-[["Mappings with defined keys (Map)".variations."parse snippet where key is not found in schema".steps]]
-
-["Mappings with defined keys (Map)".variations."parse snippet where key is not found in schema".steps.Run]
-code = "load(yaml_snippet, schema)"
-
-["Mappings with defined keys (Map)".variations."parse snippet where key is not found in schema".steps.Run.raises]
-type = "strictyaml.exceptions.YAMLValidationError"
-message = "while parsing a mapping\nunexpected key not in schema 'â'\n in \"<unicode string>\", line 3, column 1:\n \"\\xE2\": '3'\n ^ (line: 3)"
+ given.yaml_snippet = "a: 1\nb: 2\nâ: 3"
+ [["Mappings with defined keys (Map)".variations."parse snippet where key is not found in schema".steps]]
+ Run.code = "load(yaml_snippet, schema)"
+ Run.raises.type = "strictyaml.exceptions.YAMLValidationError"
+ Run.raises.message = """
+while parsing a mapping
+unexpected key not in schema 'â'
+ in "<unicode string>", line 3, column 1:
+ "\\xE2": '3'
+ ^ (line: 3)"""
["Mappings with defined keys (Map)".variations."sequence not expected when parsing"]
-
-["Mappings with defined keys (Map)".variations."sequence not expected when parsing".given]
-yaml_snippet = "- 1\n- 2\n- 3 \n"
-
-[["Mappings with defined keys (Map)".variations."sequence not expected when parsing".steps]]
-
-["Mappings with defined keys (Map)".variations."sequence not expected when parsing".steps.Run]
-code = "load(yaml_snippet, schema)"
-
-["Mappings with defined keys (Map)".variations."sequence not expected when parsing".steps.Run.raises]
-type = "strictyaml.exceptions.YAMLValidationError"
-message = "when expecting a mapping\n in \"<unicode string>\", line 1, column 1:\n - '1'\n ^ (line: 1)\nfound a sequence\n in \"<unicode string>\", line 3, column 1:\n - '3'\n ^ (line: 3)"
-
-["Mappings with defined keys (Map)".variations."List not expected when serializing"]
+ given.yaml_snippet = "- 1\n- 2\n- 3"
+ [["Mappings with defined keys (Map)".variations."sequence not expected when parsing".steps]]
+ Run.code = "load(yaml_snippet, schema)"
+ Run.raises.type = "strictyaml.exceptions.YAMLValidationError"
+ Run.raises.message = """
+when expecting a mapping
+ in "<unicode string>", line 1, column 1:
+ - '1'
+ ^ (line: 1)
+found a sequence
+ in "<unicode string>", line 3, column 1:
+ - '3'
+ ^ (line: 3)"""
[["Mappings with defined keys (Map)".variations."List not expected when serializing".steps]]
-
-["Mappings with defined keys (Map)".variations."List not expected when serializing".steps.Run]
-code = "as_document([1, 2, 3], schema)"
-
-["Mappings with defined keys (Map)".variations."List not expected when serializing".steps.Run.raises]
-type = "strictyaml.exceptions.YAMLSerializationError"
-message = "Expected a dict, found '[1, 2, 3]'"
-
-["Mappings with defined keys (Map)".variations."Empty dict not valid when serializing"]
+ Run.code = "as_document([1, 2, 3], schema)"
+ Run.raises.type = "strictyaml.exceptions.YAMLSerializationError"
+ Run.raises.message = "Expected a dict, found '[1, 2, 3]'"
[["Mappings with defined keys (Map)".variations."Empty dict not valid when serializing".steps]]
-
-["Mappings with defined keys (Map)".variations."Empty dict not valid when serializing".steps.Run]
-code = "as_document({}, schema)"
-
-["Mappings with defined keys (Map)".variations."Empty dict not valid when serializing".steps.Run.raises]
-type = "strictyaml.exceptions.YAMLSerializationError"
-message = "Expected a non-empty dict, found an empty dict.\nUse EmptyDict validator to serialize empty dicts."
+ Run.code = "as_document({}, schema)"
+ Run.raises.type = "strictyaml.exceptions.YAMLSerializationError"
+ Run.raises.message = """
+Expected a non-empty dict, found an empty dict.
+Use EmptyDict validator to serialize empty dicts."""
["Mappings with defined keys (Map)".variations."Unexpected key"]
-
-["Mappings with defined keys (Map)".variations."Unexpected key".given]
-yaml_snippet = "a: 1\nb: 2\nc: 3\nd: 4\n"
-
-[["Mappings with defined keys (Map)".variations."Unexpected key".steps]]
-
-["Mappings with defined keys (Map)".variations."Unexpected key".steps.Run]
-code = "load(yaml_snippet, schema)"
-
-["Mappings with defined keys (Map)".variations."Unexpected key".steps.Run.raises]
-type = "strictyaml.exceptions.YAMLValidationError"
-message = "while parsing a mapping\nunexpected key not in schema 'd'\n in \"<unicode string>\", line 4, column 1:\n d: '4'\n ^ (line: 4)"
+ given.yaml_snippet = "a: 1\nb: 2\nc: 3\nd: 4"
+ [["Mappings with defined keys (Map)".variations."Unexpected key".steps]]
+ Run.code = "load(yaml_snippet, schema)"
+ Run.raises.type = "strictyaml.exceptions.YAMLValidationError"
+ Run.raises.message = """
+while parsing a mapping
+unexpected key not in schema 'd'
+ in "<unicode string>", line 4, column 1:
+ d: '4'
+ ^ (line: 4)"""
["Mappings with defined keys (Map)".variations."required key not found"]
-
-["Mappings with defined keys (Map)".variations."required key not found".given]
-yaml_snippet = "a: 1\n"
-
-[["Mappings with defined keys (Map)".variations."required key not found".steps]]
-
-["Mappings with defined keys (Map)".variations."required key not found".steps.Run]
-code = "load(yaml_snippet, schema)"
-
-["Mappings with defined keys (Map)".variations."required key not found".steps.Run.raises]
-type = "strictyaml.exceptions.YAMLValidationError"
-message = "while parsing a mapping\nrequired key(s) 'b', 'c' not found\n in \"<unicode string>\", line 1, column 1:\n a: '1'\n ^ (line: 1)"
+ given.yaml_snippet = "a: 1"
+ [["Mappings with defined keys (Map)".variations."required key not found".steps]]
+ Run.code = "load(yaml_snippet, schema)"
+ Run.raises.type = "strictyaml.exceptions.YAMLValidationError"
+ Run.raises.message = """
+while parsing a mapping
+required key(s) 'b', 'c' not found
+ in "<unicode string>", line 1, column 1:
+ a: '1'
+ ^ (line: 1)"""
["Mappings with defined keys (Map)".variations.iterator]
-
-["Mappings with defined keys (Map)".variations.iterator.given]
-yaml_snippet = "a: 1\nb: 2\nc: 3\n"
-
-[["Mappings with defined keys (Map)".variations.iterator.steps]]
-Run = "assert [item for item in load(yaml_snippet, schema)] == [\"a\", \"b\", \"c\"]\n"
-
-["Mappings with defined keys (Map)".variations.serialize]
+ given.yaml_snippet = "a: 1\nb: 2\nc: 3"
+ [["Mappings with defined keys (Map)".variations.iterator.steps]]
+ Run = """assert [item for item in load(yaml_snippet, schema)] == ["a", "b", "c"]"""
[["Mappings with defined keys (Map)".variations.serialize.steps]]
-Run = "assert as_document(OrderedDict([(u\"â\", 1), (\"b\", 2), (\"c\", 3)]), schema_2).as_yaml() == yaml_snippet\n"
+ Run = """assert as_document(OrderedDict([(u"â", 1), ("b", 2), ("c", 3)]), schema_2).as_yaml() == yaml_snippet"""