2.0.0b3

Released: November 4, 2022

orm declarative

• [orm] [declarative] [bug] Added support in ORM declarative annotations for class names specified for _orm.relationship(), as well as the name of the _orm.Mapped symbol itself, to be different names than their direct class name, to support scenarios such as where _orm.Mapped is imported as from sqlalchemy.orm import Mapped as M, or where related class names are imported with an alternate name in a similar fashion. Additionally, a target class name given as the lead argument for _orm.relationship() will always supersede the name given in the left hand annotation, so that otherwise un-importable names that also don't match the class name can still be used in annotations.

  References: #8759

• [orm] [declarative] [bug] Improved support for legacy 1.4 mappings that use annotations which don't include Mapped[], by ensuring the __allow_unmapped__ attribute can be used to allow such legacy annotations to pass through Annotated Declarative without raising an error and without being interpreted in an ORM runtime context. Additionally improved the error message generated when this condition is detected, and added more documentation for how this situation should be handled. Unfortunately the 1.4 WARN_SQLALCHEMY_20 migration warning cannot detect this particular configurational issue at runtime with its current architecture.

  References: #8692

• [orm] [declarative] [bug] Changed a fundamental configuration behavior of Mapper, where _schema.Column objects that are explicitly present in the _orm.Mapper.properties dictionary, either directly or enclosed within a mapper property object, will now be mapped within the order of how they appear within the mapped Table (or other selectable) itself (assuming they are in fact part of that table's list of columns), thereby maintaining the same order of columns in the mapped selectable as is instrumented on the mapped class, as well as what renders in an ORM SELECT statement for that mapper. Previously (where "previously" means since version 0.0.1), Column objects in the _orm.Mapper.properties dictionary would always be mapped first, ahead of when the other columns in the mapped Table would be mapped, causing a discrepancy in the order in which the mapper would assign attributes to the mapped class as well as the order in which they would render in statements.

  The change most prominently takes place in the way that Declarative assigns declared columns to the Mapper, specifically how Column (or _orm.mapped_column()) objects are handled when they have a DDL name that is explicitly different from the mapped attribute name, as well as when constructs such as _orm.deferred() etc. are used. The new behavior will see the column ordering within the mapped Table being the same order in which the attributes are mapped onto the class, assigned within the Mapper itself, and rendered in ORM statements such as SELECT statements, independent of how the _schema.Column was configured against the Mapper.

  References: #8705

• [orm] [declarative] [bug] Fixed issue in new dataclass mapping feature where a column declared on the decalrative base / abstract base / mixin would leak into the constructor for an inheriting subclass under some circumstances.

  References: #8718

• [bug] [orm declarative] Fixed issues within the declarative typing resolver (i.e. which resolves ForwardRef objects) where types that were declared for columns in one particular source file would raise NameError when the ultimate mapped class were in another source file. The types are now resolved in terms of the module for each class in which the types are used.

  References: #8742

engine

• [engine] [feature] To better support the use case of iterating Result and AsyncResult objects where user-defined exceptions may interrupt the iteration, both objects as well as variants such as ScalarResult, MappingResult, AsyncScalarResult, AsyncMappingResult now support context manager usage, where the result will be closed at the end of the context manager block.

  In addition, ensured that all the above mentioned Result objects include a Result.close() method as well as Result.closed accessors, including ScalarResult and MappingResult which previously did not have a .close() method.

  References: #8710

• [engine] [usecase] Added new parameter PoolEvents.reset.reset_state parameter to the PoolEvents.reset() event, with deprecation logic in place that will continue to accept event hooks using the previous set of arguments. This indicates various state information about how the reset is taking place and is used to allow custom reset schemes to take place with full context given.

  Within this change a fix that's also backported to 1.4 is included which re-enables the PoolEvents.reset() event to continue to take place under all circumstances, including when Connection has already "reset" the connection.

  The two changes together allow custom reset schemes to be implemented using the PoolEvents.reset() event, instead of the PoolEvents.checkin() event (which continues to function as it always has).

  References: #8717

typing

• [typing] [bug] Corrected various typing issues within the engine and async engine packages.

postgresql

• [postgresql] [feature] Added new methods _postgresql.Range.contains() and _postgresql.Range.contained_by() to the new Range data object, which mirror the behavior of the PostgreSQL @> and <@ operators, as well as the _postgresql.AbstractRange.comparator_factory.contains() and _postgresql.AbstractRange.comparator_factory.contained_by() SQL operator methods. Pull request courtesy Lele Gaifax.

  References: #8706

• [postgresql] [usecase] Refined the new approach to range objects described at change_7156 to accommodate driver-specific range and multirange objects, to better accommodate both legacy code as well as when passing results from raw SQL result sets back into new range or multirange expressions.

  References: #8690