Table of Contents

Class: Database qm/test/database.py

A Database stores tests, testsuites, and resources.

A Database has two primary functions:

  1. Test storage and retrieval.

    Every test has a unique name, called a "test id". When a new test is created, the Database is responsible for writing that test to permanent storage. Later, QMTest will request the test by providing the database with the test id. The database must retrieve the test from permanent storage.

    QMTest does not put any restrictions on how tests are stored. The default database implementation uses XML to store tests, but any storage format will do.

  2. Test enumeration.

    The Database can tell QMTest what tests are stored in the database. QMTest uses this information in its graphical user interface to show the user what tests exist.

A Database stores testsuites and resources in addition to tests. The names for tests, testsuites, and resources are all "labels". A label is a special kind of string that is designed to be easily convertible to a file name. For more information, see the qm.label module. The namespaces for tests, testsuites, and resources are all distinct. For example, it is OK to have a test with the same name as a testsuite.

Every Database is associated with a particular directory on the local machine. In most cases, the Database will store all the files it needs within this directory.

Every Database has an associated AttachmentStore. An AttachmentStore is responsible for storing the attachments associated with tests. See the module qm.attachment for more information about AttachmentStore.

Database is an abstract class.

You can extend QMTest by providing your own database implementation. One reason to do this is that you may want to store tests in a format different from the XML format that QMTest uses by default. For example, if you are testing a compiler, you might want to represent each test as a source file. Or, if you are testing a SQL database, you might want to represent each test as two files: one containing SQL commands to run the test, and one containing the output you expect.

Another reason to provide your own database implementation is that you might want to store tests on a remote location. For example, suppose you wanted to allow multiple users to access the same central test database. You could create a test database that created and retrieved tests by communicating with the central server.

To create your own database implementation, you must create a Python class derived (directly or indirectly) from Database. The documentation for each method of Database indicates whether you must override it in your database implementation. Some methods may be overridden, but do not need to be. You might want to override such a method to provide a more efficient implementation, but QMTest will work fine if you just use the default version.

If QMTest calls a method on a database and that method raises an exception that is not caught within the method itself, QMTest will catch the exception and continue processing. Therefore, methods here only have to handle exceptions themselves if that is necessary to maintain the integrity of the database.

A single Database may be accessed by multiple threads simultaneously. Therefore, you must take appropriate steps to ensure thread-safe access to shared data.

Base Classes   
qm.extension.Extension
Methods   
ExpandIds
GetAttachmentStore
GetClassPaths
GetConfigurationDirectory
GetIds
GetItem
GetLabelComponents
GetPath
GetResource
GetResourceClassNames
GetResourceIds
GetSubdirectories
GetSuite
GetSuiteIds
GetTest
GetTestClassNames
GetTestIds
HasResource
HasSuite
HasTest
IsModifiable
IsValidLabel
JoinLabels
RemoveExtension
SplitLabel
SplitLabelLeft
WriteExtension
__init__
  ExpandIds 
ExpandIds ( self,  ids )

Expand test and suite IDs into test IDs.

ids
A sequence of IDs of tests and suites, which may be mixed together.
returns
A pair test_ids, suite_ids. test_ids is a sequence of test IDs including all test IDs mentioned in ids plus all test IDs obtained from recursively expanding suites included in ids. suite_ids is the set of IDs of suites included directly and indirectly in ids.
raises
ValueError if an element in id is neither a test or suite ID. The exception argument is the erroneous element.
Exceptions   
ValueError, id
  GetAttachmentStore 
GetAttachmentStore ( self )

Returns the AttachmentStore associated with the database.

returns
The AttachmentStore containing the attachments associated with tests and resources in this database.

Derived classes may override this method.

  GetClassPaths 
GetClassPaths ( self )

Return directories to search for test and resource classes.

returns
A sequence of strings. Each string is a directory that should be searched to locate test and resource classes. The directories will be searched in the order they appear. QMTest will search other directories (like those in the QMTEST_CLASS_PATH environment variable) in addition to these directories.

For a given database, this method should always return the same value; callers are permitted to cache the value returned.

Derived classes may override this method. The sequence returned by the derived class need not be a superset of the value returned by the default implementation (but probably should be).

  GetConfigurationDirectory 
GetConfigurationDirectory ( self )

Return the directory containing configuration information.

returns
The directory containing configuration information for the database.

Derived classes must not override this method.

  GetIds 
GetIds (
        self,
        kind,
        directory="",
        scan_subdirs=1,
        )

Return all IDs of the indicated kind that begin with directory.

kind
One of the ITEM_KINDS.
directory
A label indicating the directory in which to begin the search.
scan_subdirs
True if (and only if) subdirectories of directory should be scanned.
returns
A list of all items of the indicated kind located within directory, as absolute labels.

Derived classes may override this method.

  GetItem 
GetItem (
        self,
        kind,
        item_id,
        )

Return the item of the indicated kind with indicated item_id.

kind
One of the ITEM_KINDS.
item_id
The name of the item.
returns
If kind is Database.TEST or Database.RESOURCE, returns a test descriptor or resource descriptor, respectively. If kind is Database.SUITE, returns a Suite.

Derived classes may override this method.

  GetLabelComponents 
GetLabelComponents ( self,  label )

Return all of the component directories of label.

label
A string naming an entity in the database.
returns
A list of strings. The first string is the first directory in 'label'; the last string is the basename.
  GetPath 
GetPath ( self )

Return the directory containing the database.

returns
A string containing the absolute path to the directory containing the database.

Derived classes must not override this method.

  GetResource 
GetResource ( self,  resource_id )

Return the ResourceDescriptor for the resource resouce_id.

resource_id
A label naming the resource.
returns
A ResourceDescriptor corresponding to resource_id.
raises
NoSuchResourceError if there is no resource in the database named resource_id.
Exceptions   
NoSuchResourceError( resource_id )
  GetResourceClassNames 
GetResourceClassNames ( self )

Return the kinds of resources that the database can store.

returns
A sequence of strings. Each string names a class, including the containing module. Only resources of these types can be stored in the database.

Derived classes may override this method. The default implementation allows all available resource classes, but the derived class may allow only a subset.

  GetResourceIds 
GetResourceIds (
        self,
        directory="",
        scan_subdirs=1,
        )

Return all resource IDs that begin with directory.

directory
A label indicating the directory in which to begin the search.
scan_subdirs
True if (and only if) subdirectories of directory should be scanned.
returns
A list of all resources located within directory, as absolute labels.
  GetSubdirectories 
GetSubdirectories ( self,  directory )

Return the immediate subdirectories of directory.

directory
A label indicating a directory in the database.
returns
A sequence of (relative) labels indictating the immediate subdirectories of directory. For example, if "a.b" and "a.c" are directories in the database, this method will return "b" and "c" given "a" as directory.

Derived classes may override this method.

  GetSuite 
GetSuite ( self,  suite_id )

Return the Suite for the suite named suite_id.

suite_id
A label naming the suite.
returns
An instance of Suite (or a derived class of Suite) corresponding to suite_id.
raises
NoSuchSuiteError if there is no test in the database named test_id.

All databases must have an implicit suite called '' that contains all tests in the database. More generally, for each directory in the database, there must be a corresponding suite that contains all tests in that directory and its subdirectories.

Exceptions   
NoSuchSuiteError( suite_id )
  GetSuiteIds 
GetSuiteIds (
        self,
        directory="",
        scan_subdirs=1,
        )

Return all suite IDs that begin with directory.

directory
A label indicating the directory in which to begin the search.
scan_subdirs
True if (and only if) subdirectories of directory should be scanned.
returns
A list of all suites located within directory, as absolute labels.
  GetTest 
GetTest ( self,  test_id )

Return the TestDescriptor for the test named test_id.

test_id
A label naming the test.
returns
A TestDescriptor corresponding to test_id.
raises
NoSuchTestError if there is no test in the database named test_id.
Exceptions   
NoSuchTestError( test_id )
  GetTestClassNames 
GetTestClassNames ( self )

Return the kinds of tests that the database can store.

returns
A sequence of strings. Each string names a class, including the containing module. Only classes of these types can be stored in the database.

Derived classes may override this method. The default implementation allows all available test classes, but the derived class may allow only a subset.

  GetTestIds 
GetTestIds (
        self,
        directory="",
        scan_subdirs=1,
        )

Return all test IDs that begin with directory.

directory
A label indicating the directory in which to begin the search.
scan_subdirs
True if (and only if) subdirectories of directory should be scanned.
returns
A list of all tests located within directory, as absolute labels.
  HasResource 
HasResource ( self,  resource_id )

Check whether or not the database has a resource named resource_id.

resource_id
A label naming the resource.
returns
True if and only if the database contains a resource named resource_id. If this function returns true, GetResource will usually succeed. However, they may be circumstances where HasResource returns true and GetResource does not succeed. For example, someone might remove a critical file from the database between the time that HasResource is called and the time that GetResource is called.

Derived classes may override this method.

  HasSuite 
HasSuite ( self,  suite_id )

Check whether or not the database has a suite named suite_id.

suite_id
A label naming the suite.
returns
True if and only if the database contains a suite named suite_id. If this function returns true, GetSuite will usually succeed. However, they may be circumstances where HasSuite returns true and GetSuite does not succeed. For example, someone might remove a critical file from the database between the time that HasSuite is called and the time that GetSuite is called.

All databases must have an implicit suite called "" that contains all tests in the database. More generally, for each directory in the database, there must be a corresponding suite that contains all tests in that directory and its subdirectories.

Derived classes may override this method.

  HasTest 
HasTest ( self,  test_id )

Check whether or not the database has a test named test_id.

test_id
A label naming the test.
returns
True if and only if the database contains a test named test_id. If this function returns true, GetTest will usually succeed. However, they may be circumstances where HasTest returns true and GetTest does not succeed. For example, someone might remove a critical file from the database between the time that HasTest is called and the time that GetTest is called.

Derived classes may override this method.

  IsModifiable 
IsModifiable ( self )

Returns true iff this database is modifiable.

returns
True iff this database is modifiable. If the database is modifiable, it supports operatings like Write that make changes to the structure of the databaes itself. Otherwise, the contents of the database may be viewed, but not modified.
  IsValidLabel 
IsValidLabel (
        self,
        label,
        is_component=1,
        )

Return true if label is valid.

label
A string that is being considered as a label.
is_component
True if the string being tested is just a single component of a label path.
returns
True if label is a valid name for entities in this database.
  JoinLabels 
JoinLabels ( self,  *labels )

Join the labels together.

labels
A sequence of strings corresponding to label components.
returns
A string containing the complete label.
  RemoveExtension 
RemoveExtension (
        self,
        id,
        kind,
        )

Remove the extension id from the database.

id
A label for the Extension instance stored in the database.
kind
The kind of Extension stored with the given id. Some databases store different kinds of Extension in different namespaces so that it is possible for there to be more than one Extension with the same id in a single database.
Exceptions   
NotImplementedError
  SplitLabel 
SplitLabel ( self,  label )

Split the label into a pair (directory, basename).

returns
A pair of strings (directory, basename).
  SplitLabelLeft 
SplitLabelLeft ( self,  label )

Split the label into a pair (parent, subpath). This is the same operation as SplitLabel, except the split occurs at the leftmost separator, not the rightmost, and a single-component label comes back in the parent slot.

returns
A pair of strings (parent, subpath).

  WriteExtension 
WriteExtension (
        self,
        id,
        extension,
        )

Store extension in the database, using the name id.

id
A label for the extension.
extension
An instance of Extension.

The extension is stored in the database. If there is a previous item in the database with the same id', it is removed and replaced with extension. Some databases may not be able to store all Extension instances; those database must throw an exception when an attempt is made to store such an extension.

Exceptions   
NotImplementedError
  __init__ 
__init__ (
        self,
        path,
        arguments,
        )

Construct a Database.

path
A string containing the absolute path to the directory containing the database.
arguments
A dictionary mapping attribute names to values.

Derived classes must call this method from their own __init__ methods. Every derived class must have an __init__ method that takes the path to the directory containing the database as its only argument. The path provided to the derived class __init__ function will always be an absolute path.


Table of Contents

This document was automatically generated on Mon Jan 3 09:42:29 2005 by HappyDoc version 2.1