Class Project

Enable or disable debug output. Use False or True. Sets this for the class, i.e. affects all instances, current and future.

Enable the specified option. Currently only AUTOMATIC_CACHE_FREEING is available. This will cause any cached entries to be freed automatically after each iteration when using the all_rows iterator. Other iterators do not allow automatic cache freeing to be enabled.

Disable the specified option. Currently only AUTOMATIC_CACHE_FREEING is available. See enable() for details.

Construct a Project class object either by opening a project file or using a handle to an already opened project.

If a project name is given via project_name, then we open the named project. If a project handle for an already opened project is passed in (via the project_handle argument), then we use that. If neither or both are given, these are errors.

Passing in a project name causes manage=True. When a managed instance goes out of scope or is deleted garbage collection is performed. One side effect is that the project is closed.

Passing in a project handle causes manage=False. When a non-managed instance goes out of scope or is deleted the project is left open. This is desirable, for example, when you construct a python Project instance using the project handle of Maestro's currently opened project. This allows Maestro to continue working with the opened project after the python Project instance is gone. Otherwise, the project would be closed and Maestro left in an invalid state, thinking that the project was still open.

If close_without_cleanup_dialog is given True, then project cleanup dialog will not be shown when closing the project. In this case, it does not launch the project_cleanup as a separate process, but does the cleanup in-process(i.e. blocking) without showing the dialog. By default, close_without_cleanup_dialog is False, this will run the clean up process in separate process with cleanup dialog.

Overrides: object.__init__

Close the project immediately. This method is normally not needed and should only be called if garbage collection cannot be relied upon to close the project as normal. This method may be required in unittests to ensure the project is closed before the next test begins. Note that the project cleanup will occur in-process.

Return full string representation

Warning: you cannot create another project instance for a project which is currently open. That is, a project can only be opened by a single process at a time.

Overrides: object.__repr__

Return string representation

Overrides: object.__str__

Return mmproj handle. Can be used with mmproj functions.

Overrides: infra.mmobject.MmObject.__int__

Retrieve a ProjectRow instance based on the entry ID.

Parameters:

• entry_id (int or str) - is the entry ID of this project's entry. This is the internally assigned identifier that is invariant for the life of the project. The ID does not change even if other entries are deleted or the entries (rows) in the Project are sorted. Entry ID can be passed in as a string also (e.g. "1").

Returns: ProjectRow

ProjectRow if entry ID is valid Otherwise, returns None.

Return project row object, ProjectRow, for the given entry ID. Same as Project.getRow() except that it raises KeyError instead of returning None if the row does not exist.

The entry ID ('entry') can be specified as either an int or a str, and is used to look up the corresponding index into the project. Older versions used to allow look up by entry name and treated an 'entry' argument of type string as an entry name. This is no longer valid and will generate an exception - the unique identifiers in projects are now entry IDs not entry names.

If you find your memory usage becoming excessive, you may want to use freeCachedEntries(). See that method's docstring for more information.

Determine if the project contains the specified entry ID

Parameters:

• entry_id (int or str) - The entry ID to check the project for.

Returns: bool

True if the specified entry ID is present. False otherwise.

If running in Maestro, update the project after a change as the user wants to see their changes in the PT. Does not do anything if the manual_update attribute is set to True.

Select rows in the project. NOTE that rows must be specified
using ProjectRow.index, not Project Table row number or entry ID.

The allowed modes for "select_mode" are defined at the top of
this module and include adding rows to the
selection, replacing the current selection with the newly
selected rows,
selecting all rows or unselecting all rows (selecting none).
If ALL or NONE is specified, the keywords parameter is ignored.

keywords can be any one of the following:

- esl: This is an ESL definition.  Example to add to the
  selection rows that match the ESL:
  selectRows(ADD, esl="entry_re entry*")

- rows: This is a python tuple or list.  Example to add to the
  already selected rows the following internal project row indices:
  selectRows(ADD, rows = [1,5,9]). The values in this keyword
  refer to values of the index property of ProjectRow object,
  not the row number displayed in the Project Table.

- function: This is a function that returns True or False.  Example:
  Add to the already selected rows whatever the function, myfunc,
  chooses.  The signature of the function takes a Project,
  a Structure (or CT), a property_dict and some number of optional
  arguments.  Each entry is examined and if myfunc
  returns True it is selected.  If it returns False, then
  the entry is unselected.

  def myfunc(Project, Structure (or ct), property_dict, *args)
      your function definition here

  selectRows(ADD, function=myfunc)

Return an iterator object

Allows iteration over the selected entries.

To iterate over all entries use: 'for row in xrange(1, len(Project)+1)'

OBSOLETE. Use Project.selected_rows instead.

If you find your memory usage becoming excessive, you may want to use freeCachedEntries(). See that method's docstring for more information.

Refresh the project table

This is only usable from within Maestro.

Return a list of the data names of usable properties in this project instance, including properties which were hidden. There are some additional properties, like whether an entry is selected or included, which are not returned by this function.

Return a list of the data names of vislble properties in this project instance (hidden properties are not included).

@rtype = list of strings @return = list of names of the property columns that are currently displayed in the Project Table

Frees all entries that are cached.

Things like ProjectRow.getStructure(), ProjectRow.structure, ProjectRow.setStructure() will cause entries to be cached. Unless the cache is freed memory usage will grow and can become quite large (if, for example, you are iterating over and retrieving a large number of structures).

Note that on some operating systems any memory already allocated within a process is not returned to the system when it is freed. Instead it is simply marked as available to the process and only gets returned to the system when the process exits.

Given this you may not see your memory usage decrease after calling this method. However, by calling this method at carefully chosen points you can minimize your memory footprint.

If you free the cache, then the next time the above-mentioned methods/properties are invoked they will get and cache the data by fetching it from disk.

Create a new entry in the Project Table from structure <st> and return the ProjectRow object for the new entry.

In rare cases (when your Structure is managed by C code and use of it is no longer needed in python) using copy=False can give better performance. Doing so will make the Structure invalid for further use in your script.

Parameters:

• st (structure.Structure) - Structure to add to the Project Table.
• name (str) - Entry name to give to the new entry. By default, the value of the s_m_entry_name property will be used.
• wsreplace (bool) - whether to replace the Workspace with new entry. WARNING: if wsreplace is True, then any scratch entries in the Workspace will be disposed of without warning, which is not how Maestro would usually behave.
• copy (bool) - If set to False, will insert the actual input CT into the PT instead of copying it first.

Returns: ProjectRow

Return ProjectRow object for the new entry.

Imports all structures from the specified file into the Project Table. wsreplace - whether to replace the Workspace with the last structure in the specified file (default True). creategroups - which of the imported structures are to be grouped. Valid values are "multiple", "all", and "none".

This method is only available when used from within Maestro.

Return the precision of the property.

Parameters:

• property_name (string) - is the m2io data name (the long name) of the property for which you want the precision

Returns:

precision of the property as an integer

Throws a ValueError if the property name isn't valid.

shortname

Value:

property(_getShortName, None, None, "Get the short project name (witho ut the path)")

fullname

Value:

property(_getFullName, None, None, "Get the full name of the project ( including the path)")

all_rows

Value:

property(_getAllRowsIterator, doc= "Iterator for all rows in the proje ct using the visible project table order")

selected_rows

Value:

property(_getSelectedRowsIterator, doc= "Iterator for the selected row s using the visible project table order")

included_rows

Value:

property(_getIncludedRowsIterator, doc= "Iterator for all included row s. No specific return order for the rows.")

groups

Value:

property(_getGroups, None, None, doc= "Get the entry groups in the pro ject")

last_added_entry

Value:

property(_getLastAddedEntry, None, None, doc= "Return a ProjectRow ins tance for the last entry added to the project")