diff options
author | Mike Bayer <mike_mp@zzzcomputing.com> | 2015-06-10 10:48:16 -0400 |
---|---|---|
committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2015-06-10 10:48:16 -0400 |
commit | a463bb31ea8a93ffd15e4fb7cc71d84c4d206572 (patch) | |
tree | f568787521a730fb9abec5479e17a5c22dc22cf2 | |
parent | a9030d0241964c919b099e4bdb75d38fd420b546 (diff) | |
download | sqlalchemy-a463bb31ea8a93ffd15e4fb7cc71d84c4d206572.tar.gz |
- add an 0.9 migration note regarding TypeEngine's default
constructor removal; fixes #3446
-rw-r--r-- | doc/build/changelog/migration_09.rst | 66 |
1 files changed, 65 insertions, 1 deletions
diff --git a/doc/build/changelog/migration_09.rst b/doc/build/changelog/migration_09.rst index 4904dcfdf..b07aed925 100644 --- a/doc/build/changelog/migration_09.rst +++ b/doc/build/changelog/migration_09.rst @@ -9,7 +9,7 @@ What's New in SQLAlchemy 0.9? and SQLAlchemy version 0.9, which had its first production release on December 30, 2013. - Document last updated: February 28, 2014 + Document last updated: June 10, 2015 Introduction ============ @@ -402,6 +402,70 @@ This is a small change demonstrated as follows:: Behavioral Changes - Core ========================= +Type objects no longer accept ignored keyword arguments +------------------------------------------------------- + +Up through the 0.8 series, most type objects accepted arbitrary keyword +arguments which were silently ignored:: + + from sqlalchemy import Date, Integer + + # storage_format argument here has no effect on any backend; + # it needs to be on the SQLite-specific type + d = Date(storage_format="%(day)02d.%(month)02d.%(year)04d") + + # display_width argument here has no effect on any backend; + # it needs to be on the MySQL-specific type + i = Integer(display_width=5) + +This was a very old bug for which a deprecation warning was added to the +0.8 series, but because nobody ever runs Python with the "-W" flag, it +was mostly never seen:: + + + $ python -W always::DeprecationWarning ~/dev/sqlalchemy/test.py + /Users/classic/dev/sqlalchemy/test.py:5: SADeprecationWarning: Passing arguments to + type object constructor <class 'sqlalchemy.types.Date'> is deprecated + d = Date(storage_format="%(day)02d.%(month)02d.%(year)04d") + /Users/classic/dev/sqlalchemy/test.py:9: SADeprecationWarning: Passing arguments to + type object constructor <class 'sqlalchemy.types.Integer'> is deprecated + i = Integer(display_width=5) + +As of the 0.9 series the "catch all" constructor is removed from +:class:`.TypeEngine`, and these meaningless arguments are no longer accepted. + +The correct way to make use of dialect-specific arguments such as +``storage_format`` and ``display_width`` is to use the appropriate +dialect-specific types:: + + from sqlalchemy.dialects.sqlite import DATE + from sqlalchemy.dialects.mysql import INTEGER + + d = DATE(storage_format="%(day)02d.%(month)02d.%(year)04d") + + i = INTEGER(display_width=5) + +What about the case where we want the dialect-agnostic type also? We +use the :meth:`.TypeEngine.with_variant` method:: + + from sqlalchemy import Date, Integer + from sqlalchemy.dialects.sqlite import DATE + from sqlalchemy.dialects.mysql import INTEGER + + d = Date().with_variant( + DATE(storage_format="%(day)02d.%(month)02d.%(year)04d"), + "sqlite" + ) + + i = Integer().with_variant( + INTEGER(display_width=5), + "mysql" + ) + +:meth:`.TypeEngine.with_variant` isn't new, it was added in SQLAlchemy +0.7.2. So code that is running on the 0.8 series can be corrected to use +this approach and tested before upgrading to 0.9. + ``None`` can no longer be used as a "partial AND" constructor -------------------------------------------------------------- |