The persistence module

Functions

Functions for storing and retrieving archive files using Python pickle format are

dump()

load()

Functions for storing and retrieving pickled archive strings are

dumps()

loads()

Functions for storing and retrieving archive files using JSON format are

dump_json()

load_json()

Functions for storing and retrieving an archive as a JSON-formatted string are

dumps_json()

loads_json()

Functions for storing and retrieving archive files using XML format are

dump_xml()

load_xml()

Functions for storing and retrieving an archive as an XML-formatted string are

dumps_xml()

loads_xml()

Module contents

class Archive

An Archive helps to store and retrieve uncertain numbers, so that they can be used in later calculations.

A particular Archive object can either be used to prepare a record of uncertain numbers for storage, or to retrieve a stored record.

Changed in version 1.5.0.

add(**kwargs)

Add entries to an archive.

Each entry is given a name that identifies it within the archive.

Example

>>> a = pr.Archive()
>>> x = ureal(1,1)
>>> y = ureal(2,1)
>>> z = ureal(20,1)
>>> a.add(x=x,fred=y)

# Entries can also be added using the name as a key
>>> a['z'] = z

Here f is a file stream opened in mode ‘wb’:

>>> pr.dump(f, a)
>>> f.close()

static copy(ar)

A copy constructor for archive objects.

A new Archive object is returned containing a copy of the data in ar.

The returned archive can have more uncertain numbers added, and can be stored.

Parameters:: ar (Archive) – an archive object.

Added in version 1.5.0.

extract(*args)

Extract uncertain numbers by name

Parameters:: args – names of uncertain numbers stored in the archive

If just one name is provided, a single uncertain number is returned. Otherwise a sequence of uncertain numbers is returned.

Example

Continuing the example in add(), but in a different Python session, f is now a file stream opened in ‘rb’ mode:

>>> a = pr.load(f)
>>> f.close()

>>> a.extract('fred')
ureal(2.0,1.0,inf)
>>> x, fred = a.extract('x','fred')
>>> x
ureal(1.0,1.0,inf)

# Entries can also be extracted using the name as a key
>>> a['z']
ureal(20.0,1.0,inf)

items(): Return a list of name -to- uncertain-number pairs

iteritems(): Return an iterator of name -to- uncertain-number pairs

iterkeys(): Return an iterator for names

itervalues(): Return an iterator for uncertain numbers

keys(): Return a list of names

values(): Return a list of uncertain numbers

dump(file, ar)

Save an archive in a file

Parameters:

file – a file object opened in binary mode (with ‘wb’)
ar – an Archive object

Several archives can be saved in the same file by repeated use of this function.

Warning

The function dump is deprecated since version 1.5 and is planned for removal in version 2.0. Support for Python pickle to store and retrieve GTC archives is being dropped.

dump_json(file, ar, **kw)

Save an archive in a file in JSON format

Parameters:

file – a file object opened in text mode (with ‘w’)
ar – an Archive object

Keyword arguments will be passed to json.dump()

Only one archive can be saved in a file.

Added in version 1.3.0.

dump_xml(file, ar, indent=None, prefix=None, **kw)

Save an archive in a file in XML format.

Parameters:

file – a file name or a file-like object that can be written to.
ar – an Archive object.
indent (int or None) – the indentation to apply between XML elements so that the XML document is in a pretty-printed format. The indent value must be a non-negative integer.
prefix (str or None) – The prefix to use for the XML namespace.

Keyword arguments will be passed to ElementTree.write().

Only one archive can be saved in a file.

Added in version 1.5.0.

dumps(ar, protocol=5)

Save an archive pickled in a string

Parameters:

ar – an Archive object
protocol – encoding type

Possible values for protocol are described in the Python documentation for the pickle module.

protocol=0 creates an ASCII string, but note that many (special) linefeed characters are embedded.

Warning

The function dumps is deprecated since version 1.5 and is planned for removal in version 2.0. Support for Python pickle to store and retrieve GTC archives is being dropped.

dumps_json(ar, **kw)

Convert an archive to a JSON string

Parameters:: ar – an Archive object

Keyword arguments will be passed to json.dumps()

Added in version 1.3.0.

dumps_xml(ar, indent=None, prefix=None, **kw)

Convert an archive to an XML document bytestring (or string).

Parameters:

ar – an Archive object.
indent (int or None) – the indentation to apply between XML elements so that the XML document is in a pretty-printed format. The indent value must be a non-negative integer.
prefix (str or None) – The prefix to use for the XML namespace.

Keyword arguments will be passed to ElementTree.tostring().

The return type, bytes or str, depends on whether an encoding keyword argument is specified and what its value is. The default return type is bytes.

Added in version 1.5.0.

load(file)

Load an archive from a file

Parameters:: file – a file object opened in binary mode (with ‘rb’)

Several archives can be extracted from the same file by repeatedly calling this function.

Warning

The function load is deprecated since version 1.5 and is planned for removal in version 2.0. Support for Python pickle to store and retrieve GTC archives is being dropped.

load_json(file, **kw)

Load an archive from a file

Parameters:: file – a file created by dump_json()

Keyword arguments will be passed to json.load()

Added in version 1.3.0.

load_xml(file)

Load an Archive from a file in XML format.

Parameters:: file – a file name or a file-like object that can be read.

Added in version 1.5.0.

loads(s)

Return an archive object from a pickled string

Parameters:: s – a string created by dumps()

Warning

The function loads is deprecated since version 1.5 and is planned for removal in version 2.0. Support for Python pickle to store and retrieve GTC archives is being dropped.

loads_json(s, **kw)

Return an archive object by converting a JSON string

Parameters:: s – a string created by dumps_json()

Keyword arguments will be passed to json.loads()

Added in version 1.3.0.

loads_xml(s)

Return an Archive object by converting an XML string.

Parameters:: s (bytes or str) – a string created by dumps_xml().

Added in version 1.5.0.