All objects and classes described here are located in Pyrite.Database module. The contents of that module are imported into the base package, so everything described in this chapter can be accessed directly from the Pyrite module as well.
A Database object represents an open database. In order to transparently support many different low-level database representations, a Database object is actually a wrapper around a lower-level object. The Database object provides the visible interface, while the lower level object handles the details of shuffling data in and out of the actual database.
Important: Not all back-end databases support all of the functions listed here. If you are writing code which is intended to work with many or all back-ends, you will have better results if you only use the most basic interfaces (len, __getitem__, append, etc.).
As more back-ends are developed, a complete set of properties will be defined so that your code can use the has_property function to determine exactly what a database is capable of doing.
It is expected that code supporting specific applications will provide a subclass of Database, which has been extended to generate and accept customized subclasses of Record, AppBlock, and so forth. (The base Database class has support for the simplest form of this behavior.)
Note: To save space in the following descriptions, the term "record object" will be used to refer to any object which is an instance of Pyrite.Record or Pyrite.Resource, or of a subclass of one of those two classes. The correct class to use depends on whether the database is a resource database; the interface to both is the same, except that where one expects Pyrite.Record objects, the other expects Pyrite.Resource objects. Whenever a call to the database object returns a block (record, resource, appinfo block, etc.), its named fields are unpacked automatically.
The database header information. This attribute is effectively read-only, since changes are not reflected in the actual database.
A subclass of Pyrite.Record, which is used to create objects for each record retrieved from the database.
A subclass of Pyrite.AppBlock, which is used to create the object returned when the database's appinfo block is retrieved.
True if the database holds resources, false if it holds records. This variable is read-only; changing it will do nothing but confuse Pyrite.
Return true if the database has the specified property.
Return the number of records in the database.
Return a particular record, indexed by position in the database. The return value is a record object.
Append a record object to the end of the database. Depending on the backend database implementation, any existing record with the same ID may be deleted automatically.
Return a new, empty record object, with the specified initial index, id, attributes, and category. This function may return a different class of object depending on its parameters, and some databases may accept extra parameters to this function to help make the right decision. For example, databases from the Doc plug-in accept a type parameter, which can be one of 'header', 'text', or 'bookmark'.
Return a new, empty Pyrite.AppBlock object, or an object of a subclass appropriate for the database.
Return a new, empty Pyrite.Resource object, or an object of a subclass appropriate for the database.
Get a record or resource by searching for a particular unique ID. Returns a record object with its named fields already unpacked.
Delete a record or resource. The first form (one parameter) is used on record databases, the second (two parameters) on resource databases.
Note: Unlike record deletion on the handheld, this actually removes the record right away, instead of marking it for deletion/archiving later!
Delete all records or resources from the database.
Return the database's appinfo block, as an instance of Pyrite.AppBlock or a subclass.
Set the database's appinfo block, using the supplied Pyrite.AppBlock object.
Move all records in one category to another.
Delete all records in the specified category.
Get a preference block, returning it as an instance of Pyrite.PrefBlock. The creator of the preference block is assumed to be the same as the creator of this database. If backup is true, look in the "saved preferences", otherwise look in the "unsaved preferences" for the requested preference.
Important: Pyrite's preference interface is likely to change in the near future.
Set a preference block from the supplied Pyrite.PrefBlock object.
Important: Pyrite's preference interface is likely to change in the near future.
Clear the "dirty" flags on all records and set the last sync time to the current time.
Purge all deleted and/or archived records from the database.
Reset the counter used by next_record and next_modified.
Return the next record in the specified category, as a record object. (But see the Category function for an alternative.)
Return the next modified record, as a record object. If category is not supplied or is equal to -1, this function returns modified records from the entire database, otherwise it looks only in the specified category. (See the ModifiedRecords function for an alternative.)
Return a list of ID values of the records in the database. If sort is true, sort them (the ID values, not the records).
Close the backend database. (It is normally not necessary to do this, as the backend database will be closed when the Python garbage collector deletes the Database object.)
Return a slice object supporting the __getitem__ method. This is mainly to support the use of a for loop to iterate over a range of records, without retrieving them all at once.
Return an iterator object which supports retrieval of records in the specified category. The functionality of the iterator object is quite limited: it supports the __getitem__ operation only, retrieving each record in sequence only once.
Returns an iterator object which supports retrieval of modified records, either in a specific category or in the entire database. The functionality of the iterator object is quite limited: it supports the __getitem__ operation only, retrieving each record in sequence only once.