The ARRAY type may not be supported on all DBAPIs.
It is known to work on psycopg2 and not pg8000.
- **Note:** be sure to read the notes for
- :class:`.MutableType` regarding ORM
- performance implications. The :class:`.ARRAY` type's
- mutability can be disabled using the "mutable" flag.
"""
__visit_name__ = 'ARRAY'
- def __init__(self, item_type, mutable=True, as_tuple=False):
+ def __init__(self, item_type, mutable=False, as_tuple=False):
"""Construct an ARRAY.
E.g.::
``ARRAY(ARRAY(Integer))`` or such. The type mapping figures out on
the fly
- :param mutable=True: Specify whether lists passed to this
- class should be considered mutable. If so, generic copy operations
- (typically used by the ORM) will shallow-copy values.
+ :param mutable=False: Specify whether lists passed to this
+ class should be considered mutable - this enables
+ "mutable types" mode in the ORM. Be sure to read the
+ notes for :class:`.MutableType` regarding ORM
+ performance implications (default changed from ``True`` in
+ 0.7.0).
- :param as_tuple=False: Specify whether return results should be converted
- to tuples from lists. DBAPIs such as psycopg2 return lists by default.
- When tuples are returned, the results are hashable. This flag can only
- be set to ``True`` when ``mutable`` is set to ``False``. (new in 0.6.5)
+ :param as_tuple=False: Specify whether return results
+ should be converted to tuples from lists. DBAPIs such
+ as psycopg2 return lists by default. When tuples are
+ returned, the results are hashable. This flag can only
+ be set to ``True`` when ``mutable`` is set to
+ ``False``. (new in 0.6.5)
"""
if isinstance(item_type, ARRAY):
performance impact, described below.
A :class:`MutableType` usually allows a flag called
- ``mutable=True`` to enable/disable the "mutability" flag,
+ ``mutable=False`` to enable/disable the "mutability" flag,
represented on this class by :meth:`is_mutable`. Examples
include :class:`PickleType` and
:class:`~sqlalchemy.dialects.postgresql.base.ARRAY`. Setting
- this flag to ``False`` effectively disables any mutability-
- specific behavior by the ORM.
+ this flag to ``True`` enables mutability-specific behavior
+ by the ORM.
- :meth:`copy_value` and :meth:`compare_values` represent a copy
- and compare function for values of this type - implementing
- subclasses should override these appropriately.
+ The :meth:`copy_value` and :meth:`compare_values` functions
+ represent a copy and compare function for values of this
+ type - implementing subclasses should override these
+ appropriately.
The usage of mutable types has significant performance
implications when using the ORM. In order to detect changes, the
Note that for small numbers (< 100 in the Session at a time)
of objects with "mutable" values, the performance degradation is
- negligible. In most cases it's likely that the convenience allowed
- by "mutable" change detection outweighs the performance penalty.
+ negligible.
It is perfectly fine to represent "mutable" data types with the
"mutable" flag set to False, which eliminates any performance
the way out, allowing any pickleable Python object to be stored as
a serialized binary field.
- **Note:** be sure to read the notes for :class:`MutableType` regarding
- ORM performance implications.
-
"""
impl = LargeBinary
def __init__(self, protocol=pickle.HIGHEST_PROTOCOL,
- pickler=None, mutable=True, comparator=None):
+ pickler=None, mutable=False, comparator=None):
"""
Construct a PickleType.
cPickle is not available. May be any object with
pickle-compatible ``dumps` and ``loads`` methods.
- :param mutable: defaults to True; implements
+ :param mutable: defaults to False; implements
:meth:`AbstractType.is_mutable`. When ``True``, incoming
- objects should provide an ``__eq__()`` method which
- performs the desired deep comparison of members, or the
- ``comparator`` argument must be present.
-
- :param comparator: optional. a 2-arg callable predicate used
- to compare values of this type. Otherwise,
- the == operator is used to compare values.
+ objects will be compared against copies of themselves
+ using the Python "equals" operator, unless the
+ ``comparator`` argument is present. See
+ :class:`.MutableType` for details on "mutable" type
+ behavior. (default changed from ``True`` in
+ 0.7.0).
+
+ :param comparator: a 2-arg callable predicate used
+ to compare values of this type. If left as ``None``,
+ the Python "equals" operator is used to compare values.
"""
self.protocol = protocol
class Foo(object):
pass
- footable = Table('foo', metadata, Column('id', Integer,
- primary_key=True), Column('intarr',
- postgresql.ARRAY(Integer), nullable=True))
+ footable = Table('foo', metadata,
+ Column('id', Integer,primary_key=True),
+ Column('intarr',
+ postgresql.ARRAY(Integer, mutable=True),
+ nullable=True))
mapper(Foo, footable)
metadata.create_all()
sess = create_session()
assert_raises_message(
exc.ArgumentError,
"mutable must be set to False if as_tuple is True.",
- postgresql.ARRAY, Integer, as_tuple=True)
+ postgresql.ARRAY, Integer, mutable=True,
+ as_tuple=True)
t1 = Table('t1', metadata,
Column('id', Integer, primary_key=True),
Table('mutable_t', metadata,
Column('id', Integer, primary_key=True,
test_needs_autoincrement=True),
- Column('data', sa.PickleType),
+ Column('data', sa.PickleType(mutable=True)),
Column('val', sa.Unicode(30)))
@classmethod
Table('mutable_t', metadata,
Column('id', Integer, primary_key=True,
test_needs_autoincrement=True),
- Column('data', sa.PickleType(comparator=operator.eq)))
+ Column('data',
+ sa.PickleType(comparator=operator.eq, mutable=True)))
@classmethod
def setup_classes(cls):
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
