Getting Started

The Python API runs on your 3.x installation of Python, you can grab it from here if you need to install it.

Once you have Python installed you need to tell it where the Understand module is. The easiest way to do that is to add/modify the PYTHONPATH environment variable to include the module location, which is SciTools/bin/<System>/python. Also if you did not add Understand to the Path variable during installation, you will need to add the SciTools/bin/<System> directory to PATH.

Finally, to use the API you will need to put ‘import Understand’ in your script.

Documentation

The most up-to-date documentation will ship with Understand and can be accessed from the Python Console with:
   import understand
  help (understand)
A more readable version can be obtained with the python ‘pydoc’ command, which can generate an html version of the documentation. We also try to keep a current version of the Python documentation on the Manuals page.

Sample Scripts

The documentation includes some samples. More detailed example scripts are shipped with Understand in the SciTools/scripts/python folder.

Happy Scripting!

We are also in the process of adding Snapshot support for the Perl API for build 476. Now you can access historical versions of the code through your scripts as well. For example you can compare versions of files or write a script to compare metrics between versions.

What does this mean to you as an Understand script user?
In addition to the new features, the main side effect might be that some scripts might no longer work.

If any of your scripts stop working, review this list of incompatabilites in the Perl delta document. You can also make sure the scripts are still valid syntax by running maintain_uperl -c myscipt.pl.

The new snapshot changes modify the API in a few different ways:

• Db::snapshots() to get a list of snapshots for the db.
• $snapshot->name() to get the name of a snapshot and
• $snapshot->open() to open the snapshot and return a $db variable that represents the snapshot.
• The $db object is now “live”. It never used to be and it was never important that a script pass around and use the correct object. It is now critical.
• Entity objects carry with them knowledge of the database/snapshot they belong to. Multiple databases/snapshots can be open and you can have entities from them all at once.
• Any scripts which used entity ids $ent->id() as keys in hashes must be updated – the $ent->id is no longer unique across snapshots and multiple databases
  • At the beginning of the script add:   use Tie::RefHash;
  • declare the hash with:  tie my %my_hash, ‘Tie::RefHash’;
  • use the actual entity object as the key $my_hash{$ent}, not the dereference of the entity $my_hash{$ent->id}.
  • Don’t use Understand::ent->new($id) to reconstruct an Ent object from the id.

If you run into any problems that you need help with, feel free to post a question on the scripting forum, or shoot us an email at support@scitools.com

UPDATE- We found some issues with the above approach to $ent->id and changed it with build 477. Using a Tie::RefHash for entities does not work as intended and is no longer recommended. We added a new call $db->ent_from_id($id), to reconstruct entity objects from ids.  To use entities as hash keys without later retrieving the entities from keys, it is sufficient to simply use $ent for the key. To later retrieve an entity from a key, instead, use the entity id as the key ($ent->id()), and retrieve the entity from the key with $db->ent_from_id($key). Note, it is not possible to safely store entities from different db’s into the same hash using this technique, since id’s are not unique across multiple open db’s.