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) |
---|