## PyORQ, version 0.1
## Python Object-Relational binding with Queries
##
## Copyright (c) 1994 Roeland Rengelink
##
## Permission is hereby granted, free of charge, to any person obtaining a
## copy of this software and associated documentation files (the "Software"),
## to deal in the Software without restriction, including without limitation
## the rights to use, copy, modify, merge, publish, distribute, sublicense,
## and/or sell copies of the Software, and to permit persons to whom the
## Software is furnished to do so, subject to the following conditions:
##
## The above copyright notice and this permission notice shall be included in
## all copies or substantial portions of the Software.
##
## THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
## IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
## FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
## AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
## LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
## FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
## DEALINGS IN THE SOFTWARE.

INTRODUCTION
============

PyORQ (Python Object Relational binding with Queries) implements persistence
for Python objects using a relational database (RDBMS, e.g. PostgreSQL MySQL)
for storage.

Object-relational mappings have been done before. They are relatively
straightforward: classes map to tables, attributes map to columns and
instances map to rows. However, fundamental to the object paradigm is that
identity maps to state, and not the other way around. Hence, to search
(i.e. map state to identity) one has to loop over the collection of all
objects and examine their state. If the objects are in a persistent store, the
objects need to be instantiated first which may be prohibitively expensive.

Traditionally there have been two solutions to this problem:

- Use persistent containers that use knowledge of the object's state to allow
  efficient searches (e.g. B-Trees). However, this essentially generalizes the
  notion of identity, and does not allow for arbitrary queries without
  instantiation.

- Use knowledge of the object-relational mapping to write SQL queries that
  return object identities, which can then be used to instantiate the results of
  the query. However, this means that the mechanism of the object-relational
  mapping becomes part of the interface, and requires the user to use SQL
  within his application.

The innovative aspect of PyORQ is the use of Python expressions to denote
queries which can be automatically translated into SQL and then be executed by
backend. This leverages the full search capabilities of RDBMSs in an
object-oriented programming environment. Contrary to other object-relational
Python-SQL mappings, the user needs no knowledge of SQL to search the
database.

FEATURES
========

PyORQ 0.1 is a technology demo. It's purpose is to demonstrate the possibility
to translate python expression into SQL queries. 

PyORQ 0.1 features:

o A notation for describing persistent objects, based on Python properties.
o Automatic creation of tables, based on the persistent object definition.
o A native Python notation to describe queries.
o Full support for Object Oriented programming (inheritance and encapsulation).
    - Persistent objects may refer to other persistent objects and queries 
      understand this.
    - References to objects of a particular type may also refer to
      subclasses of that type.
    - Queries on a type, may return subclasses of that type.
o Interfaces to several SQL backends:
    - PostgreSQL, based on pyPgSQL by Billy G. Allie.
    - MySQL, based on MySQL-Python by Andy Dustman.
    - SQLite, based on PySQLite by Michael Owens and Gerhard Haring
o Bugs (undoubtedly)

The biggest shortcomings of version 0.1 are:

o PyORQ does not check if the definition of a previously created persistent
  object still matches the table definition
  (Before modifying a persistent object, use db.drop_table() to remove the table).
o No support for multiple inheritance (Don't do it).
o Potential name-mangling problems are not checked
  (Assume that persistent attributes are case-insensitive, and you should be OK).
o Did I mention bugs?

HISTORY
=======

PyORQ is based on a similar approach to object-relational mapping that I
implemented together with Danny Boxhoorn for the astro-wise astronomical
data-reduction pipeline (http://www.astro-wise.org/).

INSTALLATION
============

To install PyORQ on your system simply execute 'python setup.py install'
from the directory that was created when you unpacked the PyORQ tar-ball.

DOCUMENTATION
=============

A user manual can be found in the directory docs (PDF-format). You can also
open docs/user_manual/index.html in your favorite browser.

More information can be found at the PyORQ site at

http://www.sourceforge.net/project/pyorq/

