schrodinger.project

Module project

A module for accessing and modifying a Maestro Project. Projects may be accessed while within Maestro or without Maestro from a python script that imports this module. Usually when running from within Maestro the Project object would be returned via maestro.project_table_get() For a description of basic concepts that clarify the relationship between the Workspace and Maestro Projects as well as when and how changes in one affect the other, please see the Basic Concepts section in the python tutorial. The Scripting with Python tutorial is part of the General documentation and can be accessed from within Maestro's Help facility from the Manuals Index. Adding a copy of a structure to a project can be done using pt=maestro.project_table_get() pt.importStructure(ct) All row access is with respect to the order of rows in the project (which can differ from the order of rows in Maestro's Project Table since the table's rows can be sorted and rearranged). Column and Row indices start at 1. There are 3 ways to refer to rows: * Internal project index in mmproj, they are effectively indices into an array. These values are hidden from the user; avoid using them in scripts. * Project Table row number, as it appears in the left-most column of the PT in Maestro. This number can change when rows are deleted or the table is sorted. * Entry ID, which is unique for each row and never changes. These values are ints, but are often represented as strings, e.g. "1". Scratch entries will have non-int entry IDs, but are not stored in the project table. These are used in Maestro commands, ASLs, etc, and are visible to the user. Iterating over all rows in the project is done using an expression of the form pt=maestro.project_table_get() for row in pt.all_rows: # Now do something with row Iterating over selected rows in the project is done using an expression of the form: pt=maestro.project_table_get() for row in pt.selected_rows: # Now do something with row Accessing each row of the project table returns a ProjectRow object. Common operations on ProjectRow objects are to get (or set) a structure associated with that row: st = row.getStructure() # and then update row.setStructure(st) Also common is accessing the project data. This can be done either by the name of the project table column or the dataname (the latter being as it appears in Maestro format files): energy = row['Relative Potential Energy-MMFF94'] energy = row['r_mmod_Relative_Potential_Energy-MMFF94'] New columns and new properties for existing entries can be added to the project in a similar way. Note that the refreshTable() function is usually required to be called to show the results of additions to the project table. A project should be open by at most one process at any given time. It is an error to open a project currently opened by another process. Copyright Schrodinger LLC, All rights reserved.

Classes

[hide private]

PropertyDictionary
A dictionary of properties which can be indexed by dataname or column name (the name visible in the project).

EmptyIterator
Empty iterator.

ProjectRow
ProjectRow allows access to the structure and properties of an entry in the project.

_AllRowsIterator
Iterator for all rows in the project or group

_SelectedRowsIterator
Iterator for selected rows of the project or group

_IncludedRowsIterator
Iterator for included rows of the project or group

EntryGroup
A class which represents an entry group in the project table.

_EntryGroupIterator
Iterator for entry groups in the project

EntrySurface
A class for accessing the surfaces associated with a given entry.

_EntrySurfaceIterator
An iterator for the surfaces associated with a given entry.

Project
Class to handle Maestro Projects.

ProjectException

LockedProjectException

InvalidProjectException

ArchivedProjectException

InvalidProjectVersion

Functions

[hide private]

str

unzip_project(prjzip, newdir=None)
Unzip a prjzip.

schrodinger.project.Project, str, str

open_project(projdir, widget=None, autounlock=False, askunlock=True)
Open a project file, unlocking it if it is locked and the users chooses to.

delete_temp_project_directory(projdir, tempdir, tries=10, force=False)
Called AFTER closing a project to safely delete the temp directory it resides in.

Variables

[hide private]

maestro = None
hash(x)

_in_maestro = True
hash(x)

_module_name = "project"

INVALID_PROJECT_HANDLE = -1

AUTOMATIC_CACHE_FREEING = range(1)

Function Details

[hide private]

unzip_project(prjzip, newdir=None)

Unzip a prjzip. newdir specifies directory into which the new project will be created. It will be created with the same name as the old project.

Parameters:

prjzip (str) - path to zipped project
newdir (str) - destination directory of new unzipped project. This does not include the name of the prjdir. If None, unzip into temporary directory under SCHRODINGER_TMP.

Returns: str

path of unzipped project

open_project(projdir, widget=None, autounlock=False, askunlock=True)

Open a project file, unlocking it if it is locked and the users chooses to. open_project is a convenience function for constructing a Project() that provides information and options to users when projects are locked.

If projdir points to a zip archive of a project, we unzip it into a temp directory before opening it.

Note that this routine interacts with the user if the project is locked.

When closing a project that was extracted from a zip file, the project should first be closed, and then the temp directory deleted. Closing the project causes it to delete some of its own subdirectories, and this will create an error if the temp directory has already been deleted. First close the project and then use delete_temp_project_directory to do this safely.

Parameters:

projdir (str) - The path to a project
widget (QWidget or None) - The parent widget that any informational dialogs should be modal to. Use None if running without a GUI - any messages/input requests will go to the terminal. Note that using None when running under a PyQt gui will cause any questions to be asked in the terminal and "QCoreApplication::exec: The event loop is already running" to print to the terminal if the user is asked whether to unlock a file or not. The code runs correctly, however.
autounlock (bool) - If True, any project will be automatically unlocked and opened if it is locked, if False (default), the state of askunlock determines behavior.
Caution - use of autounlock=True can leave the project in an uncertain state if it is in use elsewhere, and should only be used if it is essential not to interact with the user.
askunlock (bool) - This parameter is overridden if autounlock is True. If askunlock is True (and autounlock is False), will ask the user if a locked project should be unlocked. If False, locked projects will not be opened.

Returns: schrodinger.project.Project, str, str

tuple of

schrodinger.project.Project object - or None if project could not be opened
path to the project - projdir if projdir was a path or a new directory if projdir was a zip archive,
path to the temp directory created to hold the project if projdir was a zip archive.

Note that a Project object of a valid but empty project evaluates to False, so the way to check if a valid project was returned is to check:

   if project is not None:

delete_temp_project_directory(projdir, tempdir, tries=10, force=False)

Called AFTER closing a project to safely delete the temp directory it resides in.

The project needs access to one of its subdirectories for a few ticks after it closes, so this routine waits until that directory disappears before deleting the entire directory tree. Otherwise, exceptions will result.

Note that after tries * 0.1 seconds, the routine will exit without removing the directory to avoid an infinite wait for a project that isn't closing properly. The default yields a maximum wait of 1 second.

Parameters:

projdir (str) - path to the project directory
tempdir (str) - path to the temp directory to be removed (this is normally the parent directory of the project directory
tries (int) - The number of times to check if the project has finished closing. Once tries attempts have been made, the routine exists without removing the temp directory unless force=True
force (bool) - If True, then the directory is removed even if the project has not yet closed properly - this can lead to exceptions being printed to the terminal, though no harm is actually done. If False (defualt), then the temp directory is left intact if the project hasn't closed after tries checks.