Sophie: pyrite-0.9.3-4mdk i586

pyrite-0.9.3-4mdk.i586.rpm

<HTML
><HEAD
><TITLE
>Databases</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.42"><LINK
REL="HOME"
TITLE="Pyrite Programmers Guide"
HREF="book1.html"><LINK
REL="UP"
TITLE="Reference"
HREF="p45.html"><LINK
REL="PREVIOUS"
TITLE="Functions"
HREF="x345.html"><LINK
REL="NEXT"
TITLE="Stores"
HREF="c643.html"></HEAD
><BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Pyrite Programmers Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x345.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="c643.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="REF-DATABASES"
>Chapter 2. Databases</A
></H1
><P
>    All objects and classes described here are located in
    <TT
CLASS="CLASSNAME"
>Pyrite.Database</TT
> module.  The contents of that module
    are imported into the base package, so everything described in
    this chapter can be accessed directly from the <TT
CLASS="CLASSNAME"
>Pyrite</TT
>
    module as well.
  </P
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="REF-DATABASES-DATABASE"
>Class: Database</A
></H1
><P
>      A <TT
CLASS="CLASSNAME"
>Database</TT
> object represents an open database.  In
      order to transparently support many different low-level database
      representations, a <TT
CLASS="CLASSNAME"
>Database</TT
> object is actually a
      wrapper around a lower-level object.  The <TT
CLASS="CLASSNAME"
>Database</TT
>
      object provides the visible interface, while the lower level
      object handles the details of shuffling data in and out of the
      actual database.
    </P
><DIV
CLASS="IMPORTANT"
><BLOCKQUOTE
CLASS="IMPORTANT"
><P
><B
>Important: </B
>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 (<TT
CLASS="FUNCTION"
>len</TT
>,
	<TT
CLASS="FUNCTION"
>__getitem__</TT
>, <TT
CLASS="FUNCTION"
>append</TT
>, etc.).</P
><P
>As more back-ends are developed, a complete set of
	properties will be defined so that your code can use the
	<TT
CLASS="FUNCTION"
>has_property</TT
> function to determine exactly what a
	database is capable of doing.</P
></BLOCKQUOTE
></DIV
><P
>      It is expected that code supporting specific applications will
      provide a subclass of <TT
CLASS="CLASSNAME"
>Database</TT
>, which has been
      extended to generate and accept customized subclasses of
      <TT
CLASS="CLASSNAME"
>Record</TT
>, <TT
CLASS="CLASSNAME"
>AppBlock</TT
>, and so forth.  (The
      base <TT
CLASS="CLASSNAME"
>Database</TT
> class has support for the simplest
      form of this behavior.)
    </P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>To save space in the following descriptions, the term
	"record object" will be used to refer to any object which is
	an instance of <TT
CLASS="CLASSNAME"
>Pyrite.Record</TT
> or
	<TT
CLASS="CLASSNAME"
>Pyrite.Resource</TT
>, 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 <TT
CLASS="CLASSNAME"
>Pyrite.Record</TT
>
	objects, the other expects <TT
CLASS="CLASSNAME"
>Pyrite.Resource</TT
>
	objects.  Whenever a call to the database object returns a
	block (record, resource, appinfo block, etc.), its named
	fields are unpacked automatically.</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="REF-DATABASES-DATABASE-ATTRIBUTES"
>Attributes</A
></H2
><P
></P
><DL
><DT
><TT
CLASS="STRUCTFIELD"
><I
>info</I
></TT
> (<SPAN
CLASS="TYPE"
>dictionary</SPAN
>)</DT
><DD
><P
>The database header information.  This attribute is
	      effectively read-only, since changes are not reflected
	      in the actual database.</P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>record_class</I
></TT
> (<SPAN
CLASS="TYPE"
>class</SPAN
>)</DT
><DD
><P
>A subclass of <TT
CLASS="CLASSNAME"
>Pyrite.Record</TT
>, which is
	      used to create objects for each record retrieved from
	      the database.</P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>appblock_class</I
></TT
> (<SPAN
CLASS="TYPE"
>class</SPAN
>)</DT
><DD
><P
>A subclass of <TT
CLASS="CLASSNAME"
>Pyrite.AppBlock</TT
>, which is
	      used to create the object returned when the database's
	      appinfo block is retrieved.</P
></DD
><DT
><TT
CLASS="STRUCTFIELD"
><I
>is_resource</I
></TT
></DT
><DD
><P
>True if the database holds resources, false if it
	      holds records.  This variable is read-only; changing it
	      will do nothing but confuse Pyrite.</P
></DD
></DL
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="REF-DATABASES-DATABASE-METHODS"
>Methods</A
></H2
><P
></P
><DL
><DT
><TT
CLASS="FUNCTION"
>has_property</TT
> (<TT
CLASS="PARAMETER"
><I
>property</I
></TT
>)</DT
><DD
><P
>Return true if the database has the specified
	    property.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>__len__</TT
></DT
><DD
><P
>Return the number of records in the database.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>__getitem__</TT
> (<TT
CLASS="PARAMETER"
><I
>index</I
></TT
>)</DT
><DD
><P
>Return a particular record, indexed by position in
	      the database.  The return value is a record
	      object.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>append</TT
> (<TT
CLASS="PARAMETER"
><I
>record</I
></TT
>)</DT
><DD
><P
>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.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>new_record</TT
>
	    (<TT
CLASS="PARAMETER"
><I
>index</I
></TT
>=0,
	    <TT
CLASS="PARAMETER"
><I
>id</I
></TT
>=0,
	    <TT
CLASS="PARAMETER"
><I
>attributes</I
></TT
>=0,
	    <TT
CLASS="PARAMETER"
><I
>category</I
></TT
>=0,
	    *, **)</DT
><DD
><P
>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
	      <TT
CLASS="CLASSNAME"
>Doc</TT
> plug-in accept a <TT
CLASS="PARAMETER"
><I
>type</I
></TT
>
	      parameter, which can be one of <TT
CLASS="LITERAL"
>'header'</TT
>,
	      <TT
CLASS="LITERAL"
>'text'</TT
>, or <TT
CLASS="LITERAL"
>'bookmark'</TT
>.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>new_appblock</TT
></DT
><DD
><P
>Return a new, empty <TT
CLASS="CLASSNAME"
>Pyrite.AppBlock</TT
>
	      object, or an object of a subclass appropriate for the
	      database.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>new_resource</TT
>
	    (<TT
CLASS="PARAMETER"
><I
>type</I
></TT
>='    ', <TT
CLASS="PARAMETER"
><I
>id</I
></TT
>=0)</DT
><DD
><P
>Return a new, empty <TT
CLASS="CLASSNAME"
>Pyrite.Resource</TT
>
	      object, or an object of a subclass appropriate for the
	      database.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>get_id</TT
> (<TT
CLASS="PARAMETER"
><I
>id</I
></TT
>)</DT
><DD
><P
>Get a record or resource by searching for a
	      particular unique ID.  Returns a record object with its
	      named fields already unpacked.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>delete</TT
> (<TT
CLASS="PARAMETER"
><I
>id</I
></TT
>), <TT
CLASS="FUNCTION"
>delete</TT
> (<TT
CLASS="PARAMETER"
><I
>type</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>id</I
></TT
>)</DT
><DD
><P
>Delete a record or resource.  The first form (one
	      parameter) is used on record databases, the second (two
	      parameters) on resource databases.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>Unlike record deletion on the handheld, this
		actually removes the record right away, instead of
		marking it for deletion/archiving later!</P
></BLOCKQUOTE
></DIV
></DD
><DT
><TT
CLASS="FUNCTION"
>delete_all</TT
></DT
><DD
><P
>Delete all records or resources from the database.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>get_appblock</TT
></DT
><DD
><P
>Return the database's appinfo block, as an instance
	      of <TT
CLASS="CLASSNAME"
>Pyrite.AppBlock</TT
> or a subclass.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>set_appblock</TT
> (<TT
CLASS="PARAMETER"
><I
>appblock</I
></TT
>)</DT
><DD
><P
>Set the database's appinfo block, using the supplied
	      <TT
CLASS="CLASSNAME"
>Pyrite.AppBlock</TT
> object.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>category_move</TT
> (<TT
CLASS="PARAMETER"
><I
>from</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>to</I
></TT
>)</DT
><DD
><P
>Move all records in one category to another.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>category_delete</TT
> (<TT
CLASS="PARAMETER"
><I
>category</I
></TT
>)</DT
><DD
><P
>Delete all records in the specified category.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>get_preference</TT
> (<TT
CLASS="PARAMETER"
><I
>id</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>backup</I
></TT
>=1)</DT
><DD
><P
>Get a preference block, returning it as an instance
	      of <TT
CLASS="CLASSNAME"
>Pyrite.PrefBlock</TT
>.  The creator of the
	      preference block is assumed to be the same as the
	      creator of this database.  If <TT
CLASS="PARAMETER"
><I
>backup</I
></TT
> is
	      true, look in the "saved preferences", otherwise look in
	      the "unsaved preferences" for the requested
	      preference.</P
><DIV
CLASS="IMPORTANT"
><BLOCKQUOTE
CLASS="IMPORTANT"
><P
><B
>Important: </B
>Pyrite's preference interface is likely to change
		in the near future.</P
></BLOCKQUOTE
></DIV
></DD
><DT
><TT
CLASS="FUNCTION"
>set_preference</TT
> (<TT
CLASS="PARAMETER"
><I
>prefblock</I
></TT
>)</DT
><DD
><P
>Set a preference block from the supplied
	      <TT
CLASS="CLASSNAME"
>Pyrite.PrefBlock</TT
> object.</P
><DIV
CLASS="IMPORTANT"
><BLOCKQUOTE
CLASS="IMPORTANT"
><P
><B
>Important: </B
>Pyrite's preference interface is likely to change
		in the near future.</P
></BLOCKQUOTE
></DIV
></DD
><DT
><TT
CLASS="FUNCTION"
>reset_flags</TT
></DT
><DD
><P
>Clear the "dirty" flags on all records and set the
	      last sync time to the current time.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>purge_deleted</TT
></DT
><DD
><P
>Purge all deleted and/or archived records from the
	      database.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>next_reset</TT
></DT
><DD
><P
>Reset the counter used by <TT
CLASS="FUNCTION"
>next_record</TT
> and
	      <TT
CLASS="FUNCTION"
>next_modified</TT
>.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>next_record</TT
> (<TT
CLASS="PARAMETER"
><I
>category</I
></TT
>)</DT
><DD
><P
>Return the next record in the specified category, as
	      a record object.  (But see the <TT
CLASS="FUNCTION"
>Category</TT
>
	      function for an alternative.)</P
></DD
><DT
><TT
CLASS="FUNCTION"
>next_modified</TT
> (<TT
CLASS="PARAMETER"
><I
>category</I
></TT
>=-1)</DT
><DD
><P
>Return the next modified record, as a record
	      object.  If <TT
CLASS="PARAMETER"
><I
>category</I
></TT
> 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 <TT
CLASS="FUNCTION"
>ModifiedRecords</TT
>
	      function for an alternative.)</P
></DD
><DT
><TT
CLASS="FUNCTION"
>ids</TT
> (<TT
CLASS="PARAMETER"
><I
>sort</I
></TT
>=0)</DT
><DD
><P
>Return a list of ID values of the records in the
	      database.  If <TT
CLASS="PARAMETER"
><I
>sort</I
></TT
> is true, sort them (the
	      ID values, not the records).</P
></DD
><DT
><TT
CLASS="FUNCTION"
>close</TT
></DT
><DD
><P
>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.)</P
></DD
><DT
><TT
CLASS="FUNCTION"
>__getslice__</TT
> (<TT
CLASS="PARAMETER"
><I
>low</I
></TT
>,
	    <TT
CLASS="PARAMETER"
><I
>high</I
></TT
>)</DT
><DD
><P
>Return a slice object supporting the
	      <TT
CLASS="FUNCTION"
>__getitem__</TT
> method.  This is mainly to
	      support the use of a <TT
CLASS="LITERAL"
>for</TT
> loop to iterate over
	      a range of records, without retrieving them all at
	      once.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>Category</TT
> (<TT
CLASS="PARAMETER"
><I
>category</I
></TT
>)</DT
><DD
><P
>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
	      <TT
CLASS="FUNCTION"
>__getitem__</TT
> operation only, retrieving each
	      record in sequence only once.</P
></DD
><DT
><TT
CLASS="FUNCTION"
>ModifiedRecords</TT
> (<TT
CLASS="PARAMETER"
><I
>category</I
></TT
>=None)</DT
><DD
><P
>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
	      <TT
CLASS="FUNCTION"
>__getitem__</TT
> operation only, retrieving each
	      record in sequence only once.</P
></DD
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x345.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="c643.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Functions</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="p45.html"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Stores</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>