gh-126175: Add attributes to TOMLDecodeError. Deprecate free-form `__…

…init__` args (GH-126428)

Doc/library/tomllib.rst

@@ -60,9 +60,36 @@ This module defines the following functions:
 
 The following exceptions are available:
 
-.. exception:: TOMLDecodeError
+.. exception:: TOMLDecodeError(msg, doc, pos)
 
-   Subclass of :exc:`ValueError`.
+   Subclass of :exc:`ValueError` with the following additional attributes:
+
+   .. attribute:: msg
+
+      The unformatted error message.
+
+   .. attribute:: doc
+
+      The TOML document being parsed.
+
+   .. attribute:: pos
+
+      The index of *doc* where parsing failed.
+
+   .. attribute:: lineno
+
+      The line corresponding to *pos*.
+
+   .. attribute:: colno
+
+      The column corresponding to *pos*.
+
+   .. versionchanged:: next
+      Added the *msg*, *doc* and *pos* parameters.
+      Added the :attr:`msg`, :attr:`doc`, :attr:`pos`, :attr:`lineno` and :attr:`colno` attributes.
+
+   .. deprecated:: next
+      Passing free-form positional arguments is deprecated.
 
 
 Examples

Lib/test/test_tomllib/test_error.py

@@ -49,7 +49,9 @@ def test_type_error(self):
         self.assertEqual(str(exc_info.exception), "Expected str object, not 'bool'")
 
     def test_module_name(self):
-        self.assertEqual(tomllib.TOMLDecodeError().__module__, tomllib.__name__)
+        self.assertEqual(
+            tomllib.TOMLDecodeError("", "", 0).__module__, tomllib.__name__
+        )
 
     def test_invalid_parse_float(self):
         def dict_returner(s: str) -> dict:
@@ -64,3 +66,33 @@ def list_returner(s: str) -> list:
             self.assertEqual(
                 str(exc_info.exception), "parse_float must not return dicts or lists"
             )
+
+    def test_deprecated_tomldecodeerror(self):
+        for args in [
+            (),
+            ("err msg",),
+            (None,),
+            (None, "doc"),
+            ("err msg", None),
+            (None, "doc", None),
+            ("err msg", "doc", None),
+            ("one", "two", "three", "four"),
+            ("one", "two", 3, "four", "five"),
+        ]:
+            with self.assertWarns(DeprecationWarning):
+                e = tomllib.TOMLDecodeError(*args)  # type: ignore[arg-type]
+            self.assertEqual(e.args, args)
+
+    def test_tomldecodeerror(self):
+        msg = "error parsing"
+        doc = "v=1\n[table]\nv='val'"
+        pos = 13
+        formatted_msg = "error parsing (at line 3, column 2)"
+        e = tomllib.TOMLDecodeError(msg, doc, pos)
+        self.assertEqual(e.args, (formatted_msg,))
+        self.assertEqual(str(e), formatted_msg)
+        self.assertEqual(e.msg, msg)
+        self.assertEqual(e.doc, doc)
+        self.assertEqual(e.pos, pos)
+        self.assertEqual(e.lineno, 3)
+        self.assertEqual(e.colno, 2)