root/galaxy-central/eggs/SQLAlchemy-0.5.6_dev_r6498-py2.6.egg/sqlalchemy/orm/__init__.py

リビジョン 3, 37.4 KB (コミッタ: kohda, 14 年 前)

Install Unix tools  http://hannonlab.cshl.edu/galaxy_unix_tools/galaxy.html

行番号 
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"""
8Functional constructs for ORM configuration.
9
10See the SQLAlchemy object relational tutorial and mapper configuration
11documentation for an overview of how this module is used.
12
13"""
14
15from sqlalchemy.orm import exc
16from sqlalchemy.orm.mapper import (
17     Mapper,
18     _mapper_registry,
19     class_mapper,
20     )
21from sqlalchemy.orm.interfaces import (
22     EXT_CONTINUE,
23     EXT_STOP,
24     ExtensionOption,
25     InstrumentationManager,
26     MapperExtension,
27     PropComparator,
28     SessionExtension,
29     AttributeExtension,
30     )
31from sqlalchemy.orm.util import (
32     AliasedClass as aliased,
33     Validator,
34     join,
35     object_mapper,
36     outerjoin,
37     polymorphic_union,
38     with_parent,
39     )
40from sqlalchemy.orm.properties import (
41     BackRef,
42     ColumnProperty,
43     ComparableProperty,
44     CompositeProperty,
45     RelationProperty,
46     PropertyLoader,
47     SynonymProperty,
48     )
49from sqlalchemy.orm import mapper as mapperlib
50from sqlalchemy.orm.mapper import reconstructor, validates
51from sqlalchemy.orm import strategies
52from sqlalchemy.orm.query import AliasOption, Query
53from sqlalchemy.sql import util as sql_util
54from sqlalchemy.orm.session import Session as _Session
55from sqlalchemy.orm.session import object_session, sessionmaker
56from sqlalchemy.orm.scoping import ScopedSession
57from 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
105def 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
144def 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
183def 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
425def 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
470def 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
510def 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
583def 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
593def 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
603def 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
753def 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
797def 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
834def 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
843def 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
857def 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')
868def 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')
878def 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')
895def 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
904def 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
913def 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')
924def 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')
944def 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')
953def 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
962def 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)
Note: リポジトリブラウザについてのヘルプは TracBrowser を参照してください。