Mutability Cython Implementation

class sage.structure.mutability.Mutability

Bases: object

Class to mix in mutability feature.

EXAMPLES:

sage: class A(SageObject, Mutability):
....:     def __init__(self, val):
....:         self._val = val
....:     def change(self, val):
....:         self._require_mutable()
....:         self._val = val
....:     def __hash__(self):
....:         self._require_immutable()
....:         return hash(self._val)
sage: a = A(4)
sage: a._val
4
sage: a.change(6); a._val
6
sage: hash(a)
Traceback (most recent call last):
...
ValueError: object is mutable; please make it immutable first
sage: a.set_immutable()
sage: a.change(4)
Traceback (most recent call last):
...
ValueError: object is immutable; please change a copy instead
sage: hash(a)
6
is_immutable()

Return True if this object is immutable (cannot be changed) and False if it is not.

To make this object immutable use self.set_immutable().

EXAMPLES:

sage: v = Sequence([1,2,3,4/5])
sage: v[0] = 5
sage: v
[5, 2, 3, 4/5]
sage: v.is_immutable()
False
sage: v.set_immutable()
sage: v.is_immutable()
True
is_mutable()

Return True if this object is mutable (can be changed) and False if it is not.

To make this object immutable use self.set_immutable().

EXAMPLES:

sage: v = Sequence([1,2,3,4/5])
sage: v[0] = 5
sage: v
[5, 2, 3, 4/5]
sage: v.is_mutable()
True
sage: v.set_immutable()
sage: v.is_mutable()
False
set_immutable()

Make this object immutable, so it can never again be changed.

EXAMPLES:

sage: v = Sequence([1,2,3,4/5])
sage: v[0] = 5
sage: v
[5, 2, 3, 4/5]
sage: v.set_immutable()
sage: v[3] = 7
Traceback (most recent call last):
...
ValueError: object is immutable; please change a copy instead.
sage.structure.mutability.require_immutable(f)

A decorator that requires immutability for a method to be called.

Note

Objects whose methods use this decorator should have an attribute _is_immutable. Otherwise, the object is assumed to be mutable.

EXAMPLES:

sage: from sage.structure.mutability import require_mutable, require_immutable
sage: class A(object):
....:  def __init__(self, val):
....:      self._m = val
....:  @require_mutable
....:  def change(self, new_val):
....:      'change self'
....:      self._m = new_val
....:  @require_immutable
....:  def __hash__(self):
....:      'implement hash'
....:      return hash(self._m)
sage: a = A(5)
sage: a.change(6)
sage: hash(a)   # indirect doctest
Traceback (most recent call last):
...
ValueError: <class '__main__.A'> instance is mutable, <function ...__hash__ at ...> must not be called
sage: a._is_immutable = True
sage: hash(a)
6
sage: a.change(7)
Traceback (most recent call last):
...
ValueError: <class '__main__.A'> instance is immutable, <function ...change at ...> must not be called
sage: from sage.misc.sageinspect import sage_getdoc
sage: print(sage_getdoc(a.__hash__))
implement hash

AUTHORS:

sage.structure.mutability.require_mutable(f)

A decorator that requires mutability for a method to be called.

Note

Objects whose methods use this decorator should have an attribute _is_immutable. Otherwise, the object is assumed to be mutable.

EXAMPLES:

sage: from sage.structure.mutability import require_mutable, require_immutable
sage: class A(object):
....:     def __init__(self, val):
....:         self._m = val
....:     @require_mutable
....:     def change(self, new_val):
....:         'change self'
....:         self._m = new_val
....:     @require_immutable
....:     def __hash__(self):
....:         'implement hash'
....:         return hash(self._m)
sage: a = A(5)
sage: a.change(6)
sage: hash(a)
Traceback (most recent call last):
...
ValueError: <class '__main__.A'> instance is mutable, <function ...__hash__ at ...> must not be called
sage: a._is_immutable = True
sage: hash(a)
6
sage: a.change(7)   # indirect doctest
Traceback (most recent call last):
...
ValueError: <class '__main__.A'> instance is immutable, <function ...change at ...> must not be called
sage: from sage.misc.sageinspect import sage_getdoc
sage: print(sage_getdoc(a.change))
change self

AUTHORS: