[Checkins] SVN: zc.relation/trunk/ more doc tweaks
Gary Poster
gary at zope.com
Wed Apr 23 11:49:07 EDT 2008
Log message for revision 85655:
more doc tweaks
Changed:
_U zc.relation/trunk/
U zc.relation/trunk/setup.py
U zc.relation/trunk/src/zc/relation/CHANGES.txt
U zc.relation/trunk/src/zc/relation/README.txt
U zc.relation/trunk/src/zc/relation/searchindex.txt
-=-
Property changes on: zc.relation/trunk
___________________________________________________________________
Name: svn:ignore
- develop-eggs
bin
parts
.installed.cfg
build
dist
eggs
+ develop-eggs
bin
parts
.installed.cfg
build
dist
eggs
TEST_THIS_REST_BEFORE_REGISTERING.txt
Modified: zc.relation/trunk/setup.py
===================================================================
--- zc.relation/trunk/setup.py 2008-04-23 15:23:50 UTC (rev 85654)
+++ zc.relation/trunk/setup.py 2008-04-23 15:49:06 UTC (rev 85655)
@@ -1,8 +1,17 @@
from setuptools import setup, find_packages
+
+long_description = (
+ open('src/zc/relation/README.txt').read() + "\n" +
+ open('src/zc/relation/CHANGES.txt').read() + "\n")
+
+f = open('TEST_THIS_REST_BEFORE_REGISTERING.txt', 'w')
+f.write(long_description)
+f.close()
+
setup(
name="zc.relation",
- version="1.0a1",
+ version="1.0b1",
packages=find_packages('src'),
include_package_data=True,
package_dir= {'':'src'},
@@ -13,10 +22,7 @@
author='Zope Project',
author_email='zope3-dev at zope.org',
description=open("README.txt").read(),
- long_description=(
- open('src/zc/relation/CHANGES.txt').read() +
- '\n========\nOverview\n========\n\n' +
- open("src/zc/relation/README.txt").read()),
+ long_description=long_description,
license='ZPL 2.1',
keywords="zope zope3",
install_requires=[
Modified: zc.relation/trunk/src/zc/relation/CHANGES.txt
===================================================================
--- zc.relation/trunk/src/zc/relation/CHANGES.txt 2008-04-23 15:23:50 UTC (rev 85654)
+++ zc.relation/trunk/src/zc/relation/CHANGES.txt 2008-04-23 15:49:06 UTC (rev 85655)
@@ -2,16 +2,9 @@
Changes
=======
-1.0
-===
+1.0 (2008-04-23)
+================
-NOTE: The following is science fiction in the zc.relationship support so far.
-The change is upcoming and will be part of zc.relationship 2.0 (which is in
-fact intended to be essentially-to-completely backward compatible with
-zc.relationship 1.x).
-
-(dev version; supports Zope 3.4/Zope 2.11/ZODB 3.8)
-
This is the initial release of the zc.relation package. However, it
represents a refactoring of another package, zc.relationship. This
package contains only a modified version of the relation(ship) index,
@@ -26,12 +19,12 @@
If you would like to switch a legacy zc.relationship index to a
zc.relation catalog, try this trick in your generations script.
-Assuming the old index is `old`, the following line should create
+Assuming the old index is ``old``, the following line should create
a new zc.relation catalog with your legacy data:
>>> new = old.copy(zc.relation.Catalog)
-Why is the same basic data structure called a catalog now? Because I
+Why is the same basic data structure called a catalog now? Because we
exposed the ability to mutate the data structure, and what you are really
adding and removing are indexes. It didn't make sense to put an index in
an index, but it does make sense to put an index in a catalog. Thus, a
@@ -45,38 +38,40 @@
Incompatibilities with zc.relationship 1.x index
------------------------------------------------
-The two big changes are that method names now refer to `Relation` rather
-than `Relationship`; and the catalog is instantiated slightly differently
+The two big changes are that method names now refer to ``Relation`` rather
+than ``Relationship``; and the catalog is instantiated slightly differently
from the index. A few other changes are worth your attention. The
following list attempts to highlight all incompatibilities.
:Big incompatibilities:
- - `findRelationshipTokenSet` and `findValueTokenSet` are renamed, with
- some slightly different semantics, as `getRelationTokens` and
- `getValueTokens`. The exact same result as
- `findRelationTokenSet(query)` can be obtained with
- `findRelationTokens(query, 1)` (where 1 is maxDepth). The same
- result as `findValueTokenSet(reltoken, name)` can be obtained with
- `findValueTokens(name, {None: reltoken}, 1)`.
+ - ``findRelationshipTokenSet`` and ``findValueTokenSet`` are renamed, with
+ some slightly different semantics, as ``getRelationTokens`` and
+ ``getValueTokens``. The exact same result as
+ ``findRelationTokenSet(query)`` can be obtained with
+ ``findRelationTokens(query, 1)`` (where 1 is maxDepth). The same
+ result as ``findValueTokenSet(reltoken, name)`` can be obtained with
+ ``findValueTokens(name, {zc.relation.RELATION: reltoken}, 1)``.
- - `findRelations` replaces `findRelatonships`. The new method will use
+ - ``findRelations`` replaces ``findRelatonships``. The new method will use
the defaultTransitiveQueriesFactory if it is set and maxDepth is not 1.
- It shares the call signature of `findRelationChains`.
+ It shares the call signature of ``findRelationChains``.
- - `isLinked` is now `canFind`.
+ - ``isLinked`` is now ``canFind``.
- The catalog instantiation arguments have changed from the old index.
- * `loadRel` and `dumpRel` are now required arguments for instantiation.
+ * ``load`` and ``dump`` (formerly ``loadRel`` and ``dumpRel``,
+ respectively) are now required arguments for instantiation.
- * The only other optional arguments are relFamily and family.
- Specify what elements to index with `addValueIndex`
+ * The only other optional arguments are ``btree`` (was ``relFamily``) and
+ ``family``. You now specify what elements to index with
+ ``addValueIndex``
- * Note also that `addValueIndex` defaults to no load and dump function,
+ * Note also that ``addValueIndex`` defaults to no load and dump function,
unlike the old instantiation options.
- - query factories are different. See IQueryFactory in the interfaces.
+ - query factories are different. See ``IQueryFactory`` in the interfaces.
* they first get (query, catalog, cache) and then return a getQueries
callable that gets relchains and yields queries; OR None if they
@@ -98,7 +93,7 @@
:Small:
- - `deactivateSets` is no longer an instantiation option (it was broken
+ - ``deactivateSets`` is no longer an instantiation option (it was broken
because of a ZODB bug anyway, as had been described in the
documentation).
@@ -129,14 +124,14 @@
- The catalog supports specifying indexed values by passing callables rather
than interface elements (which are also still supported).
-- `findRelations` and new method `findRelationTokens` can find
- relations transitively and intransitively. `findRelationTokens`
+- ``findRelations`` and new method ``findRelationTokens`` can find
+ relations transitively and intransitively. ``findRelationTokens``
when used intransitively repeats the legacy zc.relationship index
- behavior of `findRelationTokenSet`.
- (`findRelationTokenSet` remains in the API, not deprecated, a companion
- to `findValueTokenSet`.)
+ behavior of ``findRelationTokenSet``.
+ (``findRelationTokenSet`` remains in the API, not deprecated, a companion
+ to ``findValueTokenSet``.)
-- in findValues and findValueTokens, `query` argument is now optional. If
+- in findValues and findValueTokens, ``query`` argument is now optional. If
the query evaluates to False in a boolean context, all values, or value
tokens, are returned. Value tokens are explicitly returned using the
underlying BTree storage. This can then be used directly for other BTree
@@ -151,4 +146,11 @@
- Listeners allow objects to listen to messages from the catalog (which can
be used directly or, for instance, to fire off events).
-- You can provide
+- You can search for relations, using a key of zc.relation.RELATION...which is
+ really an alias for None. Sorry. But hey, use the constant! I think it is
+ more readable.
+
+- tokenizeQuery (and resolveQuery) now accept keyword arguments as an
+ alternative to a normal dict query. This can make constructing the query
+ a bit more attractive (i.e., ``query = catalog.tokenizeQuery;
+ res = catalog.findValues('object', query(subject=joe, predicate=OWNS))``).
\ No newline at end of file
Modified: zc.relation/trunk/src/zc/relation/README.txt
===================================================================
--- zc.relation/trunk/src/zc/relation/README.txt 2008-04-23 15:23:50 UTC (rev 85654)
+++ zc.relation/trunk/src/zc/relation/README.txt 2008-04-23 15:49:06 UTC (rev 85655)
@@ -24,6 +24,16 @@
plone.relations containers, and zc.vault. The documents in the package,
including this one, describe other possible uses.
+History
+=======
+
+This is a refactoring of the ZODB-only parts of the zc.relationship package.
+Specifically, the zc.relation catalog is largely equivalent to the
+zc.relationship index. The index in the zc.relationship 2.x line is an
+almost-completely backwards-compatible wrapper of the zc.relation catalog.
+zc.relationship will continue to be maintained, though active development is
+expected to go into zc.relation.
+
Setting Up a Relation Catalog
=============================
@@ -1466,7 +1476,7 @@
Review
------
-That brings us to the end of our introductory example. Let's review, and
+That brings us to the end of our introductory examples. Let's review, and
then look at where you can go from here.
* Relations are objects with indexed values.
Modified: zc.relation/trunk/src/zc/relation/searchindex.txt
===================================================================
--- zc.relation/trunk/src/zc/relation/searchindex.txt 2008-04-23 15:23:50 UTC (rev 85654)
+++ zc.relation/trunk/src/zc/relation/searchindex.txt 2008-04-23 15:49:06 UTC (rev 85655)
@@ -8,12 +8,11 @@
Introduction
============
-This document assumes you have read the README.txt and the tokens.txt
-documents, and want to learn a bit more by example. In it, we will
-explore a set of relations that demonstrates most of the aspects of
-working with search indexes and listeners. It will not explain the
-topics that the other documents already addressed. It also describes
-an advanced use case.
+This document assumes you have read the README.txt document, and want to learn
+a bit more by example. In it, we will explore a set of relations that
+demonstrates most of the aspects of working with search indexes and listeners.
+It will not explain the topics that the other documents already addressed. It
+also describes an advanced use case.
As we have seen in the other documents, the relation catalog supports
search indexes. These can return the results of any search, as desired.
@@ -22,7 +21,7 @@
The searchindex module supplies a few search indexes, optimizing
specified transitive and intransitive searches. We have seen them working
-in other docuements. We will examine them more in depth in this document.
+in other documents. We will examine them more in depth in this document.
Search indexes update themselves by receiving messages via a "listener"
interface. We will also look at how this works.
@@ -196,6 +195,10 @@
Now we should have a search index installed.
+Notice that we went from parent (token) to child: this index is primarily
+designed for helping transitive membership searches in a hierarchy. Using it to
+index parents would incur a lot of write expense for not much win.
+
There's just a bit more you can specify here: static fields for a query
to do a bit of filtering. We don't need any of that for this example.
More information about the Checkins
mailing list