<!-- $Id: ref-databases.sgml,v 1.2 1999/05/28 06:39:27 rob Exp $ -->
<chapter id="ref-databases">
  <title>Databases</title>

  <para>
    All objects and classes described here are located in
    <classname/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 <classname/Pyrite/
    module as well.
  </para>
  
  <sect1 id="ref-databases-database">
    <title>Class: Database</title>

    <para>
      A <classname/Database/ object represents an open database.  In
      order to transparently support many different low-level database
      representations, a <classname/Database/ object is actually a
      wrapper around a lower-level object.  The <classname/Database/
      object provides the visible interface, while the lower level
      object handles the details of shuffling data in and out of the
      actual database.
    </para>
    
    <important>
      <para>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 (<function/len/,
	<function/__getitem__/, <function/append/, etc.).</para>

      <para>As more back-ends are developed, a complete set of
	properties will be defined so that your code can use the
	<function/has_property/ function to determine exactly what a
	database is capable of doing.</para>
    </important>

    <para>
      It is expected that code supporting specific applications will
      provide a subclass of <classname/Database/, which has been
      extended to generate and accept customized subclasses of
      <classname/Record/, <classname/AppBlock/, and so forth.  (The
      base <classname/Database/ class has support for the simplest
      form of this behavior.)
    </para>
    
    <note>
      <para>To save space in the following descriptions, the term
	"record object" will be used to refer to any object which is
	an instance of <classname/Pyrite.Record/ or
	<classname/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 <classname/Pyrite.Record/
	objects, the other expects <classname/Pyrite.Resource/
	objects.  Whenever a call to the database object returns a
	block (record, resource, appinfo block, etc.), its named
	fields are unpacked automatically.</para>
    </note>
    
    <sect2 id="ref-databases-database-attributes">
      <title>Attributes</title>
      
      <variablelist>
	<varlistentry>
	  <term><structfield/info/ (<type/dictionary/)</term>
	  <listitem>
	    <para>The database header information.  This attribute is
	      effectively read-only, since changes are not reflected
	      in the actual database.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><structfield/record_class/ (<type/class/)</term>
	  <listitem>
	    <para>A subclass of <classname/Pyrite.Record/, which is
	      used to create objects for each record retrieved from
	      the database.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><structfield/appblock_class/ (<type/class/)</term>
	  <listitem>
	    <para>A subclass of <classname/Pyrite.AppBlock/, which is
	      used to create the object returned when the database's
	      appinfo block is retrieved.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><structfield/is_resource/</term>
	  <listitem>
	    <para>True if the database holds resources, false if it
	      holds records.  This variable is read-only; changing it
	      will do nothing but confuse Pyrite.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
    
    <sect2 id="ref-databases-database-methods">
      <title>Methods</title>
      
      <variablelist>
	<varlistentry>
	  <term><function/has_property/ (<parameter/property/)</term>
	  <listitem>
	    <para>Return true if the database has the specified
	    property.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/__len__/</term>
	  <listitem>
	    <para>Return the number of records in the database.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/__getitem__/ (<parameter/index/)</term>
	  <listitem>
	    <para>Return a particular record, indexed by position in
	      the database.  The return value is a record
	      object.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/append/ (<parameter/record/)</term>
	  <listitem>
	    <para>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.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/new_record/
	    (<parameter/index/=0,
	    <parameter/id/=0,
	    <parameter/attributes/=0,
	    <parameter/category/=0,
	    *, **)
	  </term>
	  <listitem>
	    <para>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
	      <classname/Doc/ plug-in accept a <parameter/type/
	      parameter, which can be one of <literal/'header'/,
	      <literal/'text'/, or <literal/'bookmark'/.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/new_appblock/</term>
	  <listitem>
	    <para>Return a new, empty <classname/Pyrite.AppBlock/
	      object, or an object of a subclass appropriate for the
	      database.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/new_resource/
	    (<parameter/type/='    ', <parameter/id/=0)</term>
	  <listitem>
	    <para>Return a new, empty <classname/Pyrite.Resource/
	      object, or an object of a subclass appropriate for the
	      database.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><function/get_id/ (<parameter/id/)</term>
	  <listitem>
	    <para>Get a record or resource by searching for a
	      particular unique ID.  Returns a record object with its
	      named fields already unpacked.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/delete/ (<parameter/id/)</term>
	  <term><function/delete/ (<parameter/type/, <parameter/id/)</term>
	  <listitem>
	    <para>Delete a record or resource.  The first form (one
	      parameter) is used on record databases, the second (two
	      parameters) on resource databases.</para>
	    <note>
	      <para>Unlike record deletion on the handheld, this
		actually removes the record right away, instead of
		marking it for deletion/archiving later!</para>
	    </note>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/delete_all/</term>
	  <listitem>
	    <para>Delete all records or resources from the database.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/get_appblock/</term>
	  <listitem>
	    <para>Return the database's appinfo block, as an instance
	      of <classname/Pyrite.AppBlock/ or a subclass.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/set_appblock/ (<parameter/appblock/)</term>
	  <listitem>
	    <para>Set the database's appinfo block, using the supplied
	      <classname/Pyrite.AppBlock/ object.</para>
	  </listitem>
	</varlistentry>
	
<!--	<varlistentry>
	  <term><function/get_sortblock/</term>
	  <listitem>
	    <para>Return the database's sortinfo block, as an
	      instance of <classname/Pyrite.SortBlock/ or a
	      subclass.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/set_sortblock/ (<parameter/sortblock/)</term>
	  <listitem>
	    <para>Set the database's sortinfo block, using the
	      supplied <classname/Pyrite.SortBlock/ object.</para>
	  </listitem>
	</varlistentry>
-->	
	<varlistentry>
	  <term><function/category_move/ (<parameter/from/, <parameter/to/)</term>
	  <listitem>
	    <para>Move all records in one category to another.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/category_delete/ (<parameter/category/)</term>
	  <listitem>
	    <para>Delete all records in the specified category.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/get_preference/ (<parameter/id/, <parameter/backup/=1)</term>
	  <listitem>
	    <para>Get a preference block, returning it as an instance
	      of <classname/Pyrite.PrefBlock/.  The creator of the
	      preference block is assumed to be the same as the
	      creator of this database.  If <parameter/backup/ is
	      true, look in the "saved preferences", otherwise look in
	      the "unsaved preferences" for the requested
	      preference.</para>
	    
	    <important>
	      <para>Pyrite's preference interface is likely to change
		in the near future.</para>
	    </important>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/set_preference/ (<parameter/prefblock/)</term>
	  <listitem>
	    <para>Set a preference block from the supplied
	      <classname/Pyrite.PrefBlock/ object.</para>
	    <important>
	      <para>Pyrite's preference interface is likely to change
		in the near future.</para>
	    </important>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/reset_flags/</term>
	  <listitem>
	    <para>Clear the "dirty" flags on all records and set the
	      last sync time to the current time.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/purge_deleted/</term>
	  <listitem>
	    <para>Purge all deleted and/or archived records from the
	      database.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/next_reset/</term>
	  <listitem>
	    <para>Reset the counter used by <function/next_record/ and
	      <function/next_modified/.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/next_record/ (<parameter/category/)</term>
	  <listitem>
	    <para>Return the next record in the specified category, as
	      a record object.  (But see the <function/Category/
	      function for an alternative.)</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/next_modified/ (<parameter/category/=-1)</term>
	  <listitem>
	    <para>Return the next modified record, as a record
	      object.  If <parameter/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 <function/ModifiedRecords/
	      function for an alternative.)</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/ids/ (<parameter/sort/=0)</term>
	  <listitem>
	    <para>Return a list of ID values of the records in the
	      database.  If <parameter/sort/ is true, sort them (the
	      ID values, not the records).</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/close/</term>
	  <listitem>
	    <para>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.)</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/__getslice__/ (<parameter/low/,
	    <parameter/high/)</term>
	  <listitem>
	    <para>Return a slice object supporting the
	      <function/__getitem__/ method.  This is mainly to
	      support the use of a <literal/for/ loop to iterate over
	      a range of records, without retrieving them all at
	      once.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/Category/ (<parameter/category/)</term>
	  <listitem>
	    <para>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
	      <function/__getitem__/ operation only, retrieving each
	      record in sequence only once.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/ModifiedRecords/ (<parameter/category/=None)</term>
	  <listitem>
	    <para>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
	      <function/__getitem__/ operation only, retrieving each
	      record in sequence only once.</para>
	  </listitem>
	</varlistentry>	
      </variablelist>
    </sect2>
  </sect1>
</chapter>

<!--Local Variables: -->
<!--sgml-parent-document: ("prg.sgml" "chapter") -->
<!--sgml-doctype: "prg.sgml" -->
<!--End: -->