Abstract base class for Sage objects

class sage.structure.sage_object.SageObject

Bases: object

category()

db(name, compress=True)

Dumps self into the Sage database. Use db(name) by itself to reload.

The database directory is $HOME/.sage/db

dump(filename, compress=True)

Same as self.save(filename, compress)

dumps(compress=True)

Dump self to a string s, which can later be reconstituted as self using loads(s).

rename(x=None)

Change self so it prints as x, where x is a string.

Note

This is only supported for Python classes that derive from SageObject.

EXAMPLES:

sage: x = PolynomialRing(QQ,'x').gen()
sage: g = x^3 + x - 5
sage: g
x^3 + x - 5
sage: g.rename('a polynomial')
sage: g
a polynomial
sage: g + x
x^3 + 2*x - 5
sage: h = g^100
sage: str(h)[:20]
'x^300 + 100*x^298 - '
sage: h.rename('x^300 + ...')
sage: h
x^300 + ...

Real numbers are not Python classes, so rename is not supported:

sage: a = 3.14
sage: type(a)
<type 'sage.rings.real_mpfr.RealLiteral'>
sage: a.rename('pi')
...
NotImplementedError: object does not support renaming: 3.14000000000000

Note

The reason C-extension types are not supported by default is if they were then every single one would have to carry around an extra attribute, which would be slower and waste a lot of memory.

To support them for a specific class, add a cdef public __custom_name attribute.

reset_name()

save(filename=None, compress=True)

Save self to the given filename.

EXAMPLES:

sage: f = x^3 + 5
sage: f.save(SAGE_TMP + '/file')
sage: load(SAGE_TMP + '/file.sobj')
x^3 + 5

version()

The version of Sage.

Call this to save the version of Sage in this object. If you then save and load this object it will know in what version of Sage it was created.

This only works on Python classes that derive from SageObject.

sage.structure.sage_object.dumps(obj, compress=True)

Dump obj to a string s. To recover obj, use loads(s).

See also

dumps()

EXAMPLES:

sage: a = 2/3
sage: s = dumps(a)
sage: print len(s)
49
sage: loads(s)
2/3    

sage.structure.sage_object.have_same_parent(self, other)

EXAMPLES:

sage: from sage.structure.sage_object import have_same_parent
sage: have_same_parent(1, 3)
True
sage: have_same_parent(1, 1/2)
False
sage: have_same_parent(gap(1), gap(1/2))
True

sage.structure.sage_object.load(*filename, compress=True, verbose=True)

Load Sage object from the file with name filename, which will have an .sobj extension added if it doesn’t have one. Or, if the input is a filename ending in .py, .pyx, or .sage, load that file into the current running session. Loaded files are not loaded into their own namespace, i.e., this is much more like Python’s execfile than Python’s import.

Note

There is also a special Sage command (that is not available in Python) called load that you use by typing

sage: load filename.sage           # not tested

The documentation below is not for that command. The documentation for load is almost identical to that for attach. Type attach? for help on attach.

This function also loads a .sobj file over a network by specifying the full URL. (Setting verbose = False suppresses the loading progress indicator.)

Finally, if you give multiple positional input arguments, then all of those files are loaded, or all of the objects are loaded and a list of the corresponding loaded objects is returned.

EXAMPLE:

sage: u = 'http://sage.math.washington.edu/home/was/db/test.sobj'  
sage: s = load(u)                                                  # optional - internet
Attempting to load remote file: http://sage.math.washington.edu/home/was/db/test.sobj
Loading: [.]        
sage: s                                                            # optional - internet
'hello SAGE'

We test loading a file or multiple files or even mixing loading files and objects:

sage: t=tmp_filename()+'.py'; open(t,'w').write("print 'hello world'")
sage: load(t)
hello world
sage: load(t,t)
hello world
hello world
sage: t2=tmp_filename(); save(2/3,t2)
sage: load(t,t,t2)
hello world
hello world
[None, None, 2/3]

sage.structure.sage_object.loads(s, compress=True)

Recover an object x that has been dumped to a string s using s = dumps(x).

See also

dumps()

EXAMPLES:

sage: a = matrix(2, [1,2,3,-4/3])
sage: s = dumps(a)
sage: loads(s)
[   1    2]
[   3 -4/3]

If compress is True (the default), it will try to decompress the data with zlib and with bz2 (in turn); if neither succeeds, it will assume the data is actually uncompressed. If compress=False is explicitly specified, then no decompression is attempted.

sage: v = [1..10]
sage: loads(dumps(v, compress=False)) == v
True
sage: loads(dumps(v, compress=False), compress=True) == v
True
sage: loads(dumps(v, compress=True), compress=False)
...
UnpicklingError: invalid load key, 'x'.

sage.structure.sage_object.picklejar(obj, dir=None)

Create pickled sobj of obj in dir, with name the absolute value of the hash of the pickle of obj. This is used in conjunction with sage.structure.sage_object.unpickle_all.

To use this to test the whole Sage library right now, set the environment variable SAGE_PICKLE_JAR, which will make it so dumps will by default call picklejar with the default dir. Once you do that and doctest Sage, you’ll find that the SAGE_ROOT/tmp/ contains a bunch of pickled objects along with corresponding txt descriptions of them. Use the sage.structure.sage_object.unpickle_all to see if they unpickle later.

INPUTS:

• obj - a pickleable object
• dir - a string or None; if None defaults to SAGE_ROOT/tmp/pickle_jar-version

EXAMPLES:

sage: dir = tmp_dir()
sage: sage.structure.sage_object.picklejar(1,dir)
sage: len(os.listdir(dir))
2

sage.structure.sage_object.register_unpickle_override(module, name, callable, call_name=None)

Python pickles include the module and class name of classes. This means that rearranging the Sage source can invalidate old pickles. To keep the old pickles working, you can call register_unpickle_override with an old module name and class name, and the Python callable (function, class with __call__ method, etc.) to use for unpickling. (If this callable is a value in some module, you can specify the module name and class name, for the benefit of explain_pickle(..., in_current_sage=True).)

EXAMPLES:

sage: from sage.structure.sage_object import unpickle_override, register_unpickle_override
sage: unpickle_global('sage.rings.integer', 'Integer')
<type 'sage.rings.integer.Integer'>

Now we horribly break the pickling system:

sage: register_unpickle_override('sage.rings.integer', 'Integer', Rational, call_name=('sage.rings.rational', 'Rational'))
sage: unpickle_global('sage.rings.integer', 'Integer')
<type 'sage.rings.rational.Rational'>

And we reach into the internals and put it back:

sage: del unpickle_override[('sage.rings.integer', 'Integer')]
sage: unpickle_global('sage.rings.integer', 'Integer')
<type 'sage.rings.integer.Integer'>

sage.structure.sage_object.save(obj, filename, compress=None, **kwds=True)

Save obj to the file with name filename, which will have an .sobj extension added if it doesn’t have one. This will replace the contents of filename.

EXAMPLES:

sage: a = matrix(2, [1,2,3,-5/2])
sage: objfile = SAGE_TMP + 'test.sobj'
sage: objfile_short = SAGE_TMP + 'test'
sage: save(a, objfile)
sage: load(objfile_short)
[   1    2]
[   3 -5/2]
sage: E = EllipticCurve([-1,0])
sage: P = plot(E)
sage: save(P, objfile_short)
sage: save(P, filename=SAGE_TMP + "sage.png", xmin=-2)
sage: print load(objfile)
Graphics object consisting of 2 graphics primitives
sage: save("A python string", SAGE_TMP + 'test')
sage: load(objfile)
'A python string'
sage: load(objfile_short)
'A python string'

sage.structure.sage_object.unpickle_all(dir, debug=False)

Unpickle all sobj’s in the given directory, reporting failures as they occur. Also printed the number of successes and failure.

INPUT:

• dir - string; a directory or name of a .tar.bz2 file that decompresses to give a directory full of pickles.

EXAMPLES:

sage: dir = tmp_dir()
sage: sage.structure.sage_object.picklejar('hello', dir)
sage: sage.structure.sage_object.unpickle_all(dir)
Successfully unpickled 1 objects.
Failed to unpickle 0 objects.

We unpickle the standard pickle jar. This doctest tests that all “standard pickles” unpickle. Every so often the standard pickle jar should be updated by running the doctest suite with the environment variable SAGE_PICKLE_JAR set, then copying the files from SAGE_ROOT/tmp/pickle_jar* into the standard pickle jar.

sage: std = os.environ['SAGE_DATA'] + '/extcode/pickle_jar/pickle_jar.tar.bz2'
sage: print "x"; sage.structure.sage_object.unpickle_all(std)
x...
Successfully unpickled ... objects.
Failed to unpickle 0 objects.

sage.structure.sage_object.unpickle_global(module, name)

Given a module name and a name within that module (typically a class name), retrieve the corresponding object. This normally just looks up the name in the module, but it can be overridden by register_unpickle_override. This is used in the Sage unpickling mechanism, so if the Sage source code organization changes, register_unpickle_override can allow old pickles to continue to work.

EXAMPLES:

sage: from sage.structure.sage_object import unpickle_override, register_unpickle_override
sage: unpickle_global('sage.rings.integer', 'Integer')
<type 'sage.rings.integer.Integer'>

Now we horribly break the pickling system:

sage: register_unpickle_override('sage.rings.integer', 'Integer', Rational, call_name=('sage.rings.rational', 'Rational'))
sage: unpickle_global('sage.rings.integer', 'Integer')
<type 'sage.rings.rational.Rational'>

And we reach into the internals and put it back:

sage: del unpickle_override[('sage.rings.integer', 'Integer')]
sage: unpickle_global('sage.rings.integer', 'Integer')
<type 'sage.rings.integer.Integer'>