[Checkins] SVN: megrok.rdf/trunk/src/megrok/rdf/README.txt Get rid
of misleading README.txt.
Martijn Faassen
faassen at infrae.com
Fri Aug 1 10:40:37 EDT 2008
Log message for revision 89154:
Get rid of misleading README.txt.
Changed:
U megrok.rdf/trunk/src/megrok/rdf/README.txt
-=-
Modified: megrok.rdf/trunk/src/megrok/rdf/README.txt
===================================================================
--- megrok.rdf/trunk/src/megrok/rdf/README.txt 2008-08-01 14:26:50 UTC (rev 89153)
+++ megrok.rdf/trunk/src/megrok/rdf/README.txt 2008-08-01 14:40:36 UTC (rev 89154)
@@ -2,201 +2,4 @@
megrok.rdf
==========
-The ``megrok.rdb`` package adds powerful relational database support
-to Grok, based on the powerful SQLAlchemy_ library. It makes available
-a new ``megrok.rdb.Model`` and ``megrok.rdb.Container`` which behave
-much like ones in core Grok, but are instead backed by a relational
-database.
-
-.. _SQLAlchemy: http://www.sqlalchemy.org
-
-In this document we will show you how to use ``megrok.rdb``.
-
-``megrok.rdb`` uses SQLAlchemy's ORM system, in particular its
-declarative extension almost directly. ``megrok.rdb`` just supplies a
-few special base classes and directives to make things easier, and a few
-other conveniences that help with integration with Grok.
-
-We first import import the SQLAlchemy bits we'll need later::
-
- >>> from sqlalchemy import Column, ForeignKey
- >>> from sqlalchemy.types import Integer, String
- >>> from sqlalchemy.orm import relation
-
-SQLAlchemy groups database schema information into a unit called
-``MetaData``. The schema can be reflected from the database schema, or
-can be created from a schema defined in Python. With ``megrok.rdb`` we
-typically do the latter, from within the content classes that they are
-mapped to using the ORM. We need to have some metadata to associate
-our content classes with.
-
-Let's set up the metadata object::
-
- >>> from megrok import rdb
- >>> metadata = rdb.MetaData()
-
-Now we'll set up a few content classes. We'll have a very simple
-structure where a (university) department has zero or more courses
-associated with it. First we'll define a container that can contain
-courses::
-
- >>> class Courses(rdb.Container):
- ... rdb.key('name')
-
-As you can see, we need to set up the attribute on which the key is
-based. We will use the ``name`` attribute, which we will define for
-the course later. Note that using the primary key attribute (such as
-``id`` in this example) is not a good idea if you expect the database
-to generate unique ids itself - the correct id will not be known yet
-before the object is commit to the database.
-
-Now we can set up the ``Department`` class. This has the ``courses``
-relation that links to its courses::
-
- >>> class Department(rdb.Model):
- ... rdb.metadata(metadata)
- ...
- ... id = Column('id', Integer, primary_key=True)
- ... name = Column('name', String(50))
- ...
- ... courses = relation('Course',
- ... backref='department',
- ... collection_class=Courses)
-
-This is very similar to the way you'd use
-``sqlalchemy.ext.declarative``, but there are a few differences::
-
-* we inherit from ``rdb.Model`` to make this behave like a Grok model.
-
-* We don't need to use ``__tablename__`` to set up the table name. By
- default the table name will be the class name, lowercased, but you
- can override this by using the ``rdb.tablename`` directive.
-
-* we need to make explicit the metadata object that is used. We do
- this in the tests, though in Grok applications it's enough to use
- the ``rdb.metadata`` directive on a module-level to have all rdb
- classes automatically associated with that metadata object.
-
-* we mark that the ``courses`` relation uses the ``Courses`` container
- class we have defined before. This is a normal SQLAlchemy feature,
- it's just we have to use it if we want to use Grok-style containers.
-
-We finish up our database definition by defining the ``Course``
-class::
-
- >>> class Course(rdb.Model):
- ... rdb.metadata(metadata)
- ...
- ... id = Column('id', Integer, primary_key=True)
- ... department_id = Column('department_id', Integer,
- ... ForeignKey('department.id'))
- ... name = Column('name', String(50))
-
-We see here that ``Course`` links back to the department it is in,
-using a foreign key.
-
-We need to actually grok these objects to have them fully set
-up Normally grok takes care of this automatically, but in this case
-we'll need to do it manually.
-
-First we grok this package's grokkers::
-
- >>> from grok.testing import grok
- >>> grok('megrok.rdb.meta')
-
-
-Before we grok stuff in the doctest, we need to make sure that
-``__file__`` exists on our "module"::
-
- >>> __file__ = 'foo'
-
-
-Now we can grok the components::
-
- >>> from grok.testing import grok_component
- >>> grok_component('Courses', Courses)
- True
- >>> grok_component('Department', Department)
- True
- >>> grok_component('Course', Course)
- True
-
-Once we have our metadata and object relational map defined, we need
-to have a database to actually put these in. While it is possible to
-set up a different database per Grok application, here we will use a
-single global database::
-
- >>> TEST_DSN = 'sqlite:///:memory:'
- >>> from z3c.saconfig import EngineFactory
- >>> from z3c.saconfig.interfaces import IEngineFactory
- >>> engine_factory = EngineFactory(TEST_DSN)
-
-We need to supply the engine factory as a utility. Grok can do this
-automatically for you using the module-level ``grok.global_utility``
-directive, like this::
-
- grok.global_utility(engine_factory, provides=IEngineFactory, direct=True)
-
-In the tests we'll use the component architecture directly::
-
- >>> from zope import component
- >>> component.provideUtility(engine_factory, provides=IEngineFactory)
-
-Now that we've set up an engine, we can set up the SQLAlchemy session
-utility::
-
- >>> from z3c.saconfig import GloballyScopedSession
- >>> from z3c.saconfig.interfaces import IScopedSession
- >>> scoped_session = GloballyScopedSession()
-
-With Grok, we'd register it like this::
-
- grok.global_utility(scoped_session, provides=IScopedSession, direct=True)
-
-But again we'll just register it directly for the tests::
-
- >>> component.provideUtility(scoped_session, provides=IScopedSession)
-
-We now need to create the tables we defined in our database::
-
- >>> engine = engine_factory()
- >>> metadata.create_all(engine)
-
-Now all that is out the way, we can use the ``rdb.Session`` object to make
-a connection to the database.
-
- >>> session = rdb.Session()
-
-Let's now create a database structure. We have a department of philosophy::
-
- >>> philosophy = Department(name="Philosophy")
-
-We need to manually add it to the database, as we haven't defined a
-particular ``departments`` container in our database::
-
- >>> session.add(philosophy)
-
-The philosophy department has a number of courses::
-
- >>> logic = Course(name="Logic")
- >>> ethics = Course(name="Ethics")
- >>> metaphysics = Course(name="Metaphysics")
- >>> session.add_all([logic, ethics, metaphysics])
-
-We'll add them to the philosophy department's courses container. Since
-we want to leave it up to the database what the key will be, we will
-use the special ``set`` method that ``rdb.Container`` objects have to
-add the objects::
-
- >>> philosophy.courses.set(logic)
- >>> philosophy.courses.set(ethics)
- >>> philosophy.courses.set(metaphysics)
-
-We can now verify that the courses are there::
-
- >>> for key, value in sorted(philosophy.courses.items()):
- ... print key, value.name, value.department.name
- Ethics Ethics Philosophy
- Logic Logic Philosophy
- Metaphysics Metaphysics Philosophy
-
+To be written.
More information about the Checkins
mailing list