[3] | 1 | # sqlalchemy/orm/__init__.py |
---|
| 2 | # Copyright (C) 2005, 2006, 2007, 2008, 2009 Michael Bayer mike_mp@zzzcomputing.com |
---|
| 3 | # |
---|
| 4 | # This module is part of SQLAlchemy and is released under |
---|
| 5 | # the MIT License: http://www.opensource.org/licenses/mit-license.php |
---|
| 6 | |
---|
| 7 | """ |
---|
| 8 | Functional constructs for ORM configuration. |
---|
| 9 | |
---|
| 10 | See the SQLAlchemy object relational tutorial and mapper configuration |
---|
| 11 | documentation for an overview of how this module is used. |
---|
| 12 | |
---|
| 13 | """ |
---|
| 14 | |
---|
| 15 | from sqlalchemy.orm import exc |
---|
| 16 | from sqlalchemy.orm.mapper import ( |
---|
| 17 | Mapper, |
---|
| 18 | _mapper_registry, |
---|
| 19 | class_mapper, |
---|
| 20 | ) |
---|
| 21 | from sqlalchemy.orm.interfaces import ( |
---|
| 22 | EXT_CONTINUE, |
---|
| 23 | EXT_STOP, |
---|
| 24 | ExtensionOption, |
---|
| 25 | InstrumentationManager, |
---|
| 26 | MapperExtension, |
---|
| 27 | PropComparator, |
---|
| 28 | SessionExtension, |
---|
| 29 | AttributeExtension, |
---|
| 30 | ) |
---|
| 31 | from sqlalchemy.orm.util import ( |
---|
| 32 | AliasedClass as aliased, |
---|
| 33 | Validator, |
---|
| 34 | join, |
---|
| 35 | object_mapper, |
---|
| 36 | outerjoin, |
---|
| 37 | polymorphic_union, |
---|
| 38 | with_parent, |
---|
| 39 | ) |
---|
| 40 | from sqlalchemy.orm.properties import ( |
---|
| 41 | BackRef, |
---|
| 42 | ColumnProperty, |
---|
| 43 | ComparableProperty, |
---|
| 44 | CompositeProperty, |
---|
| 45 | RelationProperty, |
---|
| 46 | PropertyLoader, |
---|
| 47 | SynonymProperty, |
---|
| 48 | ) |
---|
| 49 | from sqlalchemy.orm import mapper as mapperlib |
---|
| 50 | from sqlalchemy.orm.mapper import reconstructor, validates |
---|
| 51 | from sqlalchemy.orm import strategies |
---|
| 52 | from sqlalchemy.orm.query import AliasOption, Query |
---|
| 53 | from sqlalchemy.sql import util as sql_util |
---|
| 54 | from sqlalchemy.orm.session import Session as _Session |
---|
| 55 | from sqlalchemy.orm.session import object_session, sessionmaker |
---|
| 56 | from sqlalchemy.orm.scoping import ScopedSession |
---|
| 57 | from sqlalchemy import util as sa_util |
---|
| 58 | |
---|
| 59 | |
---|
| 60 | __all__ = ( |
---|
| 61 | 'EXT_CONTINUE', |
---|
| 62 | 'EXT_STOP', |
---|
| 63 | 'InstrumentationManager', |
---|
| 64 | 'MapperExtension', |
---|
| 65 | 'AttributeExtension', |
---|
| 66 | 'Validator', |
---|
| 67 | 'PropComparator', |
---|
| 68 | 'Query', |
---|
| 69 | 'aliased', |
---|
| 70 | 'backref', |
---|
| 71 | 'class_mapper', |
---|
| 72 | 'clear_mappers', |
---|
| 73 | 'column_property', |
---|
| 74 | 'comparable_property', |
---|
| 75 | 'compile_mappers', |
---|
| 76 | 'composite', |
---|
| 77 | 'contains_alias', |
---|
| 78 | 'contains_eager', |
---|
| 79 | 'create_session', |
---|
| 80 | 'defer', |
---|
| 81 | 'deferred', |
---|
| 82 | 'dynamic_loader', |
---|
| 83 | 'eagerload', |
---|
| 84 | 'eagerload_all', |
---|
| 85 | 'extension', |
---|
| 86 | 'join', |
---|
| 87 | 'lazyload', |
---|
| 88 | 'mapper', |
---|
| 89 | 'noload', |
---|
| 90 | 'object_mapper', |
---|
| 91 | 'object_session', |
---|
| 92 | 'outerjoin', |
---|
| 93 | 'polymorphic_union', |
---|
| 94 | 'reconstructor', |
---|
| 95 | 'relation', |
---|
| 96 | 'scoped_session', |
---|
| 97 | 'sessionmaker', |
---|
| 98 | 'synonym', |
---|
| 99 | 'undefer', |
---|
| 100 | 'undefer_group', |
---|
| 101 | 'validates' |
---|
| 102 | ) |
---|
| 103 | |
---|
| 104 | |
---|
| 105 | def scoped_session(session_factory, scopefunc=None): |
---|
| 106 | """Provides thread-local management of Sessions. |
---|
| 107 | |
---|
| 108 | This is a front-end function to |
---|
| 109 | :class:`~sqlalchemy.orm.scoping.ScopedSession`. |
---|
| 110 | |
---|
| 111 | :param session_factory: a callable function that produces |
---|
| 112 | :class:`Session` instances, such as :func:`sessionmaker` or |
---|
| 113 | :func:`create_session`. |
---|
| 114 | |
---|
| 115 | :param scopefunc: optional, TODO |
---|
| 116 | |
---|
| 117 | :returns: an :class:`~sqlalchemy.orm.scoping.ScopedSession` instance |
---|
| 118 | |
---|
| 119 | Usage:: |
---|
| 120 | |
---|
| 121 | Session = scoped_session(sessionmaker(autoflush=True)) |
---|
| 122 | |
---|
| 123 | To instantiate a Session object which is part of the scoped context, |
---|
| 124 | instantiate normally:: |
---|
| 125 | |
---|
| 126 | session = Session() |
---|
| 127 | |
---|
| 128 | Most session methods are available as classmethods from the scoped |
---|
| 129 | session:: |
---|
| 130 | |
---|
| 131 | Session.commit() |
---|
| 132 | Session.close() |
---|
| 133 | |
---|
| 134 | To map classes so that new instances are saved in the current Session |
---|
| 135 | automatically, as well as to provide session-aware class attributes such |
---|
| 136 | as "query", use the `mapper` classmethod from the scoped session:: |
---|
| 137 | |
---|
| 138 | mapper = Session.mapper |
---|
| 139 | mapper(Class, table, ...) |
---|
| 140 | |
---|
| 141 | """ |
---|
| 142 | return ScopedSession(session_factory, scopefunc=scopefunc) |
---|
| 143 | |
---|
| 144 | def create_session(bind=None, **kwargs): |
---|
| 145 | """Create a new :class:`~sqlalchemy.orm.session.Session`. |
---|
| 146 | |
---|
| 147 | :param bind: optional, a single Connectable to use for all |
---|
| 148 | database access in the created |
---|
| 149 | :class:`~sqlalchemy.orm.session.Session`. |
---|
| 150 | |
---|
| 151 | :param \*\*kwargs: optional, passed through to the |
---|
| 152 | :class:`Session` constructor. |
---|
| 153 | |
---|
| 154 | :returns: an :class:`~sqlalchemy.orm.session.Session` instance |
---|
| 155 | |
---|
| 156 | The defaults of create_session() are the opposite of that of |
---|
| 157 | :func:`sessionmaker`; ``autoflush`` and ``expire_on_commit`` are |
---|
| 158 | False, ``autocommit`` is True. In this sense the session acts |
---|
| 159 | more like the "classic" SQLAlchemy 0.3 session with these. |
---|
| 160 | |
---|
| 161 | Usage:: |
---|
| 162 | |
---|
| 163 | >>> from sqlalchemy.orm import create_session |
---|
| 164 | >>> session = create_session() |
---|
| 165 | |
---|
| 166 | It is recommended to use :func:`sessionmaker` instead of |
---|
| 167 | create_session(). |
---|
| 168 | |
---|
| 169 | """ |
---|
| 170 | if 'transactional' in kwargs: |
---|
| 171 | sa_util.warn_deprecated( |
---|
| 172 | "The 'transactional' argument to sessionmaker() is deprecated; " |
---|
| 173 | "use autocommit=True|False instead.") |
---|
| 174 | if 'autocommit' in kwargs: |
---|
| 175 | raise TypeError('Specify autocommit *or* transactional, not both.') |
---|
| 176 | kwargs['autocommit'] = not kwargs.pop('transactional') |
---|
| 177 | |
---|
| 178 | kwargs.setdefault('autoflush', False) |
---|
| 179 | kwargs.setdefault('autocommit', True) |
---|
| 180 | kwargs.setdefault('expire_on_commit', False) |
---|
| 181 | return _Session(bind=bind, **kwargs) |
---|
| 182 | |
---|
| 183 | def relation(argument, secondary=None, **kwargs): |
---|
| 184 | """Provide a relationship of a primary Mapper to a secondary Mapper. |
---|
| 185 | |
---|
| 186 | This corresponds to a parent-child or associative table relationship. The |
---|
| 187 | constructed class is an instance of :class:`RelationProperty`. |
---|
| 188 | |
---|
| 189 | A typical :func:`relation`:: |
---|
| 190 | |
---|
| 191 | mapper(Parent, properties={ |
---|
| 192 | 'children': relation(Children) |
---|
| 193 | }) |
---|
| 194 | |
---|
| 195 | :param argument: |
---|
| 196 | a class or :class:`Mapper` instance, representing the target of |
---|
| 197 | the relation. |
---|
| 198 | |
---|
| 199 | :param secondary: |
---|
| 200 | for a many-to-many relationship, specifies the intermediary |
---|
| 201 | table. The *secondary* keyword argument should generally only |
---|
| 202 | be used for a table that is not otherwise expressed in any class |
---|
| 203 | mapping. In particular, using the Association Object Pattern is |
---|
| 204 | generally mutually exclusive with the use of the *secondary* |
---|
| 205 | keyword argument. |
---|
| 206 | |
---|
| 207 | :param backref: |
---|
| 208 | indicates the string name of a property to be placed on the related |
---|
| 209 | mapper's class that will handle this relationship in the other |
---|
| 210 | direction. The other property will be created automatically |
---|
| 211 | when the mappers are configured. Can also be passed as a |
---|
| 212 | :func:`backref` object to control the configuration of the |
---|
| 213 | new relation. |
---|
| 214 | |
---|
| 215 | :param back_populates: |
---|
| 216 | Takes a string name and has the same meaning as ``backref``, |
---|
| 217 | except the complementing property is **not** created automatically, |
---|
| 218 | and instead must be configured explicitly on the other mapper. The |
---|
| 219 | complementing property should also indicate ``back_populates`` |
---|
| 220 | to this relation to ensure proper functioning. |
---|
| 221 | |
---|
| 222 | :param cascade: |
---|
| 223 | a comma-separated list of cascade rules which determines how |
---|
| 224 | Session operations should be "cascaded" from parent to child. |
---|
| 225 | This defaults to ``False``, which means the default cascade |
---|
| 226 | should be used. The default value is ``"save-update, merge"``. |
---|
| 227 | |
---|
| 228 | Available cascades are: |
---|
| 229 | |
---|
| 230 | ``save-update`` - cascade the "add()" operation (formerly |
---|
| 231 | known as save() and update()) |
---|
| 232 | |
---|
| 233 | ``merge`` - cascade the "merge()" operation |
---|
| 234 | |
---|
| 235 | ``expunge`` - cascade the "expunge()" operation |
---|
| 236 | |
---|
| 237 | ``delete`` - cascade the "delete()" operation |
---|
| 238 | |
---|
| 239 | ``delete-orphan`` - if an item of the child's type with no |
---|
| 240 | parent is detected, mark it for deletion. Note that this |
---|
| 241 | option prevents a pending item of the child's class from being |
---|
| 242 | persisted without a parent present. |
---|
| 243 | |
---|
| 244 | ``refresh-expire`` - cascade the expire() and refresh() |
---|
| 245 | operations |
---|
| 246 | |
---|
| 247 | ``all`` - shorthand for "save-update,merge, refresh-expire, |
---|
| 248 | expunge, delete" |
---|
| 249 | |
---|
| 250 | :param collection_class: |
---|
| 251 | a class or callable that returns a new list-holding object. will |
---|
| 252 | be used in place of a plain list for storing elements. |
---|
| 253 | |
---|
| 254 | :param comparator_factory: |
---|
| 255 | a class which extends :class:`RelationProperty.Comparator` which |
---|
| 256 | provides custom SQL clause generation for comparison operations. |
---|
| 257 | |
---|
| 258 | :param extension: |
---|
| 259 | an :class:`AttributeExtension` instance, or list of extensions, |
---|
| 260 | which will be prepended to the list of attribute listeners for |
---|
| 261 | the resulting descriptor placed on the class. These listeners |
---|
| 262 | will receive append and set events before the operation |
---|
| 263 | proceeds, and may be used to halt (via exception throw) or |
---|
| 264 | change the value used in the operation. |
---|
| 265 | |
---|
| 266 | :param foreign_keys: |
---|
| 267 | |
---|
| 268 | a list of columns which are to be used as "foreign key" columns. |
---|
| 269 | this parameter should be used in conjunction with explicit |
---|
| 270 | ``primaryjoin`` and ``secondaryjoin`` (if needed) arguments, and |
---|
| 271 | the columns within the ``foreign_keys`` list should be present |
---|
| 272 | within those join conditions. Normally, ``relation()`` will |
---|
| 273 | inspect the columns within the join conditions to determine |
---|
| 274 | which columns are the "foreign key" columns, based on |
---|
| 275 | information in the ``Table`` metadata. Use this argument when no |
---|
| 276 | ForeignKey's are present in the join condition, or to override |
---|
| 277 | the table-defined foreign keys. |
---|
| 278 | |
---|
| 279 | :param join_depth: |
---|
| 280 | when non-``None``, an integer value indicating how many levels |
---|
| 281 | deep eagerload joins should be constructed on a self-referring |
---|
| 282 | or cyclical relationship. The number counts how many times the |
---|
| 283 | same Mapper shall be present in the loading condition along a |
---|
| 284 | particular join branch. When left at its default of ``None``, |
---|
| 285 | eager loads will automatically stop chaining joins when they |
---|
| 286 | encounter a mapper which is already higher up in the chain. |
---|
| 287 | |
---|
| 288 | :param lazy=(True|False|None|'dynamic'): |
---|
| 289 | specifies how the related items should be loaded. Values include: |
---|
| 290 | |
---|
| 291 | True - items should be loaded lazily when the property is first |
---|
| 292 | accessed. |
---|
| 293 | |
---|
| 294 | False - items should be loaded "eagerly" in the same query as |
---|
| 295 | that of the parent, using a JOIN or LEFT OUTER JOIN. |
---|
| 296 | |
---|
| 297 | None - no loading should occur at any time. This is to support |
---|
| 298 | "write-only" attributes, or attributes which are |
---|
| 299 | populated in some manner specific to the application. |
---|
| 300 | |
---|
| 301 | 'dynamic' - a ``DynaLoader`` will be attached, which returns a |
---|
| 302 | ``Query`` object for all read operations. The |
---|
| 303 | dynamic- collection supports only ``append()`` and |
---|
| 304 | ``remove()`` for write operations; changes to the |
---|
| 305 | dynamic property will not be visible until the data |
---|
| 306 | is flushed to the database. |
---|
| 307 | |
---|
| 308 | :param order_by: |
---|
| 309 | indicates the ordering that should be applied when loading these |
---|
| 310 | items. |
---|
| 311 | |
---|
| 312 | :param passive_deletes=False: |
---|
| 313 | Indicates loading behavior during delete operations. |
---|
| 314 | |
---|
| 315 | A value of True indicates that unloaded child items should not |
---|
| 316 | be loaded during a delete operation on the parent. Normally, |
---|
| 317 | when a parent item is deleted, all child items are loaded so |
---|
| 318 | that they can either be marked as deleted, or have their |
---|
| 319 | foreign key to the parent set to NULL. Marking this flag as |
---|
| 320 | True usually implies an ON DELETE <CASCADE|SET NULL> rule is in |
---|
| 321 | place which will handle updating/deleting child rows on the |
---|
| 322 | database side. |
---|
| 323 | |
---|
| 324 | Additionally, setting the flag to the string value 'all' will |
---|
| 325 | disable the "nulling out" of the child foreign keys, when there |
---|
| 326 | is no delete or delete-orphan cascade enabled. This is |
---|
| 327 | typically used when a triggering or error raise scenario is in |
---|
| 328 | place on the database side. Note that the foreign key |
---|
| 329 | attributes on in-session child objects will not be changed |
---|
| 330 | after a flush occurs so this is a very special use-case |
---|
| 331 | setting. |
---|
| 332 | |
---|
| 333 | :param passive_updates=True: |
---|
| 334 | Indicates loading and INSERT/UPDATE/DELETE behavior when the |
---|
| 335 | source of a foreign key value changes (i.e. an "on update" |
---|
| 336 | cascade), which are typically the primary key columns of the |
---|
| 337 | source row. |
---|
| 338 | |
---|
| 339 | When True, it is assumed that ON UPDATE CASCADE is configured on |
---|
| 340 | the foreign key in the database, and that the database will |
---|
| 341 | handle propagation of an UPDATE from a source column to |
---|
| 342 | dependent rows. Note that with databases which enforce |
---|
| 343 | referential integrity (i.e. PostgreSQL, MySQL with InnoDB tables), |
---|
| 344 | ON UPDATE CASCADE is required for this operation. The |
---|
| 345 | relation() will update the value of the attribute on related |
---|
| 346 | items which are locally present in the session during a flush. |
---|
| 347 | |
---|
| 348 | When False, it is assumed that the database does not enforce |
---|
| 349 | referential integrity and will not be issuing its own CASCADE |
---|
| 350 | operation for an update. The relation() will issue the |
---|
| 351 | appropriate UPDATE statements to the database in response to the |
---|
| 352 | change of a referenced key, and items locally present in the |
---|
| 353 | session during a flush will also be refreshed. |
---|
| 354 | |
---|
| 355 | This flag should probably be set to False if primary key changes |
---|
| 356 | are expected and the database in use doesn't support CASCADE |
---|
| 357 | (i.e. SQLite, MySQL MyISAM tables). |
---|
| 358 | |
---|
| 359 | :param post_update: |
---|
| 360 | this indicates that the relationship should be handled by a |
---|
| 361 | second UPDATE statement after an INSERT or before a |
---|
| 362 | DELETE. Currently, it also will issue an UPDATE after the |
---|
| 363 | instance was UPDATEd as well, although this technically should |
---|
| 364 | be improved. This flag is used to handle saving bi-directional |
---|
| 365 | dependencies between two individual rows (i.e. each row |
---|
| 366 | references the other), where it would otherwise be impossible to |
---|
| 367 | INSERT or DELETE both rows fully since one row exists before the |
---|
| 368 | other. Use this flag when a particular mapping arrangement will |
---|
| 369 | incur two rows that are dependent on each other, such as a table |
---|
| 370 | that has a one-to-many relationship to a set of child rows, and |
---|
| 371 | also has a column that references a single child row within that |
---|
| 372 | list (i.e. both tables contain a foreign key to each other). If |
---|
| 373 | a ``flush()`` operation returns an error that a "cyclical |
---|
| 374 | dependency" was detected, this is a cue that you might want to |
---|
| 375 | use ``post_update`` to "break" the cycle. |
---|
| 376 | |
---|
| 377 | :param primaryjoin: |
---|
| 378 | a ClauseElement that will be used as the primary join of this |
---|
| 379 | child object against the parent object, or in a many-to-many |
---|
| 380 | relationship the join of the primary object to the association |
---|
| 381 | table. By default, this value is computed based on the foreign |
---|
| 382 | key relationships of the parent and child tables (or association |
---|
| 383 | table). |
---|
| 384 | |
---|
| 385 | :param remote_side: |
---|
| 386 | used for self-referential relationships, indicates the column or |
---|
| 387 | list of columns that form the "remote side" of the relationship. |
---|
| 388 | |
---|
| 389 | :param secondaryjoin: |
---|
| 390 | a ClauseElement that will be used as the join of an association |
---|
| 391 | table to the child object. By default, this value is computed |
---|
| 392 | based on the foreign key relationships of the association and |
---|
| 393 | child tables. |
---|
| 394 | |
---|
| 395 | :param single_parent=(True|False): |
---|
| 396 | when True, installs a validator which will prevent objects |
---|
| 397 | from being associated with more than one parent at a time. |
---|
| 398 | This is used for many-to-one or many-to-many relationships that |
---|
| 399 | should be treated either as one-to-one or one-to-many. Its |
---|
| 400 | usage is optional unless delete-orphan cascade is also |
---|
| 401 | set on this relation(), in which case its required (new in 0.5.2). |
---|
| 402 | |
---|
| 403 | :param uselist=(True|False): |
---|
| 404 | a boolean that indicates if this property should be loaded as a |
---|
| 405 | list or a scalar. In most cases, this value is determined |
---|
| 406 | automatically by ``relation()``, based on the type and direction |
---|
| 407 | of the relationship - one to many forms a list, many to one |
---|
| 408 | forms a scalar, many to many is a list. If a scalar is desired |
---|
| 409 | where normally a list would be present, such as a bi-directional |
---|
| 410 | one-to-one relationship, set uselist to False. |
---|
| 411 | |
---|
| 412 | :param viewonly=False: |
---|
| 413 | when set to True, the relation is used only for loading objects |
---|
| 414 | within the relationship, and has no effect on the unit-of-work |
---|
| 415 | flush process. Relationships with viewonly can specify any kind of |
---|
| 416 | join conditions to provide additional views of related objects |
---|
| 417 | onto a parent object. Note that the functionality of a viewonly |
---|
| 418 | relationship has its limits - complicated join conditions may |
---|
| 419 | not compile into eager or lazy loaders properly. If this is the |
---|
| 420 | case, use an alternative method. |
---|
| 421 | |
---|
| 422 | """ |
---|
| 423 | return RelationProperty(argument, secondary=secondary, **kwargs) |
---|
| 424 | |
---|
| 425 | def dynamic_loader(argument, secondary=None, primaryjoin=None, |
---|
| 426 | secondaryjoin=None, foreign_keys=None, backref=None, |
---|
| 427 | post_update=False, cascade=False, remote_side=None, |
---|
| 428 | enable_typechecks=True, passive_deletes=False, |
---|
| 429 | order_by=None, comparator_factory=None, query_class=None): |
---|
| 430 | """Construct a dynamically-loading mapper property. |
---|
| 431 | |
---|
| 432 | This property is similar to :func:`relation`, except read |
---|
| 433 | operations return an active :class:`Query` object which reads from |
---|
| 434 | the database when accessed. Items may be appended to the |
---|
| 435 | attribute via ``append()``, or removed via ``remove()``; changes |
---|
| 436 | will be persisted to the database during a :meth:`Sesion.flush`. |
---|
| 437 | However, no other Python list or collection mutation operations |
---|
| 438 | are available. |
---|
| 439 | |
---|
| 440 | A subset of arguments available to :func:`relation` are available |
---|
| 441 | here. |
---|
| 442 | |
---|
| 443 | :param argument: |
---|
| 444 | a class or :class:`Mapper` instance, representing the target of |
---|
| 445 | the relation. |
---|
| 446 | |
---|
| 447 | :param secondary: |
---|
| 448 | for a many-to-many relationship, specifies the intermediary |
---|
| 449 | table. The *secondary* keyword argument should generally only |
---|
| 450 | be used for a table that is not otherwise expressed in any class |
---|
| 451 | mapping. In particular, using the Association Object Pattern is |
---|
| 452 | generally mutually exclusive with the use of the *secondary* |
---|
| 453 | keyword argument. |
---|
| 454 | |
---|
| 455 | :param query_class: |
---|
| 456 | Optional, a custom Query subclass to be used as the basis for |
---|
| 457 | dynamic collection. |
---|
| 458 | |
---|
| 459 | """ |
---|
| 460 | from sqlalchemy.orm.dynamic import DynaLoader |
---|
| 461 | |
---|
| 462 | return RelationProperty( |
---|
| 463 | argument, secondary=secondary, primaryjoin=primaryjoin, |
---|
| 464 | secondaryjoin=secondaryjoin, foreign_keys=foreign_keys, backref=backref, |
---|
| 465 | post_update=post_update, cascade=cascade, remote_side=remote_side, |
---|
| 466 | enable_typechecks=enable_typechecks, passive_deletes=passive_deletes, |
---|
| 467 | order_by=order_by, comparator_factory=comparator_factory, |
---|
| 468 | strategy_class=DynaLoader, query_class=query_class) |
---|
| 469 | |
---|
| 470 | def column_property(*args, **kwargs): |
---|
| 471 | """Provide a column-level property for use with a Mapper. |
---|
| 472 | |
---|
| 473 | Column-based properties can normally be applied to the mapper's |
---|
| 474 | ``properties`` dictionary using the ``schema.Column`` element directly. |
---|
| 475 | Use this function when the given column is not directly present within the |
---|
| 476 | mapper's selectable; examples include SQL expressions, functions, and |
---|
| 477 | scalar SELECT queries. |
---|
| 478 | |
---|
| 479 | Columns that aren't present in the mapper's selectable won't be persisted |
---|
| 480 | by the mapper and are effectively "read-only" attributes. |
---|
| 481 | |
---|
| 482 | \*cols |
---|
| 483 | list of Column objects to be mapped. |
---|
| 484 | |
---|
| 485 | comparator_factory |
---|
| 486 | a class which extends ``sqlalchemy.orm.properties.ColumnProperty.Comparator`` |
---|
| 487 | which provides custom SQL clause generation for comparison operations. |
---|
| 488 | |
---|
| 489 | group |
---|
| 490 | a group name for this property when marked as deferred. |
---|
| 491 | |
---|
| 492 | deferred |
---|
| 493 | when True, the column property is "deferred", meaning that |
---|
| 494 | it does not load immediately, and is instead loaded when the |
---|
| 495 | attribute is first accessed on an instance. See also |
---|
| 496 | :func:`~sqlalchemy.orm.deferred`. |
---|
| 497 | |
---|
| 498 | extension |
---|
| 499 | an :class:`~sqlalchemy.orm.interfaces.AttributeExtension` instance, |
---|
| 500 | or list of extensions, which will be prepended to the list of |
---|
| 501 | attribute listeners for the resulting descriptor placed on the class. |
---|
| 502 | These listeners will receive append and set events before the |
---|
| 503 | operation proceeds, and may be used to halt (via exception throw) |
---|
| 504 | or change the value used in the operation. |
---|
| 505 | |
---|
| 506 | """ |
---|
| 507 | |
---|
| 508 | return ColumnProperty(*args, **kwargs) |
---|
| 509 | |
---|
| 510 | def composite(class_, *cols, **kwargs): |
---|
| 511 | """Return a composite column-based property for use with a Mapper. |
---|
| 512 | |
---|
| 513 | This is very much like a column-based property except the given class is |
---|
| 514 | used to represent "composite" values composed of one or more columns. |
---|
| 515 | |
---|
| 516 | The class must implement a constructor with positional arguments matching |
---|
| 517 | the order of columns supplied here, as well as a __composite_values__() |
---|
| 518 | method which returns values in the same order. |
---|
| 519 | |
---|
| 520 | A simple example is representing separate two columns in a table as a |
---|
| 521 | single, first-class "Point" object:: |
---|
| 522 | |
---|
| 523 | class Point(object): |
---|
| 524 | def __init__(self, x, y): |
---|
| 525 | self.x = x |
---|
| 526 | self.y = y |
---|
| 527 | def __composite_values__(self): |
---|
| 528 | return self.x, self.y |
---|
| 529 | def __eq__(self, other): |
---|
| 530 | return other is not None and self.x == other.x and self.y == other.y |
---|
| 531 | |
---|
| 532 | # and then in the mapping: |
---|
| 533 | ... composite(Point, mytable.c.x, mytable.c.y) ... |
---|
| 534 | |
---|
| 535 | The composite object may have its attributes populated based on the names |
---|
| 536 | of the mapped columns. To override the way internal state is set, |
---|
| 537 | additionally implement ``__set_composite_values__``:: |
---|
| 538 | |
---|
| 539 | class Point(object): |
---|
| 540 | def __init__(self, x, y): |
---|
| 541 | self.some_x = x |
---|
| 542 | self.some_y = y |
---|
| 543 | def __composite_values__(self): |
---|
| 544 | return self.some_x, self.some_y |
---|
| 545 | def __set_composite_values__(self, x, y): |
---|
| 546 | self.some_x = x |
---|
| 547 | self.some_y = y |
---|
| 548 | def __eq__(self, other): |
---|
| 549 | return other is not None and self.some_x == other.x and self.some_y == other.y |
---|
| 550 | |
---|
| 551 | Arguments are: |
---|
| 552 | |
---|
| 553 | class\_ |
---|
| 554 | The "composite type" class. |
---|
| 555 | |
---|
| 556 | \*cols |
---|
| 557 | List of Column objects to be mapped. |
---|
| 558 | |
---|
| 559 | group |
---|
| 560 | A group name for this property when marked as deferred. |
---|
| 561 | |
---|
| 562 | deferred |
---|
| 563 | When True, the column property is "deferred", meaning that it does not |
---|
| 564 | load immediately, and is instead loaded when the attribute is first |
---|
| 565 | accessed on an instance. See also :func:`~sqlalchemy.orm.deferred`. |
---|
| 566 | |
---|
| 567 | comparator_factory |
---|
| 568 | a class which extends ``sqlalchemy.orm.properties.CompositeProperty.Comparator`` |
---|
| 569 | which provides custom SQL clause generation for comparison operations. |
---|
| 570 | |
---|
| 571 | extension |
---|
| 572 | an :class:`~sqlalchemy.orm.interfaces.AttributeExtension` instance, |
---|
| 573 | or list of extensions, which will be prepended to the list of |
---|
| 574 | attribute listeners for the resulting descriptor placed on the class. |
---|
| 575 | These listeners will receive append and set events before the |
---|
| 576 | operation proceeds, and may be used to halt (via exception throw) |
---|
| 577 | or change the value used in the operation. |
---|
| 578 | |
---|
| 579 | """ |
---|
| 580 | return CompositeProperty(class_, *cols, **kwargs) |
---|
| 581 | |
---|
| 582 | |
---|
| 583 | def backref(name, **kwargs): |
---|
| 584 | """Create a BackRef object with explicit arguments, which are the same |
---|
| 585 | arguments one can send to ``relation()``. |
---|
| 586 | |
---|
| 587 | Used with the `backref` keyword argument to ``relation()`` in |
---|
| 588 | place of a string argument. |
---|
| 589 | |
---|
| 590 | """ |
---|
| 591 | return BackRef(name, **kwargs) |
---|
| 592 | |
---|
| 593 | def deferred(*columns, **kwargs): |
---|
| 594 | """Return a ``DeferredColumnProperty``, which indicates this |
---|
| 595 | object attributes should only be loaded from its corresponding |
---|
| 596 | table column when first accessed. |
---|
| 597 | |
---|
| 598 | Used with the `properties` dictionary sent to ``mapper()``. |
---|
| 599 | |
---|
| 600 | """ |
---|
| 601 | return ColumnProperty(deferred=True, *columns, **kwargs) |
---|
| 602 | |
---|
| 603 | def mapper(class_, local_table=None, *args, **params): |
---|
| 604 | """Return a new :class:`~sqlalchemy.orm.Mapper` object. |
---|
| 605 | |
---|
| 606 | class\_ |
---|
| 607 | The class to be mapped. |
---|
| 608 | |
---|
| 609 | local_table |
---|
| 610 | The table to which the class is mapped, or None if this mapper |
---|
| 611 | inherits from another mapper using concrete table inheritance. |
---|
| 612 | |
---|
| 613 | always_refresh |
---|
| 614 | If True, all query operations for this mapped class will overwrite all |
---|
| 615 | data within object instances that already exist within the session, |
---|
| 616 | erasing any in-memory changes with whatever information was loaded |
---|
| 617 | from the database. Usage of this flag is highly discouraged; as an |
---|
| 618 | alternative, see the method `populate_existing()` on |
---|
| 619 | :class:`~sqlalchemy.orm.query.Query`. |
---|
| 620 | |
---|
| 621 | allow_null_pks |
---|
| 622 | Indicates that composite primary keys where one or more (but not all) |
---|
| 623 | columns contain NULL is a valid primary key. Primary keys which |
---|
| 624 | contain NULL values usually indicate that a result row does not |
---|
| 625 | contain an entity and should be skipped. |
---|
| 626 | |
---|
| 627 | batch |
---|
| 628 | Indicates that save operations of multiple entities can be batched |
---|
| 629 | together for efficiency. setting to False indicates that an instance |
---|
| 630 | will be fully saved before saving the next instance, which includes |
---|
| 631 | inserting/updating all table rows corresponding to the entity as well |
---|
| 632 | as calling all ``MapperExtension`` methods corresponding to the save |
---|
| 633 | operation. |
---|
| 634 | |
---|
| 635 | column_prefix |
---|
| 636 | A string which will be prepended to the `key` name of all Columns when |
---|
| 637 | creating column-based properties from the given Table. Does not |
---|
| 638 | affect explicitly specified column-based properties |
---|
| 639 | |
---|
| 640 | concrete |
---|
| 641 | If True, indicates this mapper should use concrete table inheritance |
---|
| 642 | with its parent mapper. |
---|
| 643 | |
---|
| 644 | extension |
---|
| 645 | A :class:`~sqlalchemy.orm.MapperExtension` instance or list of |
---|
| 646 | ``MapperExtension`` instances which will be applied to all |
---|
| 647 | operations by this ``Mapper``. |
---|
| 648 | |
---|
| 649 | inherits |
---|
| 650 | Another ``Mapper`` for which this ``Mapper`` will have an inheritance |
---|
| 651 | relationship with. |
---|
| 652 | |
---|
| 653 | inherit_condition |
---|
| 654 | For joined table inheritance, a SQL expression (constructed |
---|
| 655 | ``ClauseElement``) which will define how the two tables are joined; |
---|
| 656 | defaults to a natural join between the two tables. |
---|
| 657 | |
---|
| 658 | inherit_foreign_keys |
---|
| 659 | when inherit_condition is used and the condition contains no |
---|
| 660 | ForeignKey columns, specify the "foreign" columns of the join |
---|
| 661 | condition in this list. else leave as None. |
---|
| 662 | |
---|
| 663 | order_by |
---|
| 664 | A single ``Column`` or list of ``Columns`` for which |
---|
| 665 | selection operations should use as the default ordering for entities. |
---|
| 666 | Defaults to the OID/ROWID of the table if any, or the first primary |
---|
| 667 | key column of the table. |
---|
| 668 | |
---|
| 669 | non_primary |
---|
| 670 | Construct a ``Mapper`` that will define only the selection of |
---|
| 671 | instances, not their persistence. Any number of non_primary mappers |
---|
| 672 | may be created for a particular class. |
---|
| 673 | |
---|
| 674 | polymorphic_on |
---|
| 675 | Used with mappers in an inheritance relationship, a ``Column`` which |
---|
| 676 | will identify the class/mapper combination to be used with a |
---|
| 677 | particular row. Requires the ``polymorphic_identity`` value to be set |
---|
| 678 | for all mappers in the inheritance hierarchy. The column specified by |
---|
| 679 | ``polymorphic_on`` is usually a column that resides directly within |
---|
| 680 | the base mapper's mapped table; alternatively, it may be a column that |
---|
| 681 | is only present within the <selectable> portion of the |
---|
| 682 | ``with_polymorphic`` argument. |
---|
| 683 | |
---|
| 684 | _polymorphic_map |
---|
| 685 | Used internally to propagate the full map of polymorphic identifiers |
---|
| 686 | to surrogate mappers. |
---|
| 687 | |
---|
| 688 | polymorphic_identity |
---|
| 689 | A value which will be stored in the Column denoted by polymorphic_on, |
---|
| 690 | corresponding to the *class identity* of this mapper. |
---|
| 691 | |
---|
| 692 | polymorphic_fetch |
---|
| 693 | Deprecated. Unloaded columns load as deferred in all cases; loading |
---|
| 694 | can be controlled using the "with_polymorphic" option. |
---|
| 695 | |
---|
| 696 | properties |
---|
| 697 | A dictionary mapping the string names of object attributes to |
---|
| 698 | ``MapperProperty`` instances, which define the persistence behavior of |
---|
| 699 | that attribute. Note that the columns in the mapped table are |
---|
| 700 | automatically converted into ``ColumnProperty`` instances based on the |
---|
| 701 | `key` property of each ``Column`` (although they can be overridden |
---|
| 702 | using this dictionary). |
---|
| 703 | |
---|
| 704 | include_properties |
---|
| 705 | An inclusive list of properties to map. Columns present in the mapped |
---|
| 706 | table but not present in this list will not be automatically converted |
---|
| 707 | into properties. |
---|
| 708 | |
---|
| 709 | exclude_properties |
---|
| 710 | A list of properties not to map. Columns present in the mapped table |
---|
| 711 | and present in this list will not be automatically converted into |
---|
| 712 | properties. Note that neither this option nor include_properties will |
---|
| 713 | allow an end-run around Python inheritance. If mapped class ``B`` |
---|
| 714 | inherits from mapped class ``A``, no combination of includes or |
---|
| 715 | excludes will allow ``B`` to have fewer properties than its |
---|
| 716 | superclass, ``A``. |
---|
| 717 | |
---|
| 718 | primary_key |
---|
| 719 | A list of ``Column`` objects which define the *primary key* to be used |
---|
| 720 | against this mapper's selectable unit. This is normally simply the |
---|
| 721 | primary key of the `local_table`, but can be overridden here. |
---|
| 722 | |
---|
| 723 | with_polymorphic |
---|
| 724 | A tuple in the form ``(<classes>, <selectable>)`` indicating the |
---|
| 725 | default style of "polymorphic" loading, that is, which tables are |
---|
| 726 | queried at once. <classes> is any single or list of mappers and/or |
---|
| 727 | classes indicating the inherited classes that should be loaded at |
---|
| 728 | once. The special value ``'*'`` may be used to indicate all descending |
---|
| 729 | classes should be loaded immediately. The second tuple argument |
---|
| 730 | <selectable> indicates a selectable that will be used to query for |
---|
| 731 | multiple classes. Normally, it is left as None, in which case this |
---|
| 732 | mapper will form an outer join from the base mapper's table to that of |
---|
| 733 | all desired sub-mappers. When specified, it provides the selectable |
---|
| 734 | to be used for polymorphic loading. When with_polymorphic includes |
---|
| 735 | mappers which load from a "concrete" inheriting table, the |
---|
| 736 | <selectable> argument is required, since it usually requires more |
---|
| 737 | complex UNION queries. |
---|
| 738 | |
---|
| 739 | select_table |
---|
| 740 | Deprecated. Synonymous with |
---|
| 741 | ``with_polymorphic=('*', <selectable>)``. |
---|
| 742 | |
---|
| 743 | version_id_col |
---|
| 744 | A ``Column`` which must have an integer type that will be used to keep |
---|
| 745 | a running *version id* of mapped entities in the database. this is |
---|
| 746 | used during save operations to ensure that no other thread or process |
---|
| 747 | has updated the instance during the lifetime of the entity, else a |
---|
| 748 | ``ConcurrentModificationError`` exception is thrown. |
---|
| 749 | |
---|
| 750 | """ |
---|
| 751 | return Mapper(class_, local_table, *args, **params) |
---|
| 752 | |
---|
| 753 | def synonym(name, map_column=False, descriptor=None, comparator_factory=None, proxy=False): |
---|
| 754 | """Set up `name` as a synonym to another mapped property. |
---|
| 755 | |
---|
| 756 | Used with the ``properties`` dictionary sent to :func:`~sqlalchemy.orm.mapper`. |
---|
| 757 | |
---|
| 758 | Any existing attributes on the class which map the key name sent |
---|
| 759 | to the ``properties`` dictionary will be used by the synonym to provide |
---|
| 760 | instance-attribute behavior (that is, any Python property object, provided |
---|
| 761 | by the ``property`` builtin or providing a ``__get__()``, ``__set__()`` |
---|
| 762 | and ``__del__()`` method). If no name exists for the key, the |
---|
| 763 | ``synonym()`` creates a default getter/setter object automatically and |
---|
| 764 | applies it to the class. |
---|
| 765 | |
---|
| 766 | `name` refers to the name of the existing mapped property, which can be |
---|
| 767 | any other ``MapperProperty`` including column-based properties and |
---|
| 768 | relations. |
---|
| 769 | |
---|
| 770 | If `map_column` is ``True``, an additional ``ColumnProperty`` is created |
---|
| 771 | on the mapper automatically, using the synonym's name as the keyname of |
---|
| 772 | the property, and the keyname of this ``synonym()`` as the name of the |
---|
| 773 | column to map. For example, if a table has a column named ``status``:: |
---|
| 774 | |
---|
| 775 | class MyClass(object): |
---|
| 776 | def _get_status(self): |
---|
| 777 | return self._status |
---|
| 778 | def _set_status(self, value): |
---|
| 779 | self._status = value |
---|
| 780 | status = property(_get_status, _set_status) |
---|
| 781 | |
---|
| 782 | mapper(MyClass, sometable, properties={ |
---|
| 783 | "status":synonym("_status", map_column=True) |
---|
| 784 | }) |
---|
| 785 | |
---|
| 786 | The column named ``status`` will be mapped to the attribute named |
---|
| 787 | ``_status``, and the ``status`` attribute on ``MyClass`` will be used to |
---|
| 788 | proxy access to the column-based attribute. |
---|
| 789 | |
---|
| 790 | The `proxy` keyword argument is deprecated and currently does nothing; |
---|
| 791 | synonyms now always establish an attribute getter/setter function if one |
---|
| 792 | is not already available. |
---|
| 793 | |
---|
| 794 | """ |
---|
| 795 | return SynonymProperty(name, map_column=map_column, descriptor=descriptor, comparator_factory=comparator_factory) |
---|
| 796 | |
---|
| 797 | def comparable_property(comparator_factory, descriptor=None): |
---|
| 798 | """Provide query semantics for an unmanaged attribute. |
---|
| 799 | |
---|
| 800 | Allows a regular Python @property (descriptor) to be used in Queries and |
---|
| 801 | SQL constructs like a managed attribute. comparable_property wraps a |
---|
| 802 | descriptor with a proxy that directs operator overrides such as == |
---|
| 803 | (__eq__) to the supplied comparator but proxies everything else through to |
---|
| 804 | the original descriptor:: |
---|
| 805 | |
---|
| 806 | class MyClass(object): |
---|
| 807 | @property |
---|
| 808 | def myprop(self): |
---|
| 809 | return 'foo' |
---|
| 810 | |
---|
| 811 | class MyComparator(sqlalchemy.orm.interfaces.PropComparator): |
---|
| 812 | def __eq__(self, other): |
---|
| 813 | .... |
---|
| 814 | |
---|
| 815 | mapper(MyClass, mytable, properties=dict( |
---|
| 816 | 'myprop': comparable_property(MyComparator))) |
---|
| 817 | |
---|
| 818 | Used with the ``properties`` dictionary sent to :func:`~sqlalchemy.orm.mapper`. |
---|
| 819 | |
---|
| 820 | comparator_factory |
---|
| 821 | A PropComparator subclass or factory that defines operator behavior |
---|
| 822 | for this property. |
---|
| 823 | |
---|
| 824 | descriptor |
---|
| 825 | Optional when used in a ``properties={}`` declaration. The Python |
---|
| 826 | descriptor or property to layer comparison behavior on top of. |
---|
| 827 | |
---|
| 828 | The like-named descriptor will be automatically retreived from the |
---|
| 829 | mapped class if left blank in a ``properties`` declaration. |
---|
| 830 | |
---|
| 831 | """ |
---|
| 832 | return ComparableProperty(comparator_factory, descriptor) |
---|
| 833 | |
---|
| 834 | def compile_mappers(): |
---|
| 835 | """Compile all mappers that have been defined. |
---|
| 836 | |
---|
| 837 | This is equivalent to calling ``compile()`` on any individual mapper. |
---|
| 838 | |
---|
| 839 | """ |
---|
| 840 | for m in list(_mapper_registry): |
---|
| 841 | m.compile() |
---|
| 842 | |
---|
| 843 | def clear_mappers(): |
---|
| 844 | """Remove all mappers that have been created thus far. |
---|
| 845 | |
---|
| 846 | The mapped classes will return to their initial "unmapped" state and can |
---|
| 847 | be re-mapped with new mappers. |
---|
| 848 | |
---|
| 849 | """ |
---|
| 850 | mapperlib._COMPILE_MUTEX.acquire() |
---|
| 851 | try: |
---|
| 852 | for mapper in list(_mapper_registry): |
---|
| 853 | mapper.dispose() |
---|
| 854 | finally: |
---|
| 855 | mapperlib._COMPILE_MUTEX.release() |
---|
| 856 | |
---|
| 857 | def extension(ext): |
---|
| 858 | """Return a ``MapperOption`` that will insert the given |
---|
| 859 | ``MapperExtension`` to the beginning of the list of extensions |
---|
| 860 | that will be called in the context of the ``Query``. |
---|
| 861 | |
---|
| 862 | Used with ``query.options()``. |
---|
| 863 | |
---|
| 864 | """ |
---|
| 865 | return ExtensionOption(ext) |
---|
| 866 | |
---|
| 867 | @sa_util.accepts_a_list_as_starargs(list_deprecation='pending') |
---|
| 868 | def eagerload(*keys): |
---|
| 869 | """Return a ``MapperOption`` that will convert the property of the given |
---|
| 870 | name into an eager load. |
---|
| 871 | |
---|
| 872 | Used with ``query.options()``. |
---|
| 873 | |
---|
| 874 | """ |
---|
| 875 | return strategies.EagerLazyOption(keys, lazy=False) |
---|
| 876 | |
---|
| 877 | @sa_util.accepts_a_list_as_starargs(list_deprecation='pending') |
---|
| 878 | def eagerload_all(*keys): |
---|
| 879 | """Return a ``MapperOption`` that will convert all properties along the |
---|
| 880 | given dot-separated path into an eager load. |
---|
| 881 | |
---|
| 882 | For example, this:: |
---|
| 883 | |
---|
| 884 | query.options(eagerload_all('orders.items.keywords'))... |
---|
| 885 | |
---|
| 886 | will set all of 'orders', 'orders.items', and 'orders.items.keywords' to |
---|
| 887 | load in one eager load. |
---|
| 888 | |
---|
| 889 | Used with ``query.options()``. |
---|
| 890 | |
---|
| 891 | """ |
---|
| 892 | return strategies.EagerLazyOption(keys, lazy=False, chained=True) |
---|
| 893 | |
---|
| 894 | @sa_util.accepts_a_list_as_starargs(list_deprecation='pending') |
---|
| 895 | def lazyload(*keys): |
---|
| 896 | """Return a ``MapperOption`` that will convert the property of the given |
---|
| 897 | name into a lazy load. |
---|
| 898 | |
---|
| 899 | Used with ``query.options()``. |
---|
| 900 | |
---|
| 901 | """ |
---|
| 902 | return strategies.EagerLazyOption(keys, lazy=True) |
---|
| 903 | |
---|
| 904 | def noload(*keys): |
---|
| 905 | """Return a ``MapperOption`` that will convert the property of the |
---|
| 906 | given name into a non-load. |
---|
| 907 | |
---|
| 908 | Used with ``query.options()``. |
---|
| 909 | |
---|
| 910 | """ |
---|
| 911 | return strategies.EagerLazyOption(keys, lazy=None) |
---|
| 912 | |
---|
| 913 | def contains_alias(alias): |
---|
| 914 | """Return a ``MapperOption`` that will indicate to the query that |
---|
| 915 | the main table has been aliased. |
---|
| 916 | |
---|
| 917 | `alias` is the string name or ``Alias`` object representing the |
---|
| 918 | alias. |
---|
| 919 | |
---|
| 920 | """ |
---|
| 921 | return AliasOption(alias) |
---|
| 922 | |
---|
| 923 | @sa_util.accepts_a_list_as_starargs(list_deprecation='pending') |
---|
| 924 | def contains_eager(*keys, **kwargs): |
---|
| 925 | """Return a ``MapperOption`` that will indicate to the query that |
---|
| 926 | the given attribute will be eagerly loaded. |
---|
| 927 | |
---|
| 928 | Used when feeding SQL result sets directly into ``query.instances()``. |
---|
| 929 | Also bundles an ``EagerLazyOption`` to turn on eager loading in case it |
---|
| 930 | isn't already. |
---|
| 931 | |
---|
| 932 | `alias` is the string name of an alias, **or** an ``sql.Alias`` object, |
---|
| 933 | which represents the aliased columns in the query. This argument is |
---|
| 934 | optional. |
---|
| 935 | |
---|
| 936 | """ |
---|
| 937 | alias = kwargs.pop('alias', None) |
---|
| 938 | if kwargs: |
---|
| 939 | raise exceptions.ArgumentError("Invalid kwargs for contains_eager: %r" % kwargs.keys()) |
---|
| 940 | |
---|
| 941 | return (strategies.EagerLazyOption(keys, lazy=False, propagate_to_loaders=False), strategies.LoadEagerFromAliasOption(keys, alias=alias)) |
---|
| 942 | |
---|
| 943 | @sa_util.accepts_a_list_as_starargs(list_deprecation='pending') |
---|
| 944 | def defer(*keys): |
---|
| 945 | """Return a ``MapperOption`` that will convert the column property of the |
---|
| 946 | given name into a deferred load. |
---|
| 947 | |
---|
| 948 | Used with ``query.options()`` |
---|
| 949 | """ |
---|
| 950 | return strategies.DeferredOption(keys, defer=True) |
---|
| 951 | |
---|
| 952 | @sa_util.accepts_a_list_as_starargs(list_deprecation='pending') |
---|
| 953 | def undefer(*keys): |
---|
| 954 | """Return a ``MapperOption`` that will convert the column property of the |
---|
| 955 | given name into a non-deferred (regular column) load. |
---|
| 956 | |
---|
| 957 | Used with ``query.options()``. |
---|
| 958 | |
---|
| 959 | """ |
---|
| 960 | return strategies.DeferredOption(keys, defer=False) |
---|
| 961 | |
---|
| 962 | def undefer_group(name): |
---|
| 963 | """Return a ``MapperOption`` that will convert the given group of deferred |
---|
| 964 | column properties into a non-deferred (regular column) load. |
---|
| 965 | |
---|
| 966 | Used with ``query.options()``. |
---|
| 967 | |
---|
| 968 | """ |
---|
| 969 | return strategies.UndeferGroupOption(name) |
---|