From: Nate Clark <natec425@gmail.com>
Date: Wed, 20 Feb 2019 14:30:13 +0000 (-0600)
Subject: Add draft changelog file and migration blurb
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=25a1d8963a551bb287043cdf3bfd32f83994f8db;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Add draft changelog file and migration blurb
---

diff --git a/doc/build/changelog/migration_13.rst b/doc/build/changelog/migration_13.rst
index c133bd6620..946ef1ba53 100644
--- a/doc/build/changelog/migration_13.rst
+++ b/doc/build/changelog/migration_13.rst
@@ -1662,3 +1662,40 @@ primary key column::
 :ticket:`4362`
 
 :ticket:`4235`
+
+Changed StatementError formatting (newlines and %s) 
+=================================================================================
+
+Two changes are introduced to ``StatementError``'s string representation.
+
+#. Previously: single line.
+   Now: each "detail" on it's own line.
+#. Previously: SQL in the message was emitted using ``__repr__``
+   Now: SQL in the message is emitted using ``__str__``
+
+This means that an error message that previously looked like this:
+    
+    sqlalchemy.exc.StatementError: (sqlalchemy.exc.InvalidRequestError) A value is required for bind parameter 'id' [SQL: 'select * from reviews where id = %(id)s'] (Background on this error at: http://sqlalche.me/e/cd3x)
+
+    (sqlalchemy.exc.InvalidRequestError) A value is required for bind parameter 'id' [SQL: 'select * from reviews where id = %(id)s'] (Background on this error at: http://sqlalche.me/e/cd3x)
+
+Will now look like this:
+
+    sqlalchemy.exc.StatementError: (sqlalchemy.exc.InvalidRequestError) A value is required for bind parameter 'id'
+    [SQL: select * from reviews where id = %(id)s]
+    (Background on this error at: http://sqlalche.me/e/cd3x)
+    
+    (sqlalchemy.exc.InvalidRequestError) A value is required for bind parameter 'id'
+    [SQL: select * from reviews where id = %(id)s]
+    (Background on this error at: http://sqlalche.me/e/cd3x)
+
+The primary impact of this change is that consumers can no longer assume:
+
+#. an exception message is on a single line
+#. SQL contained in an exception message will be escaped and on a single line.
+
+SQL being rendered with ``__str__`` instead of ``__repr__`` is the more interesting of the two.
+For one example, newlines will actually be rendered instead of escaped.
+
+:ticket:`4500`
+
diff --git a/doc/build/changelog/unreleased_13/4500.rst b/doc/build/changelog/unreleased_13/4500.rst
new file mode 100644
index 0000000000..70792e14d8
--- /dev/null
+++ b/doc/build/changelog/unreleased_13/4500.rst
@@ -0,0 +1,18 @@
+.. change::
+   :tags: errors
+   :tickets: 4500
+
+   Change StatementError formatting (newlines and %s)
+    
+   This changes the error formatting for StatementError in two ways:
+   
+   1) Break each error detail up over multiple newlines instead of
+      spaced out on a single line. Hopefully, this helps readers scan
+      the error message more easily.
+   
+   2) Change the SQL representation in the message to use __str__ (%s)
+      instead of the current behavior that uses __repr__ (%r). This
+      should help readers recognize the structure of their SQL,
+      particularly if it is a multiline SQL statement. In the multiline
+      case, the SQL would be printed over multiple lines instead of
+      printing an escaped "\n".