Raise ValueError when indent is negative. Update README

Author: hukkin

README.md

@@ -17,7 +17,8 @@
   - [Write to file](#write-to-file)
 - [FAQ](#faq)
   - [Does Tomli-W sort the document?](#does-tomli-w-sort-the-document)
-  - [Does Tomli-W support writing documents with comments or custom whitespace?](#does-tomli-w-support-writing-documents-with-comments-or-custom-whitespace)
+  - [Does Tomli-W support writing documents with comments?](#does-tomli-w-support-writing-documents-with-comments)
+  - [Can I customize insignificant whitespace?](#can-i-customize-insignificant-whitespace)
   - [Why does Tomli-W not write a multi-line string if the string value contains newlines?](#why-does-tomli-w-not-write-a-multi-line-string-if-the-string-value-contains-newlines)
   - [Is Tomli-W output guaranteed to be valid TOML?](#is-tomli-w-output-guaranteed-to-be-valid-toml)
 
@@ -73,10 +74,29 @@ with open("path_to_file/conf.toml", "wb") as f:
 No, but it respects sort order of the input data,
 so one could sort the content of the `dict` (recursively) before calling `tomli_w.dumps`.
 
-### Does Tomli-W support writing documents with comments or custom whitespace?<a name="does-tomli-w-support-writing-documents-with-comments-or-custom-whitespace"></a>
+### Does Tomli-W support writing documents with comments?<a name="does-tomli-w-support-writing-documents-with-comments"></a>
 
 No.
 
+### Can I customize insignificant whitespace?<a name="can-i-customize-insignificant-whitespace"></a>
+
+Indent width of array content can be configured via the `indent` keyword argument.
+`indent` takes a non-negative integer, defaulting to 4.
+
+```python
+import tomli_w
+
+doc = {"fruits": ["orange", "kiwi", "papaya"]}
+expected_toml = """\
+fruits = [
+ "orange",
+ "kiwi",
+ "papaya",
+]
+"""
+assert tomli_w.dumps(doc, indent=1) == expected_toml
+```
+
 ### Why does Tomli-W not write a multi-line string if the string value contains newlines?<a name="why-does-tomli-w-not-write-a-multi-line-string-if-the-string-value-contains-newlines"></a>
 
 This default was chosen to achieve lossless parse/write round-trips.
@@ -117,3 +137,11 @@ No.
 If there's a chance that your input data is bad and you need output validation,
 parse the output string once with `tomli.loads`.
 If the parse is successful (does not raise `tomli.TOMLDecodeError`) then the string is valid TOML.
+
+Examples of bad input data that can lead to writing invalid TOML without an error being raised include:
+
+- A mapping where keys behave very much like strings, but aren't. E.g. a tuple of strings of length 1.
+- A mapping where a value is a subclass of a supported type, but which overrides the `__str__` method.
+
+Given proper input (a mapping consisting of non-subclassed [types returned by Tomli](https://github.com/hukkin/tomli?tab=readme-ov-file#how-do-toml-types-map-into-python-types))
+the output should be valid TOML.

src/tomli_w/_writer.py

@@ -25,6 +25,19 @@
 )
 
 
+class Context(NamedTuple):
+    allow_multiline: bool
+    # cache rendered inline tables (mapping from object id to rendered inline table)
+    inline_table_cache: dict[int, str]
+    indent_str: str
+
+
+def make_context(multiline_strings: bool, indent: int) -> Context:
+    if indent < 0:
+        raise ValueError("Indent width must be non-negative")
+    return Context(multiline_strings, {}, " " * indent)
+
+
 def dump(
     obj: Mapping[str, Any],
     fp: IO[bytes],
@@ -33,25 +46,18 @@ def dump(
     multiline_strings: bool = False,
     indent: int = 4,
 ) -> None:
-    ctx = Context(multiline_strings, {}, " " * indent)
+    ctx = make_context(multiline_strings, indent)
     for chunk in gen_table_chunks(obj, ctx, name=""):
         fp.write(chunk.encode())
 
 
 def dumps(
     obj: Mapping[str, Any], /, *, multiline_strings: bool = False, indent: int = 4
 ) -> str:
-    ctx = Context(multiline_strings, {}, " " * indent)
+    ctx = make_context(multiline_strings, indent)
     return "".join(gen_table_chunks(obj, ctx, name=""))
 
 
-class Context(NamedTuple):
-    allow_multiline: bool
-    # cache rendered inline tables (mapping from object id to rendered inline table)
-    inline_table_cache: dict[int, str]
-    indent_str: str
-
-
 def gen_table_chunks(
     table: Mapping[str, Any],
     ctx: Context,

tests/test_invalid.py

@@ -14,3 +14,8 @@ def test_invalid_time():
     offset_time = time(23, 59, 59, tzinfo=timezone.utc)
     with pytest.raises(ValueError):
         tomli_w.dumps({"offset time": offset_time})
+
+
+def test_negative_indent():
+    with pytest.raises(ValueError):
+        tomli_w.dumps({"k": "v"}, indent=-1)

tests/test_style.py

@@ -275,13 +275,30 @@ def test_multiline_in_aot():
 
 
 def test_array_indent_override():
-    data = {"k0": ["v1", "v2"]}
+    data = {"k0": ["v1", "v2", ["v3", "v4"]]}
     assert (
         tomli_w.dumps(data, indent=2)
         == """\
 k0 = [
   "v1",
   "v2",
+  [
+    "v3",
+    "v4",
+  ],
+]
+"""
+    )
+    assert (
+        tomli_w.dumps(data, indent=0)
+        == """\
+k0 = [
+"v1",
+"v2",
+[
+"v3",
+"v4",
+],
 ]
 """
     )