[Checkins] SVN: Sandbox/adamg/ocql/trunk/src/ocql/ started developer documentations, adjusted code to better fit it
Adam Groszer
agroszer at gmail.com
Thu Aug 14 04:54:56 EDT 2008
Log message for revision 89823:
started developer documentations, adjusted code to better fit it
Changed:
A Sandbox/adamg/ocql/trunk/src/ocql/OVERVIEW.txt
A Sandbox/adamg/ocql/trunk/src/ocql/README.txt
A Sandbox/adamg/ocql/trunk/src/ocql/USAGE.txt
U Sandbox/adamg/ocql/trunk/src/ocql/database/configure.zcml
U Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/mentor.py
U Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/organization.py
U Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/project.py
U Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/student.py
U Sandbox/adamg/ocql/trunk/src/ocql/testing/utils.py
A Sandbox/adamg/ocql/trunk/src/ocql/tests/test_usage.py
-=-
Added: Sandbox/adamg/ocql/trunk/src/ocql/OVERVIEW.txt
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/OVERVIEW.txt (rev 0)
+++ Sandbox/adamg/ocql/trunk/src/ocql/OVERVIEW.txt 2008-08-14 08:54:55 UTC (rev 89823)
@@ -0,0 +1,16 @@
+
+OCQL - Overview
+================
+
+How parts of it fit together.
+
+
+
+The following documents help understanding the inner life of the engine:
+
+* Object Comprehension Query Language proposal
+ http://docs.google.com/Doc?docid=ddvh6xf9_141g9sqbr
+
+* D. Chan and P. Trinder. A Processing Framework for Object Comprehensions.
+ Information and Software Technology, 39(9):641--651, 1997.
+ http://citeseer.ist.psu.edu/384122.html
Property changes on: Sandbox/adamg/ocql/trunk/src/ocql/OVERVIEW.txt
___________________________________________________________________
Name: svn:keywords
+ Date Author Id Revision
Name: svn:eol-style
+ native
Added: Sandbox/adamg/ocql/trunk/src/ocql/README.txt
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/README.txt (rev 0)
+++ Sandbox/adamg/ocql/trunk/src/ocql/README.txt 2008-08-14 08:54:55 UTC (rev 89823)
@@ -0,0 +1,37 @@
+
+OCQL - Object Comprehension Query Language
+===========================================
+
+A declarative data extraction language that can be used with with Python / Zope
+and matches the language philosophy.
+
+For how to use OCQL in your own applications see USAGE.txt.
+
+In depth documentation is OVERVIEW.txt and can be found in each subfolder.
+
+For further text on the subject see:
+
+* Object Comprehension Query Language proposal
+ http://docs.google.com/Doc?docid=ddvh6xf9_141g9sqbr
+
+* OCQL presentation
+ http://docs.google.com/Presentation?docid=ddvh6xf9_146gp2npm
+
+In depth coverage, basics of the subject is described in the papers:
+
+* D.K.C. Chan. Object-Oriented Query Language Design and Processing.
+ Phd Thesis, Department of Computing Science, University of Glasgow 1994.
+ http://citeseer.ist.psu.edu/359340.html
+* D. Chan and P. Trinder. A Processing Framework for Object Comprehensions.
+ Information and Software Technology, 39(9):641--651, 1997.
+ http://citeseer.ist.psu.edu/384122.html
+
+Also the idea itself and most of the knowledge comes from the above papers.
+
+
+Status
+======
+
+Current project status is:
+
+#TODO!
\ No newline at end of file
Property changes on: Sandbox/adamg/ocql/trunk/src/ocql/README.txt
___________________________________________________________________
Name: svn:keywords
+ Date Author Id Revision
Name: svn:eol-style
+ native
Added: Sandbox/adamg/ocql/trunk/src/ocql/USAGE.txt
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/USAGE.txt (rev 0)
+++ Sandbox/adamg/ocql/trunk/src/ocql/USAGE.txt 2008-08-14 08:54:55 UTC (rev 89823)
@@ -0,0 +1,139 @@
+
+OCQL - Usage
+=============
+
+Using OCQL in your own application is quite straightforward.
+There are some basic requirements you have to follow.
+
+This file uses ZCML samples as most likely you'll use that.
+We need for that to work an import:
+
+ >>> from zope.configuration import xmlconfig
+
+Include OCQL in your configuration:
+(this registers all required adapters and stuff)
+
+ >>> context = xmlconfig.string("""
+ ... <configure
+ ... xmlns="http://namespaces.zope.org/zope">
+ ...
+ ... <include package="zope.component" file="meta.zcml" />
+ ... <include package="zope.app.component" file="meta.zcml" />
+ ... <include package="zope.security" file="meta.zcml" />
+ ... <include package="zope.app.security" file="meta.zcml" />
+ ... <include package="zope.app.security"/>
+ ...
+ ... <include package="ocql" />
+ ...
+ ... </configure>
+ ... """)
+
+We will use the sample data of OCQL to demonstrate the usage.
+There are 4 classes and interfaces:
+
+ >>> from ocql.testing.sample.interfaces import IOrganization
+ >>> from ocql.testing.sample.interfaces import IProject
+ >>> from ocql.testing.sample.interfaces import IStudent
+ >>> from ocql.testing.sample.interfaces import IMentor
+
+ >>> from ocql.testing.sample.organization import Organization
+ >>> from ocql.testing.sample.project import Project
+ >>> from ocql.testing.sample.student import Student
+ >>> from ocql.testing.sample.mentor import Mentor
+
+
+Declare all your classes interfaces:
+
+ >>> context = xmlconfig.string("""
+ ... <configure
+ ... xmlns="http://namespaces.zope.org/zope">
+ ...
+ ... <include package="zope.component" file="meta.zcml" />
+ ...
+ ... <interface interface="ocql.testing.sample.interfaces.IOrganization" />
+ ... <interface interface="ocql.testing.sample.interfaces.IProject" />
+ ... <interface interface="ocql.testing.sample.interfaces.IStudent" />
+ ... <interface interface="ocql.testing.sample.interfaces.IMentor" />
+ ...
+ ... </configure>
+ ... """)
+
+This would work too, but we want to keep it simple:
+<class class="something">
+ <implements interface="Isomething" />
+ ...
+ ...
+</class>
+
+As a bare minimum a catalog is needed with indexes for all your classes.
+We do that here with python code, you can achieve that with any means.
+Of course if you're using a live application and the catalog is stored in
+a database this catalog setup is required only once.
+
+ >>> from zope.app.intid import IntIds
+ >>> from zope.app.intid.interfaces import IIntIds
+ >>> from zope import interface, component
+ >>> from zope.app.keyreference.testing import SimpleKeyReference
+ >>> from zope.app.catalog.catalog import Catalog
+ >>> from zope.app.catalog.interfaces import ICatalog
+
+Some preconditions for the catalog and indexing to work:
+
+ >>> intids = IntIds()
+ >>> component.provideUtility(intids, IIntIds)
+ >>> component.provideAdapter(SimpleKeyReference)
+
+There is a special index in OCQL that holds the references to all instances
+of a defined class.
+
+ >>> from ocql.database.index import AllIndex
+
+Index name can be anything, OCQL will scan all available indexes.
+Make sure you do this for ALL your interfaces.
+
+ >>> cat = Catalog()
+ >>> cat['all_students'] = AllIndex(IStudent)
+ >>> cat['all_mentors'] = AllIndex(IMentor)
+ >>> cat['all_projects'] = AllIndex(IProject)
+ >>> cat['all_orgs'] = AllIndex(IOrganization)
+
+Provide the catalog as a utility.
+The catalog can have any name, OCQL will scan all available catalogs.
+
+ >>> component.provideUtility(cat, ICatalog, name='foo-catalog')
+
+We'll create some sample data now.
+All objects need to be registered with IntIds, and the catalog as usual:
+
+ >>> def make_sample(obj):
+ ... id = intids.register(obj)
+ ... cat.index_doc(id, obj)
+
+ >>> make_sample(Mentor(u"John Doe"))
+ >>> make_sample(Project(u"Save the world"))
+ >>> make_sample(Student(u"Charith", u"Sri Lanka"))
+ >>> make_sample(Student(u"Jane", u"USA"))
+ >>> make_sample(Student(u"Ann", u"Hungary"))
+ >>> make_sample(Organization(u"Zope.org"))
+
+That was it, off you go:
+
+ >>> from ocql.engine import OCQLEngine
+ >>> engine = OCQLEngine()
+
+Creating the runnable query takes time, so you better save it somewhere:
+
+ >>> run = engine.compile('set [ c in IStudent; c.country=="USA" | c.name]')
+
+Results can be retrieved by executing the runnable query:
+
+ >>> result = run.execute()
+ >>> result
+ set([u'Jane'])
+
+The OCQL language itself is quite rich, so providing all samples would fill a
+book itself.
+
+Here goes the dry syntax:
+
+#TODO!
Property changes on: Sandbox/adamg/ocql/trunk/src/ocql/USAGE.txt
___________________________________________________________________
Name: svn:keywords
+ Date Author Id Revision
Name: svn:eol-style
+ native
Modified: Sandbox/adamg/ocql/trunk/src/ocql/database/configure.zcml
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/database/configure.zcml 2008-08-14 07:19:45 UTC (rev 89822)
+++ Sandbox/adamg/ocql/trunk/src/ocql/database/configure.zcml 2008-08-14 08:54:55 UTC (rev 89823)
@@ -5,6 +5,17 @@
factory=".metadata.Metadata"
/>
+ <!--This declaration needs a lot of zope packages:-->
+ <class class=".index.AllIndex">
+ <require
+ permission="zope.ManageServices"
+ interface=".index.IAllIndex
+ zope.index.interfaces.IStatistics
+ "
+ set_schema=".index.IAllIndex"
+ />
+ </class>
+
</configure>
Modified: Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/mentor.py
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/mentor.py 2008-08-14 07:19:45 UTC (rev 89822)
+++ Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/mentor.py 2008-08-14 08:54:55 UTC (rev 89823)
@@ -28,5 +28,9 @@
project=None
+ def __init__(self, name=u'', project=None):
+ self.name = name
+ self.project = project
+
def __repr__(self):
return "%s <%s>" % (self.__class__.__name__, self.name)
Modified: Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/organization.py
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/organization.py 2008-08-14 07:19:45 UTC (rev 89822)
+++ Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/organization.py 2008-08-14 08:54:55 UTC (rev 89823)
@@ -29,5 +29,8 @@
# See google.interfaces.IOrganization
name = u''
+ def __init__(self, name=u''):
+ self.name = name
+
def __repr__(self):
return "%s <%s>" % (self.__class__.__name__, self.name)
Modified: Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/project.py
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/project.py 2008-08-14 07:19:45 UTC (rev 89822)
+++ Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/project.py 2008-08-14 08:54:55 UTC (rev 89823)
@@ -36,6 +36,11 @@
# See google.interfaces.IProject
name = u''
+ description = u''
+ def __init__(self, name=u'', description=u''):
+ self.name = name
+ self.description = description
+
def __repr__(self):
return "%s <%s>" % (self.__class__.__name__, self.name)
\ No newline at end of file
Modified: Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/student.py
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/student.py 2008-08-14 07:19:45 UTC (rev 89822)
+++ Sandbox/adamg/ocql/trunk/src/ocql/testing/sample/student.py 2008-08-14 08:54:55 UTC (rev 89823)
@@ -28,5 +28,9 @@
name = u''
country = None
+ def __init__(self, name=u'', country=None):
+ self.name = name
+ self.country = country
+
def __repr__(self):
return "%s <%s>" % (self.__class__.__name__, self.name)
Modified: Sandbox/adamg/ocql/trunk/src/ocql/testing/utils.py
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/testing/utils.py 2008-08-14 07:19:45 UTC (rev 89822)
+++ Sandbox/adamg/ocql/trunk/src/ocql/testing/utils.py 2008-08-14 08:54:55 UTC (rev 89823)
@@ -48,7 +48,14 @@
xmlns="http://namespaces.zope.org/zope">
<include package="zope.component" file="meta.zcml" />
+ <include package="zope.app.component" file="meta.zcml" />
+ <include package="zope.security" file="meta.zcml" />
+ <include package="zope.app.security" file="meta.zcml" />
+ <include package="zope.app.security"/>
+
+ <include package="zope.app.security"/>
+
<include package="ocql" />
</configure>
@@ -99,37 +106,27 @@
cat['all_projects'] = AllIndex(IProject)
cat['all_orgs'] = AllIndex(IOrganization)
- m1 = Mentor()
- m1.name = u"John Doe"
+ m1 = Mentor(u"John Doe")
id = intids.register(m1)
cat.index_doc(id, m1)
- p1 = Project()
- p1.name = u"Save the world"
- p1.description = u"test"
+ p1 = Project(u"Save the world", u'test')
id = intids.register(p1)
cat.index_doc(id, p1)
- s1 = Student()
- s1.name = u"Charith"
- s1.country = "Sri Lanka"
+ s1 = Student(u"Charith", u"Sri Lanka")
id = intids.register(s1)
cat.index_doc(id, s1)
- s2 = Student()
- s2.name = u"Jane"
- s2.country = "USA"
+ s2 = Student(u"Jane", u"USA")
id = intids.register(s2)
cat.index_doc(id, s2)
- s3 = Student()
- s3.name = u"Ann"
- s3.country = "Hungary"
+ s3 = Student(u"Ann", u"Hungary")
id = intids.register(s3)
cat.index_doc(id, s3)
- o1 = Organization()
- o1.name = u"Zope.org"
+ o1 = Organization(u"Zope.org")
id = intids.register(o1)
cat.index_doc(id, o1)
Added: Sandbox/adamg/ocql/trunk/src/ocql/tests/test_usage.py
===================================================================
--- Sandbox/adamg/ocql/trunk/src/ocql/tests/test_usage.py (rev 0)
+++ Sandbox/adamg/ocql/trunk/src/ocql/tests/test_usage.py 2008-08-14 08:54:55 UTC (rev 89823)
@@ -0,0 +1,25 @@
+# -*- coding: UTF-8 -*-
+
+"""Main
+
+$Id$
+"""
+
+import unittest
+import doctest
+from zope.testing.doctestunit import DocTestSuite,DocFileSuite
+
+from ocql.engine import OCQLEngine
+from ocql.testing.stubs import *
+
+from ocql.testing import utils
+
+def test_suite():
+ flags = doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS
+ return unittest.TestSuite((
+ DocFileSuite('../USAGE.txt',
+ optionflags=flags),
+ ))
+
+if __name__ == '__main__':
+ unittest.main(defaultTest='test_suite')
\ No newline at end of file
Property changes on: Sandbox/adamg/ocql/trunk/src/ocql/tests/test_usage.py
___________________________________________________________________
Name: svn:keywords
+ Date Author Id Revision
Name: svn:eol-style
+ native
More information about the Checkins
mailing list