24. project — project.py

Functions for managing a project in pyFormex.

24.1. Classes defined in module project

class project.Unpickler(f, try_resolve=True)

Customized Unpickler class

find_class(module, name)

Return an object from a specified module.

If necessary, the module will be imported. Subclasses may override this method (e.g. to restrict unpickling of arbitrary classes and functions).

This method is called whenever a class or a function object is needed. Both arguments passed are str objects.

class project.Project(filename=None, access='wr', convert=True, signature='pyFormex 2.0 (release-2.0-1-gc440c89d) DEVELOPMENT VERSION', compression=5, binary=True, data={}, protocol=3, **kargs)

Project: a persistent storage of pyFormex data.

A pyFormex Project is a regular Python dict that can contain named data of any kind, and can be saved to a file to create persistence over different pyFormex sessions.

The Project class is used by pyFormex for the pyformex.PF global variable that collects variables exported from pyFormex scripts. While projects are mostly handled through the pyFormex GUI, notably the File menu, the user may also create and handle his own Project objects from a script.

Because of the way pyFormex Projects are written to file, there may be problems when trying to read a project file that was created with another pyFormex version. Problems may occur if the project contains data of a class whose implementation has changed, or whose definition has been relocated. Our policy is to provide backwards compatibility: newer versions of pyFormex will normally read the older project formats. Saving is always done in the newest format, and these can generally not be read back by older program versions (unless you are prepared to do some hacking).

Warning

Compatibility issues.

Occasionally you may run into problems when reading back an old project file, especially when it was created by an unreleased (development) version of pyFormex. Because pyFormex is evolving fast, we can not test the full compatibility with every revision You can file a support request on the pyFormex support tracker. and we will try to add the required conversion code to pyFormex.

The project files are mainly intended as a means to easily save lots of data of any kind and to restore them in the same session or a later session, to pass them to another user (with the same or later pyFormex version), to store them over a medium time period. Occasionally opening and saving back your project files with newer pyFormex versions may help to avoid read-back problems over longer time.

For a problemless long time storage of Geometry type objects you may consider to write them to a pyFormex Geometry file (.pgf) instead, since this uses a stable ascii based format. It can however (currently) only store obects of class Geometry or one of its subclasses.

Parameters:

• filename: the name of the file where the Project data will be saved. If the file exists (and access is not w), it should be a previously saved Project and an attempt will be made to load the data from this file into the Project. If this fails, an error is raised.

  If the file exists and access is w, it will be overwritten, destroying any previous contents.

  If no filename is specified, a temporary file will be created when the Project is saved for the first time. The file with not be automatically deleted. The generated name can be retrieved from the filename attribute.

• access: One of ‘wr’ (default), ‘rw’, ‘w’ or ‘r’. If the string contains an ‘r’ the data from an existing file will be read into the dict. If the string starts with an ‘r’, the file should exist. If the string contains a ‘w’, the data can be written back to the file. The ‘r’ access mode is thus a read-only mode.

  access	File must exist	File is read	File can be written
  r	yes	yes	no
  rw	yes	yes	yes
  wr	no	if it exists	yes
  w	no	no	yes

• convert: if True (default), and the file is opened for reading, an attempt is made to open old projects in a compatibility mode, doing the necessary conversions to new data formats. If convert is set False, only the latest format can be read and older formats will generate an error.

• signature: A text that will be written in the header record of the file. This can e.g. be used to record format version info.

• compression: An integer from 0 to 9: compression level. For large data sets, compression leads to much smaller files. 0 is no compression, 9 is maximal compression. The default is 4.

• binary: if False and no compression is used, storage is done in an ASCII format, allowing to edit the file. Otherwise, storage uses a binary format. Using binary=False is deprecated.

• data: a dict-like object to initialize the Project contents. These data may override values read from the file.

Example

>>> d = dict(a=1,b=2,c=3,d=[1,2,3],e={'f':4,'g':5})
>>> P = Project()
>>> P.update(d)
>>> print(P) # doctest: +ELLIPSIS
Project name: None
  access: wr    mode: b     gzip: 5
  signature: pyFormex ...
  contents: ['a', 'b', 'c', 'd', 'e']
<BLANKLINE>
>>> print(utils.dictStr(P)) # doctest: +ELLIPSIS
{'a': 1, 'b': 2, 'c': 3, 'd': [1, 2, 3], 'e': ...}
>>> with utils.TempFile() as tmp:
...     P.save(filename=tmp.path, quiet=True)
...     P.clear()
...     print(utils.dictStr(P))
...     P.load(quiet=True)
{}
>>> print(utils.dictStr(P)) # doctest: +ELLIPSIS
{'a': 1, 'b': 2, 'c': 3, 'd': [1, 2, 3], 'e': ...}

header_data()

Construct the data to be saved in the header.

save(filename=None, quiet=False)

Save the project to file.

readHeader(f, quiet=False)

Read the header from a project file.

f is the file opened for reading. Tries to read the header from different legacy formats, and if successful, adjusts the project attributes according to the values in the header. Returns the open file if successful.

load(filename=None, try_resolve=True, quiet=False)

Load a project from file.

The loaded definitions will update the current project.

convert(filename=None)

Convert an old format project file.

The project file is read, and if successful, is immediately saved. By default, this will overwrite the original file. If a filename is specified, the converted data are saved to that file. In both cases, access is set to ‘wr’, so the tha saved data can be read back immediately.

uncompress(verbose=True)

Uncompress a compressed project file.

The project file is read, and if successful, is written back in uncompressed format. This allows to make conversions of the data inside.

delete()

Unrecoverably delete the project file.

24.2. Functions defined in module project

project.find_class(module, name)

Find a class whose name or module has changed