From 25a1d8963a551bb287043cdf3bfd32f83994f8db Mon Sep 17 00:00:00 2001 From: Nate Clark Date: Wed, 20 Feb 2019 08:30:13 -0600 Subject: [PATCH] Add draft changelog file and migration blurb --- doc/build/changelog/migration_13.rst | 37 ++++++++++++++++++++++ doc/build/changelog/unreleased_13/4500.rst | 18 +++++++++++ 2 files changed, 55 insertions(+) create mode 100644 doc/build/changelog/unreleased_13/4500.rst 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". -- 2.47.3