- the "mutable" flag on PickleType, postgresql.ARRAY is now off

by default.  [ticket:1980]

2 files changed, 33 insertions, 32 deletions

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index 47e6d6ea8..f000520ca 100644
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -224,15 +224,11 @@ class ARRAY(sqltypes.MutableType, sqltypes.Concatenable, sqltypes.TypeEngine):
     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.::
@@ -247,14 +243,19 @@ class ARRAY(sqltypes.MutableType, sqltypes.Concatenable, sqltypes.TypeEngine):
           ``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):
diff --git a/lib/sqlalchemy/types.py b/lib/sqlalchemy/types.py
index 111f2314b..782e9f15e 100644
--- a/lib/sqlalchemy/types.py
+++ b/lib/sqlalchemy/types.py
@@ -533,16 +533,17 @@ class MutableType(object):
     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
@@ -561,8 +562,7 @@ class MutableType(object):
     
     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
@@ -1552,15 +1552,12 @@ class PickleType(MutableType, TypeDecorator):
     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.
 
@@ -1570,15 +1567,18 @@ class PickleType(MutableType, TypeDecorator):
           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