A dictionary-based collection type with column-based keying. .. versionchanged:: 2.0 Renamed :data:`.column_mapped_collection` to :class:`.column_keyed_dict`. Returns a :class:`.KeyFuncDict` factory which will produce new dictionary keys based on the value of a particular :class
(
mapping_spec: Union[Type[_KT], Callable[[_KT], _VT]],
*,
ignore_unpopulated_attribute: bool = False,
)
| 142 | |
| 143 | |
| 144 | def column_keyed_dict( |
| 145 | mapping_spec: Union[Type[_KT], Callable[[_KT], _VT]], |
| 146 | *, |
| 147 | ignore_unpopulated_attribute: bool = False, |
| 148 | ) -> Type[KeyFuncDict[_KT, _KT]]: |
| 149 | """A dictionary-based collection type with column-based keying. |
| 150 | |
| 151 | .. versionchanged:: 2.0 Renamed :data:`.column_mapped_collection` to |
| 152 | :class:`.column_keyed_dict`. |
| 153 | |
| 154 | Returns a :class:`.KeyFuncDict` factory which will produce new |
| 155 | dictionary keys based on the value of a particular :class:`.Column`-mapped |
| 156 | attribute on ORM mapped instances to be added to the dictionary. |
| 157 | |
| 158 | .. note:: the value of the target attribute must be assigned with its |
| 159 | value at the time that the object is being added to the |
| 160 | dictionary collection. Additionally, changes to the key attribute |
| 161 | are **not tracked**, which means the key in the dictionary is not |
| 162 | automatically synchronized with the key value on the target object |
| 163 | itself. See :ref:`key_collections_mutations` for further details. |
| 164 | |
| 165 | .. seealso:: |
| 166 | |
| 167 | :ref:`orm_dictionary_collection` - background on use |
| 168 | |
| 169 | :param mapping_spec: a :class:`_schema.Column` object that is expected |
| 170 | to be mapped by the target mapper to a particular attribute on the |
| 171 | mapped class, the value of which on a particular instance is to be used |
| 172 | as the key for a new dictionary entry for that instance. |
| 173 | :param ignore_unpopulated_attribute: if True, and the mapped attribute |
| 174 | indicated by the given :class:`_schema.Column` target attribute |
| 175 | on an object is not populated at all, the operation will be silently |
| 176 | skipped. By default, an error is raised. |
| 177 | |
| 178 | .. versionadded:: 2.0 an error is raised by default if the attribute |
| 179 | being used for the dictionary key is determined that it was never |
| 180 | populated with any value. The |
| 181 | :paramref:`_orm.column_keyed_dict.ignore_unpopulated_attribute` |
| 182 | parameter may be set which will instead indicate that this condition |
| 183 | should be ignored, and the append operation silently skipped. |
| 184 | This is in contrast to the behavior of the 1.x series which would |
| 185 | erroneously populate the value in the dictionary with an arbitrary key |
| 186 | value of ``None``. |
| 187 | |
| 188 | |
| 189 | """ |
| 190 | cols = [ |
| 191 | coercions.expect(roles.ColumnArgumentRole, q, argname="mapping_spec") |
| 192 | for q in util.to_list(mapping_spec) |
| 193 | ] |
| 194 | keyfunc = _PlainColumnGetter(cols) |
| 195 | return _mapped_collection_cls( |
| 196 | keyfunc, |
| 197 | ignore_unpopulated_attribute=ignore_unpopulated_attribute, |
| 198 | ) |
| 199 | |
| 200 | |
| 201 | class _AttrGetter: |