[z3-checkins] r42022 - z3/sqlos/trunk/src/sqlos
kobold at codespeak.net
kobold at codespeak.net
Fri Apr 13 12:31:32 CEST 2007
Author: kobold
Date: Fri Apr 13 12:31:32 2007
New Revision: 42022
Modified:
z3/sqlos/trunk/src/sqlos/README.txt
Log:
Updated documentation.
Modified: z3/sqlos/trunk/src/sqlos/README.txt
==============================================================================
--- z3/sqlos/trunk/src/sqlos/README.txt (original)
+++ z3/sqlos/trunk/src/sqlos/README.txt Fri Apr 13 12:31:32 2007
@@ -10,20 +10,19 @@
Introduction
------------
-``sqlos`` is a toolkit for using SQLObject_ (an Object Relational
-Mapper) inside Zope 3 or Zope 2. It tries to take care of many of the
-fiddly details that always seem to take a lot of time. The major ways
-it helps are:
+``sqlos`` is a toolkit for using SQLObject_ (an Object Relational Mapper)
+inside Zope 3 or Zope 2. It tries to take care of many of the fiddly details
+that always seem to take a lot of time. The major ways it helps are:
- + Integrates the Zope transaction system and SQLObject, allowing
- SQLObject to be used in lazyUpdate mode.
+ + Integrates the Zope transaction system and SQLObject, allowing SQLObject
+ to be used in lazyUpdate mode.
+ Uses Zope Database adapters in SQLObject.
+ Provide zcml configuration directives.
- + Provide ZODB persistent objects that can act as a "window" into
- the database.
+ + Provide ZODB persistent objects that can act as a "window" into the
+ database.
+ A testing infrastructure for testing SQLObject based applications.
@@ -31,19 +30,19 @@
.. _SQLObject: http://sqlobject.org
-This file describes how to use the ``sqlos`` package to use SQLObject
-together with Zope.
+This file describes how to use the ``sqlos`` package to use SQLObject together
+with Zope.
Zope 3 or Zope 2??
------------------
-For a quite few reasons, it is better and easier to use sqlos in Zope 3,
-but it can be used with Zope 2. Heavily leveraging the work by the Five
-project, a Zope 2 product (FiveSQLOS) was created to enable this.
+For a quite few reasons, it is better and easier to use sqlos in Zope 3, but it
+can be used with Zope 2. Heavily leveraging the work by the Five project, a
+Zope 2 product (FiveSQLOS) was created to enable this.
-The following table shows which sqlos version can and should be used
-with which Zope 2 and Zope 3 versions.
+The following table shows which sqlos version can and should be used with which
+Zope 2 and Zope 3 versions.
============ ======== =========
. Zope 2.9 Zope 2.10
@@ -85,45 +84,43 @@
Background
----------
-``sqlos`` was originally developed for the ``SIP`` project. You can
-find more information about SIP, including some screencasts on the
-`SIP project homepage`_.
+``sqlos`` was originally developed for the ``SIP`` project. You can find more
+information about SIP, including some screencasts on the `SIP project
+homepage`_.
.. _SIP project homepage: http://sampleinventory.sf.net
-Currently we're using a ``SQLObjectContainer`` object, that behaves
-like a normal folder, except that its contents doesn't come from the
-ZODB, but instead, they come from an SQL connection, through
-SQLObject.
-
-Given the pluggable nature of Zope 3, it was quite easy to integrate
-it with SQLObject. Originally, SQLObject had its own ``DBConnection``
-objects, that handle all the operations with the SQL backend, and even
-some other backends, like ``DBM``. These connection objects implement
-the ``DBAPI``, and work over a SQL cursor that is generated on the
-``makeConnection`` method of the DBConnection-based classes. Each
-database connection implements a given set of methods to generate
-queries and convert data types. To allow using a connection from Zope
-3 in SQLObject, we used an ``adapter``, which adapts a
+Currently we're using a ``SQLObjectContainer`` object, that behaves like a
+normal folder, except that its contents doesn't come from the ZODB, but
+instead, they come from an SQL connection, through SQLObject.
+
+Given the pluggable nature of Zope 3, it was quite easy to integrate it with
+SQLObject. Originally, SQLObject had its own ``DBConnection`` objects, that
+handle all the operations with the SQL backend, and even some other backends,
+like ``DBM``. These connection objects implement the ``DBAPI``, and work over a
+SQL cursor that is generated on the ``makeConnection`` method of the
+DBConnection-based classes. Each database connection implements a given set of
+methods to generate queries and convert data types. To allow using a connection
+from Zope 3 in SQLObject, we used an ``adapter``, which adapts a
``IZopeDatabaseAdapter`` utility service to the same interface that a
DBConnection object implements. This adapter just subclasses the
-``*Connection`` classes from SQLObject (eg: MySQLConnection),
-overriding the ``__init__`` and ``makeConnection`` method to
-initialize an instance variable with a reference to the ZopeConnection
-object and to return a ZopeCursor instance respectively.
-
-For the SQLObjectContainer class, we made it so it is possible to
-choose a set of class names that will be available inside that container.
-
-Based on this, the methods of the IContainer class were implemented so
-as all operations are done using SQLObject methods. For example, the
-``keys`` method does a select query and returns the available ids, the
-items method uses the SQLObject class ``select()`` method to generate one
-object for each row in the database and return them.
-
-At this point, we have an object that behaves just like a folder, and
-its flexible enough that you can make their objects come from any
-connection and any registered class you wish.
+``*Connection`` classes from SQLObject (eg: MySQLConnection), overriding the
+``__init__`` and ``makeConnection`` method to initialize an instance variable
+with a reference to the ZopeConnection object and to return a ZopeCursor
+instance respectively.
+
+For the SQLObjectContainer class, we made it so it is possible to choose a set
+of class names that will be available inside that container.
+
+Based on this, the methods of the IContainer class were implemented so as all
+operations are done using SQLObject methods. For example, the ``keys`` method
+does a select query and returns the available ids, the items method uses the
+SQLObject class ``select()`` method to generate one object for each row in the
+database and return them.
+
+At this point, we have an object that behaves just like a folder, and its
+flexible enough that you can make their objects come from any connection and
+any registered class you wish.
Installation
@@ -132,8 +129,8 @@
Zope3
_____
-You can easily install sqlos from the python cheeseshop using easy_install.
-To do this, you will have to first install setuptools_.
+You can easily install sqlos from the python cheeseshop using easy_install. To
+do this, you will have to first install setuptools_.
For example, this command will install the latest version of sqlos and it's
dependencies in ~/lib/python2.4/site-packages. Note that
@@ -145,8 +142,8 @@
copy the sqlos-\*.zcml package includes (in the includes directory in the
tarball) to the package-includes directory of your Zope instance.
-NOTE: the sqlos.ftesting-configure.zcml shouldn't be copied unless you want
- to test the sample application.
+NOTE: the sqlos.ftesting-configure.zcml shouldn't be copied unless you want to
+test the sample application.
Zope2
@@ -160,34 +157,36 @@
A Sample Application
--------------------
-The functional test setup for sqlos is really a sample application. You can
-run and play with this to see how sqlos works.
+The functional test setup for sqlos is really a sample application. You can run
+and play with this to see how sqlos works.
First install a Z3 database adapter, create a database, edit
-src/sqlos/ftesting.zcml to change the connection settings as
-described below in "Setting up a connection for SQLObject".
+src/sqlos/ftesting.zcml to change the connection settings as described below in
+"Setting up a connection for SQLObject".
-NOTE: This currently does not work with the default testing database
- (memory based SQLite) due to threading issues.
+NOTE: This currently does not work with the default testing database (memory
+based SQLite) due to threading issues. In order to run the testing application,
+change the rdb connection to point to a real file instead of an in-memory
+database within the file ftesting.zcml.
Then, from a checkout of sqlos run:
$ make run-sampleapp
-This should download Zope3 install sqlos and set up the functional
-test suite as a sample application. You can then log into zope3 on
-http://localhost:8080 with gandalf:123.
+This should download Zope3 install sqlos and set up the functional test suite
+as a sample application. You can then log into zope3 on http://localhost:8080
+with gandalf:123.
Try adding a "SQLObject MultiContainer" and then some people.
-NOTE: changing debug=1 in src/sqlos/adapter.py will cause the SQL
- executed to be printed on the terminal
+NOTE: changing debug=1 in src/sqlos/adapter.py will cause the SQL executed to
+be printed on the terminal
Setting up a connection for SQLObject
-------------------------------------
-This example is not complete yet (XXX), but should give you an idea::
+This is an example connection configuration with psycopgda::
<configure
xmlns='http://namespaces.zope.org/zope'
@@ -291,52 +290,46 @@
</configure>
-There are a few things that you need to know about this piece of
-ZCML:
+There are a few things that you need to know about this piece of ZCML:
-First, the ``<browser:editform />`` part is what does generate the
-automatic editform for the Person class. As you can see, we don't
-reference the class explicitly, but instead, we are saying that for
-the ``IPerson`` schema (a schema is just a flavor of interface), there
-will be an auto-generated editform called ``edit.html`` and it will be
-registered with the menu ``zmi_views``. ``<browser:editform />`` is a
-``directive``, which is also registered using ZCML and is created as
-part of the ``metaconfiguration`` of Zope 3. I'll not enter this into
-detail now. All you need to know is that this is a ``special view``
-that spits out an edit form in HTML based on the schema you defined.
-
-Second, the ``<content class="....">`` directive is used to register
-some information about the class, like what factory will be using for
-creating instances of it and what are the permissions needed to do
-stuff with this class. The <sqlos:factory> directive register the
-class as a IFactory utility and also registers the class as a
-IISQLObject utility.
+First, the ``<browser:editform />`` part is what does generate the automatic
+editform for the Person class. As you can see, we don't reference the class
+explicitly, but instead, we are saying that for the ``IPerson`` schema (a
+schema is just a flavor of interface), there will be an auto-generated editform
+called ``edit.html`` and it will be registered with the menu ``zmi_views``.
+``<browser:editform />`` is a ``directive``, which is also registered using
+ZCML and is created as part of the ``metaconfiguration`` of Zope 3. I'll not
+enter this into detail now. All you need to know is that this is a ``special
+view`` that spits out an edit form in HTML based on the schema you defined.
+
+Second, the ``<content class="....">`` directive is used to register some
+information about the class, like what factory will be using for creating
+instances of it and what are the permissions needed to do stuff with this
+class. The <sqlos:factory> directive register the class as a IFactory utility
+and also registers the class as a IISQLObject utility.
Let's take a look at the ``<require>`` directive:
-As you can see, there are 3 attributes on the directive. The
-``permission`` attribute specifies the permission that is
-required. The ``interface`` attribure specifies what is the interface
-that is protected by this permission. All the methods and properties
-defined on this interface are protected for reading by this
-permission. And last, the ``set_schema`` attribute specifies what is
-the interface which is going to be protected for *setting* attributes
-on the instances of this class. This is needed for the auto-generated
-form to work. If you don't specify a permission to protect
-``set_schema`` on the interface, you won`t be able to modify the
-instance.
+As you can see, there are 3 attributes on the directive. The ``permission``
+attribute specifies the permission that is required. The ``interface``
+attribure specifies what is the interface that is protected by this permission.
+All the methods and properties defined on this interface are protected for
+reading by this permission. And last, the ``set_schema`` attribute specifies
+what is the interface which is going to be protected for *setting* attributes
+on the instances of this class. This is needed for the auto-generated form to
+work. If you don't specify a permission to protect ``set_schema`` on the
+interface, you won`t be able to modify the instance.
Create A Container
------------------
-In addition to defining the content for Zope, you need a place for
-zope to locate the content. ``sqlos`` already provides nearly all of
-the implementation in the SQLObjectContainer class, however this
-ready-made container is constrained such that it can not contain any
-content. SQLObjectContainer must be extended to adjust this
-constraint and make the data in the database appear to be in this
-container.
+In addition to defining the content for Zope, you need a place for zope to
+locate the content. ``sqlos`` already provides nearly all of the
+implementation in the SQLObjectContainer class, however this ready-made
+container is constrained such that it can not contain any content.
+SQLObjectContainer must be extended to adjust this constraint and make the data
+in the database appear to be in this container.
As always, the first step is to declare the interface::
@@ -349,8 +342,8 @@
... pass
... __setitem__.precondition = ItemTypePrecondition( IPerson )
-The zope container infrastructure checks the __setitem__ precondition
-to determine what type of content the container is allowed to contain.
+The zope container infrastructure checks the __setitem__ precondition to
+determine what type of content the container is allowed to contain.
Next, define the implementation::
@@ -359,10 +352,10 @@
>>> class PersonContainer(SQLObjectContainer) :
... implements(IPersonContainer)
-All that needs to be done at this point is to connect an
-implementation with the interface. SQLObjectContainer provides all
-the (core) logic necessary. Later you may want to add custom methods
-and logic for convenience in manipulating the SQL-backed records.
+All that needs to be done at this point is to connect an implementation with
+the interface. SQLObjectContainer provides all the (core) logic necessary.
+Later you may want to add custom methods and logic for convenience in
+manipulating the SQL-backed records.
Finally, write the ZCML configuration to put all the pieces together::
@@ -403,27 +396,25 @@
Demonstration
-------------
-At this point you have a complete web interface for your database.
-It is time to test it and demonstrate that it does, indeed, work.
+At this point you have a complete web interface for your database. It is time
+to test it and demonstrate that it does, indeed, work.
-Start zope and point your browser to the ZMI. In the list of addable
-items on the left you should see our ``Person Container`` type. Add
-``Person Container`` to your site. When you view the container's
-@@contents.html view, you should see a simple listing of all the
-people in your database.
+Start zope and point your browser to the ZMI. In the list of addable items on
+the left you should see our ``Person Container`` type. Add ``Person
+Container`` to your site. When you view the container's @@contents.html view,
+you should see a simple listing of all the people in your database.
A Nice Touch (Title / DublinCore)
---------------------------------
-Although the base @@contents.html view is fully functional, it leaves
-plenty of usability to be desired. You will almost certainly want to
-replace the built-in container contents listing with a custom view
-tailored to the type of content your container handles. However, the
-built-in contents can trivially be given a nice touch that vastly
-improves the usability. The view queries the content for its
-DublinCore_ metadata, such as Title. We will provide this metadata
-with an adapter to adapt the IPerson interface to IZopeDublinCore.
+Although the base @@contents.html view is fully functional, it leaves plenty of
+usability to be desired. You will almost certainly want to replace the
+built-in container contents listing with a custom view tailored to the type of
+content your container handles. However, the built-in contents can trivially
+be given a nice touch that vastly improves the usability. The view queries the
+content for its DublinCore_ metadata, such as Title. We will provide this
+metadata with an adapter to adapt the IPerson interface to IZopeDublinCore.
The code is as follows::
More information about the z3-checkins
mailing list