Unique Representation#

Abstract classes for cached and unique representation behavior.

What is a unique representation?#

Instances of a class have a unique instance behavior when instances of this class evaluate equal if and only if they are identical. Sage provides the base class WithEqualityById, which provides comparison by identity and a hash that is determined by the memory address of the instance. Both the equality test and the hash are implemented in Cython and are very fast, even when one has a Python class inheriting from WithEqualityById.

In many applications, one wants to combine unique instance and cached representation behaviour. This is called unique representation behaviour. We have seen above that symmetric groups have a cached representation behaviour. However, they do not show the unique representation behaviour, since they are equal to groups created in a totally different way, namely to subgroups:

Sage

sage: # needs sage.groups
sage: G = SymmetricGroup(6)
sage: G3 = G.subgroup([G((1,2,3,4,5,6)), G((1,2))])
sage: G is G3
False
sage: type(G) == type(G3)
False
sage: G == G3
True

Python

>>> from sage.all import *
>>> # needs sage.groups
>>> G = SymmetricGroup(Integer(6))
>>> G3 = G.subgroup([G((Integer(1),Integer(2),Integer(3),Integer(4),Integer(5),Integer(6))), G((Integer(1),Integer(2)))])
>>> G is G3
False
>>> type(G) == type(G3)
False
>>> G == G3
True

The unique representation behaviour can conveniently be implemented with a class that inherits from UniqueRepresentation: By adding UniqueRepresentation to the base classes, the class will simultaneously inherit from CachedRepresentation and from WithEqualityById.

For example, a symmetric function algebra is uniquely determined by the base ring. Thus, it is reasonable to use UniqueRepresentation in this case:

Sage

sage: isinstance(SymmetricFunctions(CC), SymmetricFunctions)                        # needs sage.combinat
True
sage: issubclass(SymmetricFunctions, UniqueRepresentation)                          # needs sage.combinat
True

Python

>>> from sage.all import *
>>> isinstance(SymmetricFunctions(CC), SymmetricFunctions)                        # needs sage.combinat
True
>>> issubclass(SymmetricFunctions, UniqueRepresentation)                          # needs sage.combinat
True

UniqueRepresentation differs from CachedRepresentation only by adding WithEqualityById as a base class. Hence, the above examples of argument preprocessing work for UniqueRepresentation as well.

Note that a cached representation created with UniqueFactory does not automatically provide unique representation behaviour, in spite of its name! Hence, for unique representation behaviour, one has to implement hash and equality test accordingly, for example by inheriting from WithEqualityById.

class sage.structure.unique_representation.CachedRepresentation[source]#

Bases: WithPicklingByInitArgs

Classes derived from CachedRepresentation inherit a weak cache for their instances.

Note

If this class is used as a base class, then instances are (weakly) cached, according to the arguments used to create the instance. Pickling is provided, of course by using the cache.

Note

Using this class, one can have arbitrary hash and comparison. Hence, unique representation behaviour is not provided.

EXAMPLES:

Providing a class with a weak cache for the instances is easy: Just inherit from CachedRepresentation:

Sage

sage: from sage.structure.unique_representation import CachedRepresentation
sage: class MyClass(CachedRepresentation):
....:     # all the rest as usual
....:     pass

Python

>>> from sage.all import *
>>> from sage.structure.unique_representation import CachedRepresentation
>>> class MyClass(CachedRepresentation):
...     # all the rest as usual
...     pass

We start with a simple class whose constructor takes a single value as argument (TODO: find a more meaningful example):

Sage

sage: class MyClass(CachedRepresentation):
....:     def __init__(self, value):
....:         self.value = value
....:     def __eq__(self, other):
....:         if type(self) != type(other):
....:             return False
....:         return self.value == other.value

Python

>>> from sage.all import *
>>> class MyClass(CachedRepresentation):
...     def __init__(self, value):
...         self.value = value
...     def __eq__(self, other):
...         if type(self) != type(other):
...             return False
...         return self.value == other.value

Two coexisting instances of MyClass created with the same argument data are guaranteed to share the same identity. Since Issue #12215, this is only the case if there is some strong reference to the returned instance, since otherwise it may be garbage collected:

Sage

sage: x = MyClass(1)
sage: y = MyClass(1)
sage: x is y               # There is a strong reference
True
sage: z = MyClass(2)
sage: x is z
False

Python

>>> from sage.all import *
>>> x = MyClass(Integer(1))
>>> y = MyClass(Integer(1))
>>> x is y               # There is a strong reference
True
>>> z = MyClass(Integer(2))
>>> x is z
False

In particular, modifying any one of them modifies the other (reference effect):

Sage

sage: x.value = 3
sage: x.value, y.value
(3, 3)
sage: y.value = 1
sage: x.value, y.value
(1, 1)

Python

>>> from sage.all import *
>>> x.value = Integer(3)
>>> x.value, y.value
(3, 3)
>>> y.value = Integer(1)
>>> x.value, y.value
(1, 1)

The arguments can consist of any combination of positional or keyword arguments, as taken by a usual __init__ function. However, all values passed in should be hashable:

Sage

sage: MyClass(value = [1,2,3])
Traceback (most recent call last):
...
TypeError: unhashable type: 'list'

Python

>>> from sage.all import *
>>> MyClass(value = [Integer(1),Integer(2),Integer(3)])
Traceback (most recent call last):
...
TypeError: unhashable type: 'list'

Argument preprocessing

Sometimes, one wants to do some preprocessing on the arguments, to put them in some canonical form. The following example illustrates how to achieve this; it takes as argument any iterable, and canonicalizes it into a tuple (which is hashable!):

Sage

sage: class MyClass2(CachedRepresentation):
....:     @staticmethod
....:     def __classcall__(cls, iterable):
....:         t = tuple(iterable)
....:         return super().__classcall__(cls, t)
....:
....:     def __init__(self, value):
....:         self.value = value
sage: x = MyClass2([1,2,3])
sage: y = MyClass2(tuple([1,2,3]))
sage: z = MyClass2(i for i in [1,2,3])
sage: x.value
(1, 2, 3)
sage: x is y, y is z
(True, True)

Python

>>> from sage.all import *
>>> class MyClass2(CachedRepresentation):
...     @staticmethod
...     def __classcall__(cls, iterable):
...         t = tuple(iterable)
...         return super().__classcall__(cls, t)
....:
>>>     def __init__(self, value):
...         self.value = value
>>> x = MyClass2([Integer(1),Integer(2),Integer(3)])
>>> y = MyClass2(tuple([Integer(1),Integer(2),Integer(3)]))
>>> z = MyClass2(i for i in [Integer(1),Integer(2),Integer(3)])
>>> x.value
(1, 2, 3)
>>> x is y, y is z
(True, True)

A similar situation arises when the constructor accepts default values for some of its parameters. Alas, the obvious implementation does not work:

Sage

sage: class MyClass3(CachedRepresentation):
....:     def __init__(self, value = 3):
....:         self.value = value
sage: MyClass3(3) is MyClass3()
False

Python

>>> from sage.all import *
>>> class MyClass3(CachedRepresentation):
...     def __init__(self, value = Integer(3)):
...         self.value = value
>>> MyClass3(Integer(3)) is MyClass3()
False

Instead, one should do:

Sage

sage: class MyClass3(UniqueRepresentation):
....:     @staticmethod
....:     def __classcall__(cls, value = 3):
....:         return super().__classcall__(cls, value)
....:
....:     def __init__(self, value):
....:         self.value = value
sage: MyClass3(3) is MyClass3()
True

Python

>>> from sage.all import *
>>> class MyClass3(UniqueRepresentation):
...     @staticmethod
...     def __classcall__(cls, value = Integer(3)):
...         return super().__classcall__(cls, value)
....:
>>>     def __init__(self, value):
...         self.value = value
>>> MyClass3(Integer(3)) is MyClass3()
True

A bit of explanation is in order. First, the call MyClass2([1,2,3]) triggers a call to MyClass2.__classcall__(MyClass2, [1,2,3]). This is an extension of the standard Python behavior, needed by CachedRepresentation, and implemented by the ClasscallMetaclass. Then, MyClass2.__classcall__ does the desired transformations on the arguments. Finally, it uses super to call the default implementation of __classcall__ provided by CachedRepresentation. This one in turn handles the caching and, if needed, constructs and initializes a new object in the class using __new__ and __init__ as usual.

Constraints:

__classcall__() is a staticmethod (like, implicitly, __new__)
the preprocessing on the arguments should be idempotent. That is, if MyClass2.__classcall__(<arguments>) calls CachedRepresentation.__classcall__(<preprocessed_arguments>), then MyClass2.__classcall__(<preprocessed_arguments>) should also result in a call to CachedRepresentation.__classcall__(<preprocessed_arguments>).
MyClass2.__classcall__ should return the result of CachedRepresentation.__classcall__() without modifying it.

Other than that MyClass2.__classcall__ may play any tricks, like acting as a factory and returning objects from other classes.

Warning

It is possible, but strongly discouraged, to let the __classcall__ method of a class C return objects that are not instances of C. Of course, instances of a subclass of C are fine. Compare the examples in unique_representation.

We illustrate what is meant by an “idempotent” preprocessing. Imagine that one has instances that are created with an integer-valued argument, but only depend on the square of the argument. It would be a mistake to square the given argument during preprocessing:

Sage

sage: class WrongUsage(CachedRepresentation):
....:     @staticmethod
....:     def __classcall__(cls, n):
....:         return super().__classcall__(cls, n^2)
....:     def __init__(self, n):
....:         self.n = n
....:     def __repr__(self):
....:         return "Something(%d)"%self.n
sage: import __main__
sage: __main__.WrongUsage = WrongUsage # This is only needed in doctests
sage: w = WrongUsage(3); w
Something(9)
sage: w._reduction
(<class '__main__.WrongUsage'>, (9,), {})

Python

>>> from sage.all import *
>>> class WrongUsage(CachedRepresentation):
...     @staticmethod
...     def __classcall__(cls, n):
...         return super().__classcall__(cls, n**Integer(2))
...     def __init__(self, n):
...         self.n = n
...     def __repr__(self):
...         return "Something(%d)"%self.n
>>> import __main__
>>> __main__.WrongUsage = WrongUsage # This is only needed in doctests
>>> w = WrongUsage(Integer(3)); w
Something(9)
>>> w._reduction
(<class '__main__.WrongUsage'>, (9,), {})

Indeed, the reduction data are obtained from the preprocessed arguments. By consequence, if the resulting instance is pickled and unpickled, the argument gets squared again:

Sage

sage: loads(dumps(w))
Something(81)

Python

>>> from sage.all import *
>>> loads(dumps(w))
Something(81)

Instead, the preprocessing should only take the absolute value of the given argument, while the squaring should happen inside of the __init__ method, where it won’t mess with the cache:

Sage

sage: class BetterUsage(CachedRepresentation):
....:     @staticmethod
....:     def __classcall__(cls, n):
....:         return super().__classcall__(cls, abs(n))
....:     def __init__(self, n):
....:         self.n = n^2
....:     def __repr__(self):
....:         return "SomethingElse(%d)"%self.n
sage: __main__.BetterUsage = BetterUsage # This is only needed in doctests
sage: b = BetterUsage(3); b
SomethingElse(9)
sage: loads(dumps(b)) is b
True
sage: b is BetterUsage(-3)
True

Python

>>> from sage.all import *
>>> class BetterUsage(CachedRepresentation):
...     @staticmethod
...     def __classcall__(cls, n):
...         return super().__classcall__(cls, abs(n))
...     def __init__(self, n):
...         self.n = n**Integer(2)
...     def __repr__(self):
...         return "SomethingElse(%d)"%self.n
>>> __main__.BetterUsage = BetterUsage # This is only needed in doctests
>>> b = BetterUsage(Integer(3)); b
SomethingElse(9)
>>> loads(dumps(b)) is b
True
>>> b is BetterUsage(-Integer(3))
True

Cached representation and mutability

CachedRepresentation is primarily intended for implementing objects which are (at least semantically) immutable. This is in particular assumed by the default implementations of copy and deepcopy:

Sage

sage: copy(x) is x
True
sage: from copy import deepcopy
sage: deepcopy(x) is x
True

Python

>>> from sage.all import *
>>> copy(x) is x
True
>>> from copy import deepcopy
>>> deepcopy(x) is x
True

However, in contrast to UniqueRepresentation, using CachedRepresentation allows for a comparison that is not by identity:

Sage

sage: t = MyClass(3)
sage: z = MyClass(2)
sage: t.value = 2

Python

>>> from sage.all import *
>>> t = MyClass(Integer(3))
>>> z = MyClass(Integer(2))
>>> t.value = Integer(2)

Now t and z are non-identical, but equal:

Sage

sage: t.value == z.value
True
sage: t == z
True
sage: t is z
False

Python

>>> from sage.all import *
>>> t.value == z.value
True
>>> t == z
True
>>> t is z
False

More on cached representation and identity

CachedRepresentation is implemented by means of a cache. This cache uses weak references in general, but strong references to the most recently created objects. Hence, when all other references to, say, MyClass(1) have been deleted, the instance is eventually deleted from memory (after enough other objects have been created to remove the strong reference to MyClass(1)). A later call to MyClass(1) reconstructs the instance from scratch:

Sage

sage: class SomeClass(UniqueRepresentation):
....:     def __init__(self, i):
....:         print("creating new instance for argument %s" % i)
....:         self.i = i
....:     def __del__(self):
....:         print("deleting instance for argument %s" % self.i)
sage: class OtherClass(UniqueRepresentation):
....:     def __init__(self, i):
....:         pass
sage: O = SomeClass(1)
creating new instance for argument 1
sage: O is SomeClass(1)
True
sage: O is SomeClass(2)
creating new instance for argument 2
False
sage: L = [OtherClass(i) for i in range(200)]
deleting instance for argument 2
sage: del O
deleting instance for argument 1
sage: O = SomeClass(1)
creating new instance for argument 1
sage: del O
sage: del L
sage: L = [OtherClass(i) for i in range(200)]
deleting instance for argument 1

Python

>>> from sage.all import *
>>> class SomeClass(UniqueRepresentation):
...     def __init__(self, i):
...         print("creating new instance for argument %s" % i)
...         self.i = i
...     def __del__(self):
...         print("deleting instance for argument %s" % self.i)
>>> class OtherClass(UniqueRepresentation):
...     def __init__(self, i):
...         pass
>>> O = SomeClass(Integer(1))
creating new instance for argument 1
>>> O is SomeClass(Integer(1))
True
>>> O is SomeClass(Integer(2))
creating new instance for argument 2
False
>>> L = [OtherClass(i) for i in range(Integer(200))]
deleting instance for argument 2
>>> del O
deleting instance for argument 1
>>> O = SomeClass(Integer(1))
creating new instance for argument 1
>>> del O
>>> del L
>>> L = [OtherClass(i) for i in range(Integer(200))]
deleting instance for argument 1

Cached representation and pickling

The default Python pickling implementation (by reconstructing an object from its class and dictionary, see “The pickle protocol” in the Python Library Reference) does not preserve cached representation, as Python has no chance to know whether and where the same object already exists.

CachedRepresentation tries to ensure appropriate pickling by implementing a __reduce__ method returning the arguments passed to the constructor:

Sage

sage: import __main__             # Fake MyClass being defined in a python module
sage: __main__.MyClass = MyClass
sage: x = MyClass(1)
sage: loads(dumps(x)) is x
True

Python

>>> from sage.all import *
>>> import __main__             # Fake MyClass being defined in a python module
>>> __main__.MyClass = MyClass
>>> x = MyClass(Integer(1))
>>> loads(dumps(x)) is x
True

CachedRepresentation uses the __reduce__ pickle protocol rather than __getnewargs__ because the latter does not handle keyword arguments:

Sage

sage: x = MyClass(value = 1)
sage: x.__reduce__()
(<function unreduce at ...>, (<class '__main__.MyClass'>, (), {'value': 1}))
sage: x is loads(dumps(x))
True

Python

>>> from sage.all import *
>>> x = MyClass(value = Integer(1))
>>> x.__reduce__()
(<function unreduce at ...>, (<class '__main__.MyClass'>, (), {'value': 1}))
>>> x is loads(dumps(x))
True

Note

The default implementation of __reduce__ in CachedRepresentation requires to store the constructor’s arguments in the instance dictionary upon construction:

Sage

sage: x.__dict__
{'_reduction': (<class '__main__.MyClass'>, (), {'value': 1}), 'value': 1}

Python

>>> from sage.all import *
>>> x.__dict__
{'_reduction': (<class '__main__.MyClass'>, (), {'value': 1}), 'value': 1}

It is often easy in a derived subclass to reconstruct the constructor’s arguments from the instance data structure. When this is the case, __reduce__ should be overridden; automagically the arguments won’t be stored anymore:

Sage

sage: class MyClass3(UniqueRepresentation):
....:     def __init__(self, value):
....:         self.value = value
....:
....:     def __reduce__(self):
....:         return (MyClass3, (self.value,))
sage: import __main__; __main__.MyClass3 = MyClass3  # Fake MyClass3 being defined in a python module
sage: x = MyClass3(1)
sage: loads(dumps(x)) is x
True
sage: x.__dict__
{'value': 1}

Python

>>> from sage.all import *
>>> class MyClass3(UniqueRepresentation):
...     def __init__(self, value):
...         self.value = value
....:
>>>     def __reduce__(self):
...         return (MyClass3, (self.value,))
>>> import __main__; __main__.MyClass3 = MyClass3  # Fake MyClass3 being defined in a python module
>>> x = MyClass3(Integer(1))
>>> loads(dumps(x)) is x
True
>>> x.__dict__
{'value': 1}

Migrating classes to CachedRepresentation and unpickling

We check that, when migrating a class to CachedRepresentation, older pickles can still be reasonably unpickled. Let us create a (new style) class, and pickle one of its instances:

Sage

sage: class MyClass4():
....:     def __init__(self, value):
....:         self.value = value
sage: import __main__; __main__.MyClass4 = MyClass4  # Fake MyClass4 being defined in a python module
sage: pickle = dumps(MyClass4(1))

Python

>>> from sage.all import *
>>> class MyClass4():
...     def __init__(self, value):
...         self.value = value
>>> import __main__; __main__.MyClass4 = MyClass4  # Fake MyClass4 being defined in a python module
>>> pickle = dumps(MyClass4(Integer(1)))

It can be unpickled:

Sage

sage: y = loads(pickle)
sage: y.value
1

Python

>>> from sage.all import *
>>> y = loads(pickle)
>>> y.value
1

Now, we upgrade the class to derive from UniqueRepresentation, which inherits from CachedRepresentation:

Sage

sage: class MyClass4(UniqueRepresentation, object):
....:     def __init__(self, value):
....:         self.value = value
sage: import __main__; __main__.MyClass4 = MyClass4  # Fake MyClass4 being defined in a python module
sage: __main__.MyClass4 = MyClass4

Python

>>> from sage.all import *
>>> class MyClass4(UniqueRepresentation, object):
...     def __init__(self, value):
...         self.value = value
>>> import __main__; __main__.MyClass4 = MyClass4  # Fake MyClass4 being defined in a python module
>>> __main__.MyClass4 = MyClass4

The pickle can still be unpickled:

Sage

sage: y = loads(pickle)
sage: y.value
1

Python

>>> from sage.all import *
>>> y = loads(pickle)
>>> y.value
1

Note however that, for the reasons explained above, unique representation is not guaranteed in this case:

Sage

sage: y is MyClass4(1)
False

Python

>>> from sage.all import *
>>> y is MyClass4(Integer(1))
False

Todo

Illustrate how this can be fixed on a case by case basis.

Now, we redo the same test for a class deriving from SageObject:

Sage

sage: class MyClass4(SageObject):
....:     def __init__(self, value):
....:         self.value = value
sage: import __main__; __main__.MyClass4 = MyClass4  # Fake MyClass4 being defined in a python module
sage: pickle = dumps(MyClass4(1))

sage: class MyClass4(UniqueRepresentation, SageObject):
....:     def __init__(self, value):
....:         self.value = value
sage: __main__.MyClass4 = MyClass4
sage: y = loads(pickle)
sage: y.value
1

Python

>>> from sage.all import *
>>> class MyClass4(SageObject):
...     def __init__(self, value):
...         self.value = value
>>> import __main__; __main__.MyClass4 = MyClass4  # Fake MyClass4 being defined in a python module
>>> pickle = dumps(MyClass4(Integer(1)))

>>> class MyClass4(UniqueRepresentation, SageObject):
...     def __init__(self, value):
...         self.value = value
>>> __main__.MyClass4 = MyClass4
>>> y = loads(pickle)
>>> y.value
1

Caveat: unpickling instances of a formerly old-style class is not supported yet by default:

Sage

sage: class MyClass4:
....:     def __init__(self, value):
....:         self.value = value
sage: import __main__; __main__.MyClass4 = MyClass4  # Fake MyClass4 being defined in a python module
sage: pickle = dumps(MyClass4(1))

sage: class MyClass4(UniqueRepresentation, SageObject):
....:     def __init__(self, value):
....:         self.value = value
sage: __main__.MyClass4 = MyClass4
sage: y = loads(pickle)  # todo: not implemented
sage: y.value            # todo: not implemented
1

Python

>>> from sage.all import *
>>> class MyClass4:
...     def __init__(self, value):
...         self.value = value
>>> import __main__; __main__.MyClass4 = MyClass4  # Fake MyClass4 being defined in a python module
>>> pickle = dumps(MyClass4(Integer(1)))

>>> class MyClass4(UniqueRepresentation, SageObject):
...     def __init__(self, value):
...         self.value = value
>>> __main__.MyClass4 = MyClass4
>>> y = loads(pickle)  # todo: not implemented
>>> y.value            # todo: not implemented
1

Rationale for the current implementation

CachedRepresentation and derived classes use the ClasscallMetaclass of the standard Python type. The following example explains why.

We define a variant of MyClass where the calls to __init__ are traced:

Sage

sage: class MyClass(CachedRepresentation):
....:     def __init__(self, value):
....:         print("initializing object")
....:         self.value = value

Python

>>> from sage.all import *
>>> class MyClass(CachedRepresentation):
...     def __init__(self, value):
...         print("initializing object")
...         self.value = value

Let us create an object twice:

Sage

sage: x = MyClass(1)
initializing object
sage: z = MyClass(1)

Python

>>> from sage.all import *
>>> x = MyClass(Integer(1))
initializing object
>>> z = MyClass(Integer(1))

As desired the __init__ method was only called the first time, which is an important feature.

As far as we can tell, this is not achievable while just using __new__ and __init__ (as defined by type; see Section Basic Customization in the Python Reference Manual). Indeed, __init__ is called systematically on the result of __new__ whenever the result is an instance of the class.

Another difficulty is that argument preprocessing (as in the example above) cannot be handled by __new__, since the unprocessed arguments will be passed down to __init__.

class sage.structure.unique_representation.UniqueRepresentation[source]#

Bases: CachedRepresentation, WithEqualityById

Classes derived from UniqueRepresentation inherit a unique representation behavior for their instances.

See also

unique_representation

EXAMPLES:

The short story: to construct a class whose instances have a unique representation behavior one just has to do:

Sage

sage: class MyClass(UniqueRepresentation):
....:     # all the rest as usual
....:     pass

Python

>>> from sage.all import *
>>> class MyClass(UniqueRepresentation):
...     # all the rest as usual
...     pass

Everything below is for the curious or for advanced usage.

What is unique representation?

Instances of a class have a unique representation behavior when instances evaluate equal if and only if they are identical (i.e., share the same memory representation), if and only if they were created using equal arguments. For example, calling twice:

Sage

sage: f = SymmetricFunctions(QQ)                                                # needs sage.combinat sage.modules
sage: g = SymmetricFunctions(QQ)                                                # needs sage.combinat sage.modules

Python

>>> from sage.all import *
>>> f = SymmetricFunctions(QQ)                                                # needs sage.combinat sage.modules
>>> g = SymmetricFunctions(QQ)                                                # needs sage.combinat sage.modules

to create the symmetric function algebra over \(\QQ\) actually gives back the same object:

Sage

sage: f == g                                                                    # needs sage.combinat sage.modules
True
sage: f is g                                                                    # needs sage.combinat sage.modules
True

Python

>>> from sage.all import *
>>> f == g                                                                    # needs sage.combinat sage.modules
True
>>> f is g                                                                    # needs sage.combinat sage.modules
True

This is a standard design pattern. It allows for sharing cached data (say representation theoretical information about a group) as well as for very fast hashing and equality testing. This behaviour is typically desirable for parents and categories. It can also be useful for intensive computations where one wants to cache all the operations on a small set of elements (say the multiplication table of a small group), and access this cache as quickly as possible.

UniqueRepresentation is very easy to use: a class just needs to derive from it, or make sure some of its super classes does. Also, it groups together the class and the factory in a single gadget:

Sage

sage: isinstance(SymmetricFunctions(CC), SymmetricFunctions)                    # needs sage.combinat sage.modules
True
sage: issubclass(SymmetricFunctions, UniqueRepresentation)                      # needs sage.combinat sage.modules
True

Python

>>> from sage.all import *
>>> isinstance(SymmetricFunctions(CC), SymmetricFunctions)                    # needs sage.combinat sage.modules
True
>>> issubclass(SymmetricFunctions, UniqueRepresentation)                      # needs sage.combinat sage.modules
True

This nice behaviour is not available when one just uses a factory:

Sage

sage: isinstance(GF(7), GF)
Traceback (most recent call last):
...
TypeError: isinstance() arg 2 must be a type...

sage: isinstance(GF, sage.structure.factory.UniqueFactory)
True

Python

>>> from sage.all import *
>>> isinstance(GF(Integer(7)), GF)
Traceback (most recent call last):
...
TypeError: isinstance() arg 2 must be a type...

>>> isinstance(GF, sage.structure.factory.UniqueFactory)
True

In addition, UniqueFactory only provides the cached representation behaviour, but not the unique representation behaviour—the examples in unique_representation explain this difference.

On the other hand, the UniqueRepresentation class is more intrusive, as it imposes a behavior (and a metaclass) on all the subclasses. In particular, the unique representation behaviour is imposed on all subclasses (unless the __classcall__ method is overloaded and not called in the subclass, which is not recommended). Its implementation is also more technical, which leads to some subtleties.

EXAMPLES:

We start with a simple class whose constructor takes a single value as argument. This pattern is similar to what is done in sage.combinat.sf.sf.SymmetricFunctions:

Sage

sage: class MyClass(UniqueRepresentation):
....:     def __init__(self, value):
....:         self.value = value

Python

>>> from sage.all import *
>>> class MyClass(UniqueRepresentation):
...     def __init__(self, value):
...         self.value = value

Sage

sage: x = MyClass(1)
sage: y = MyClass(1)
sage: x is y               # There is a strong reference
True
sage: z = MyClass(2)
sage: x is z
False

Python

>>> from sage.all import *
>>> x = MyClass(Integer(1))
>>> y = MyClass(Integer(1))
>>> x is y               # There is a strong reference
True
>>> z = MyClass(Integer(2))
>>> x is z
False

In particular, modifying any one of them modifies the other (reference effect):

Sage

sage: x.value = 3
sage: x.value, y.value
(3, 3)
sage: y.value = 1
sage: x.value, y.value
(1, 1)

Python

>>> from sage.all import *
>>> x.value = Integer(3)
>>> x.value, y.value
(3, 3)
>>> y.value = Integer(1)
>>> x.value, y.value
(1, 1)

When comparing two instances of a unique representation with == or != comparison by identity is used:

Sage

sage: x == y
True
sage: x is y
True
sage: z = MyClass(2)
sage: x == z
False
sage: x is z
False
sage: x != y
False
sage: x != z
True

Python

>>> from sage.all import *
>>> x == y
True
>>> x is y
True
>>> z = MyClass(Integer(2))
>>> x == z
False
>>> x is z
False
>>> x != y
False
>>> x != z
True

A hash function equivalent to object.__hash__() is used, which is compatible with comparison by identity. However this means that the hash function may change in between Sage sessions, or even within the same Sage session.

Sage

sage: hash(x) == object.__hash__(x)
True

Python

>>> from sage.all import *
>>> hash(x) == object.__hash__(x)
True

Warning

It is possible to inherit from UniqueRepresentation and then overload comparison in a way that destroys the unique representation property. We strongly recommend against it! You should use CachedRepresentation instead.

Mixing super types and super classes

class sage.structure.unique_representation.WithPicklingByInitArgs[source]#

Bases: object

Classes derived from WithPicklingByInitArgs store the arguments passed to __init__() to implement pickling.

This class is for objects that are semantically immutable and determined by the class and the arguments passed to __init__(). The class also provides implementations of __copy__() and __deepcopy__(), which simply return the object.

sage.structure.unique_representation.unreduce(cls, args, keywords)[source]#

Calls a class on the given arguments:

Sage

sage: sage.structure.unique_representation.unreduce(Integer, (1,), {})
1

Python

>>> from sage.all import *
>>> sage.structure.unique_representation.unreduce(Integer, (Integer(1),), {})
1

Todo

should reuse something preexisting …

Unique Representation#

What is a cached representation?#

Implementing a cached representation#

Using `CachedRepresentation`#

Normalising the arguments#

Using `UniqueFactory`#

Comparing the two ways of implementing a cached representation#

Simplicity and transparency#

Class inheritance#

Python versus extension classes#

What is a unique representation?#

Unique Representation#

What is a cached representation?#

Implementing a cached representation#

Using CachedRepresentation#

Normalising the arguments#

Using UniqueFactory#

Comparing the two ways of implementing a cached representation#

Simplicity and transparency#

Class inheritance#

Python versus extension classes#

What is a unique representation?#

Using `CachedRepresentation`#

Using `UniqueFactory`#