Package schrodinger :: Module project :: Class Project

Class Project

             object --+    
                      |    
infra.mmobject.MmObject --+
                          |
                         Project

Class to handle Maestro Projects. This is largely a wrapper to the underlying C library which stores all the state information.

The Project class allows selection of rows in the project via various interfaces.

A Maestro project may be accessed from within a Maestro session which has it open via maestro.project_table_get().

A Maestro project may alternatively be accessed without Maestro running by specifying a the name of the project when creating a project object.

See the doc string for the module for more details.

Instance Methods

[hide private]

enable(self, option=None)
Enable the specified option.

disable(self, option=None)
Disable the specified option.

__init__(self, project_name='', project_handle=-1, manage=True, close_without_cleanup_dialog=False)
Construct a Project class object either by opening a project file or using a handle to an already opened project.

_delete(self)
A function to delete this object.

close(self)
Close the project immediately.

__repr__(self)
Return full string representation

__str__(self)
Return string representation

__int__(self)
Return mmproj handle.

__len__(self)
Return the number of entries (rows) in the project

setCloseWithoutCleanupDialog(self, close_without_cleanup_dialog)

ProjectRow

getRow(self, entry_id)
Retrieve a ProjectRow instance based on the entry ID.

__getitem__(self, entry)
Return project row object, ProjectRow, for the given entry ID.

bool

__contains__(self, entry)
Determine if the project contains the specified entry ID

__delitem__(self, entry_id)
Delete the project row for the given entry ID.

update(self)
If running in Maestro, update the project after a change as the user wants to see their changes in the PT.

findRowsMatching(self, prop, cmp_op, value)
Returns a list of ProjectRow entries for all rows matching the given criteria.

getSelectedRowTotal(self)
Return the total number of selected rows

selectRows(self, select_mode=1, *args, **keywords)
Select rows in the project.

_selectAdd(self, *args, **keywords)
Private method to add specified rows to the already selected rows

_selectByFunction(self, user_function, *args)
Private method to add rows to selection via user specified function.

_selectNone(self)
Private method to unselect all entry rows

_selectAll(self)
Private method to select all rows

_selectInvert(self)
Private method to invert all rows in the project

includeRows(self, entry_ids, exclude_others=True)
Include rows with the given entry IDs in the Workspace, while optionally excluding all other entries.

__iter__(self)
Return an iterator object

refreshTable(self)
Refresh the project table

getPropertyNames(self)
Return a list of the data names of usable properties in this project instance, including properties which were hidden.

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

list of str

getPropertyNamesForSelectedRows(self)
Return a set of data names of properties (including hidden ones) that are common to all selected entries in this project.

_getShortName(self)
Get the name of the project (without the path)

_getFullName(self)
Get the full name of the project (which includes the whole path)

getAdditionalDataDir(self)
Get the additional data directory of the project

_getAllRowsIterator(self)

_getSelectedRowsIterator(self)

_getIncludedRowsIterator(self)

_getGroups(self)

_getLastAddedEntry(self)

freeCachedEntries(self)
Frees all entries that are cached.

ProjectRow

importStructure(self, st, name=None, wsreplace=False, copy=True)
Create a new entry in the Project Table from structure <st> and return the ProjectRow object for the new entry.

importStructureFile(self, filename, wsreplace=True, creategroups='multiple')
Imports all structures from the specified file into the Project Table.

getPropertyPrecision(self, property_name)
Return the precision of the property.

bool

isColumnFixed(self, column)
Return whether the column is in fixed area of the Project Table.

int

getFixedColumnsCount(self, in_subset=True)
Return number of columns in fixed area.

Inherited from infra.mmobject.MmObject: __del__

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __subclasshook__

Static Methods

[hide private]

setDebug(state)
Enable or disable debug output.

_printDebug(*args)
Print debugging output if enabled

initialize(error_handler=None)
Initialize necessary mmlibs (which will also implicitly initialize all the dependent mmlibs)

terminate()
Terminate various mmlibs (which also implicitly terminates all the libraries they are dependent upon)

Class Variables

[hide private]

_instances = {}

_debug = False
hash(x)

Properties

[hide private]

shortname
Get the short project name (without the path)

fullname
Get the full name of the project (including the path)

all_rows
Iterator for all rows in the project using the visible project table order

selected_rows
Iterator for the selected rows using the visible project table order

included_rows
Iterator for all included rows.

groups
Get the entry groups in the project

last_added_entry
Return a ProjectRow instance for the last entry added to the project

Inherited from object: __class__

Method Details

[hide private]

setDebug(state)
Static Method

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

enable(self, option=None)

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(self, option=None)

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

init(self, project_name=`''`, project_handle=-1, manage=True, close_without_cleanup_dialog=False)
(Constructor)

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__

_delete(self)

A function to delete this object. Required for MmObject interface.

close(self)

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.

repr(self)
(Representation operator)

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__

str(self)
(Informal representation operator)

Return string representation

Overrides: object.__str__

int(self)

Return mmproj handle. Can be used with mmproj functions.

Overrides: infra.mmobject.MmObject.__int__

getRow(self, entry_id)

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.

getitem(self, entry)
(Indexing operator)

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.

contains(self, entry)
(In operator)

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.

delitem(self, entry_id)
(Index deletion operator)


Delete the project row for the given entry ID.

For example,
    del pt[10]

update(self)

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.

findRowsMatching(self, prop, cmp_op, value)

Returns a list of ProjectRow entries for all rows matching the given criteria.

cmp_op should be "<", "<=", ">", ">=", "==", "!="

selectRows(self, select_mode=1, *args, **keywords)


Select rows in the project.

@param select_mode: Selection mode.
    project.ADD - add rows to existing PT selection.
    project.REPLACE - replace current selection.
    project.INVERT - invert the PT selection.
    project.ALL - select all rows in the PT.
    project.NONE - deselect all rows in the PT.
    Examples:
      pt.selectRows(project.REPLACE, entry_ids=[1, 2, 3])
      pt.selectRows(project.ALL)
      pt.selectRows(project.NONE)
@type select_mode: int

@param entry_ids: List of entry IDs for the rows to select.
  Example:
     pt.selectRows(entry_ids=[1, 2, 3])
@type entry_ids: list of ints or list of str

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

@param rows: Project indices for the rows to select (deprecated).
    Values refer to the values of the ProjectRow.index property.
@param rows: tuple or list of ints.

@param function: Callback for determining whether a row should be
    selected or not (deprecated).
@type function: callable

_selectByFunction(self, user_function, *args)

Private method to add rows to selection via user specified function. See the 'function' section in the doc string of the selectRows() method for usage by client code.

_selectNone(self)


Private method to unselect all entry rows

The public API for de-selecting all rows is:
  Project.selectRows(NONE)

_selectAll(self)


Private method to select all rows

The public API for selecting all rows is:
  Project.selectRows(ALL)

_selectInvert(self)


Private method to invert all rows in the project

The public API for inverting row selection is:
  Project.selectRows(INVERT)

includeRows(self, entry_ids, exclude_others=True)

Include rows with the given entry IDs in the Workspace, while optionally excluding all other entries.

Parameters:

entry_ids (list of ints or str.) - List of Entry IDs to include.
exclude_others (bool) - Whether to also exclude previously included entries.

iter(self)

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.

refreshTable(self)

Refresh the project table

This is only usable from within Maestro.

getPropertyNames(self)

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.

getVisiblePropertyNames(self)

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

getPropertyNamesForSelectedRows(self)

Return a set of data names of properties (including hidden ones) that are common to all selected entries in this project.

Returns: list of str: List of property data names

freeCachedEntries(self)

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.

importStructure(self, st, name=None, wsreplace=False, copy=True)

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.

importStructureFile(self, filename, wsreplace=True, creategroups=`'multiple'`)

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.

getPropertyPrecision(self, property_name)

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.

isColumnFixed(self, column)

Return whether the column is in fixed area of the Project Table.

Parameters:

column (int) - Project column

Returns: bool

Whether the column is in the fixed area.

getFixedColumnsCount(self, in_subset=True)

Return number of columns in fixed area. This does not include always fixed columns (Row, Included, Stars, 2D Structure and Title).

Parameters:

column - Whether to return fixed columns count only for the columns in subset (True by default)
in_subset (bool)

Returns: int

Number of columns in the fixed area.

Property Details

[hide private]

shortname

Get the short project name (without the path)

Get Method:: _getShortName(self) - Get the name of the project (without the path)

fullname

Get the full name of the project (including the path)

Get Method:: _getFullName(self) - Get the full name of the project (which includes the whole path)

all_rows

Iterator for all rows in the project using the visible project table order

Get Method:: _getAllRowsIterator(self)

selected_rows

Iterator for the selected rows using the visible project table order

Get Method:: _getSelectedRowsIterator(self)

included_rows

Iterator for all included rows. No specific return order for the rows.

Get Method:: _getIncludedRowsIterator(self)

groups

Get the entry groups in the project

Get Method:: _getGroups(self)

last_added_entry

Return a ProjectRow instance for the last entry added to the project

Get Method:: _getLastAddedEntry(self)

Class Project

setDebug(state) Static Method

enable(self, option=None)

disable(self, option=None)

__init__(self, project_name='', project_handle=-1, manage=True, close_without_cleanup_dialog=False) (Constructor)

_delete(self)

close(self)

__repr__(self) (Representation operator)

__str__(self) (Informal representation operator)

__int__(self)

getRow(self, entry_id)

__getitem__(self, entry) (Indexing operator)

__contains__(self, entry) (In operator)

__delitem__(self, entry_id) (Index deletion operator)

update(self)

findRowsMatching(self, prop, cmp_op, value)

selectRows(self, select_mode=1, *args, **keywords)

_selectByFunction(self, user_function, *args)

_selectNone(self)

_selectAll(self)

_selectInvert(self)

includeRows(self, entry_ids, exclude_others=True)

__iter__(self)

refreshTable(self)

getPropertyNames(self)

getVisiblePropertyNames(self)

getPropertyNamesForSelectedRows(self)

freeCachedEntries(self)

importStructure(self, st, name=None, wsreplace=False, copy=True)

importStructureFile(self, filename, wsreplace=True, creategroups='multiple')

getPropertyPrecision(self, property_name)

isColumnFixed(self, column)

getFixedColumnsCount(self, in_subset=True)

shortname

fullname

all_rows

selected_rows

included_rows

groups

last_added_entry

setDebug(state)
Static Method

init(self, project_name=`''`, project_handle=-1, manage=True, close_without_cleanup_dialog=False)
(Constructor)

repr(self)
(Representation operator)

str(self)
(Informal representation operator)

int(self)

getitem(self, entry)
(Indexing operator)

contains(self, entry)
(In operator)

delitem(self, entry_id)
(Index deletion operator)

iter(self)

importStructureFile(self, filename, wsreplace=True, creategroups=`'multiple'`)