[Dev] Feedback on repository documents requested
Ted Leung
twl at osafoundation.org
Fri Oct 15 11:37:26 PDT 2004
I've include my reply in line -- if I don't address it, I made
suggested change.
On Oct 13, 2004, at 6:48 PM, Donn Denman wrote:
> Ted,
>
> I have a bunch of nit-picky comments, but overall this looks good. It
> covers all the important points I was looking for, except that I'd
> like to see a section on trouble-shooting. Also, if there's a way to
> do interactive experimentation that would be really great. Along those
> lines, I've been thinking about adding a field to the Detail View of
> an Item Collection for the query. This should be easy for me to do,
> and then you can just edit the query in place, hit enter, and see the
> results in Chandler. Now that 0.4 is branched, we can consider it -
> let me know if you think this is a good way to go. Maybe we enable it
> from the "test" menu.
I think that a test menu item would be great. It would be even better
to type the query into a box, and have a list box that displays the
results -- kind of a little browser, but I don't know how much work
that would be to do.
>
> - Donn Denman
>
> DETAILS
> -------------
>
> Here's the information I expected to find in your document, and what I
> found:
> --------------
> * Can queries be run over a subset of the repository? YES, using an
> itemCollection for the input set.
You are also doing this when you specify a Kind as the source
> * How do you iterate through queries? What form are the results in?
> The query object is itself an iterator. Saying this explicitly would
> be nice - it looks like it could be a sequence and support slicing...
> * What's the grammar for queries? You covered this, though not
> explicitly. A BNF grammar might be nice for us techies.
> * What are some common errors in writing a query? You should add a
> section on how/where to find syntax errors.
I'm not sure we have enough experience to know common errors. Most of
the ones that I can think of are the usual type sorts of things.
> * Is there an interactive way to experiment with queries? Not yet...
>
> Comments
> --------------
> * Typo in the second sentence: missing the word "of" before "care"
> * Suggest adding a sentence to the second paragraph: This feature
> allows queries to automatically keep their result sets up-to-date.
> * In the first paragraph of the Python API section, give an example of
> usage in parcel.xml. In an ItemCollection, the query is held in the
> "_rule" attribute:
> <_rule value="for i in
> '//parcels/osaf/contentmodel/calendar/CalendarEventMixin' where
> True"/>
> * The next paragraph should start: "To use a query from Python, your
> code..."
> * when you say "The query string may be "", the following sentence is
> ambiguous. Do you mean the above example, or the empty string query?
> * looks like you forgot to use boldface for the keywords of the query
> under the section "for queries"
> * When using a lucene query, is the query run over all items with an
> attribute in the specified list whose type is lucene-type? Seems like
> this is a potential long-term problem, because you have to run the
> lucene query over the entire repository. Maybe this is the way lucene
> works, and that's why you did it this way. If not, it seems like it
> would be good to be able to specify an ItemCollection for the search
> set, and still run a lucene-query, which you can't do now.
At the moment this is how pylucene works. It searches the entire
repository whether you want to or not. I agree that limiting the scope
of pylucene searching would be useful, but that also depends on how you
build the index. Right now there's a single pylucene index for the
repository (I think). Restricting the scope would require multiple
indices.
> * Missing a section in the query syntax on literals. Seems like you
> can use numbers, string literals, booleans...
> * There are several little typos...I stopped making note of them.
> * It would be good if you typographically highlighted the special use
> of the word "for", otherwise it's hard to read sentences like "...
> composed of three for queries that show..."
> * You could mention that "union" combines the results from all queries
> specified, and intersection returns only items that are in both result
> sets.
> * With difference, it's all the items in 1 that are not in 2, right?
> If there are items in 2 that are not in 1, they get ignored? You
> could update the example to use 'block' and 'blocker' to illustrate
> the point.
> * Query notification is a bit confusing. The item is confusing,
> because I think it might correspond to the item added/removed from the
> query. You should point out that the item is usually a block, or at
> least an item whose kind is associated with a class that has the
> specified method.
> * Is there a way to get the item(s) that entered or exited the query
> in the notification? I guess you could pass an "items" iterable to
> give access to that. Not sure how useful it would be, but it seems
> like entered/exited isn't very useful if you can't find out which
> items entered/exited. Also, what happens if some items enter and some
> exit? You get two notifications?
Notification is going to get more functionality in 0.5. One thing will
probably be to pass the items that were modified.
> * You should quote "exited" at the end of the Query Notification
> section.
>
> Comments on Query Functionality inspired by the Doc Review
> -------------------
> * It would be nice if the "where" clause was optional, so the user
> doesn't need to say "where True"
Noted for 0.5
> * It would also be nice if you could make "contains" a binary operator
> instead of a function. E.g. "...where i.itsName contains 'arc'"
Noted for 0.5, but I'm not promising
> * Have you thought about allowing arbitrary python functions to
> execute in the query? I know this is a security hole, and probably
> difficult to make robust.
The machinery is all there to execute any python function that you
want. I purposely restrict the set of functions for security reasons.
Thanks for the great review!
>
> On Oct 12, 2004, at 5:39 PM, Ted Leung wrote:
>
>> Hi all,
>>
>> I checked in a pair of documents for repository features in 0.4. I'd
>> appreciate any comments, corrections, or questions regarding their
>> contents.
>>
>> <http://cvs.osafoundation.org/viewcvs.cgi/*checkout*/chandler/
>> distrib/docs/repository-intro.html?rev=HEAD&content-type=text/html>
>>
>> <http://cvs.osafoundation.org/viewcvs.cgi/*checkout*/chandler/
>> distrib/docs/chandler-query-system.html?rev=HEAD&content-type=text/
>> html>
>>
>> Thanks,
>>
>> Ted
>>
>> _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
>>
>> Open Source Applications Foundation "Dev" mailing list
>> http://lists.osafoundation.org/mailman/listinfo/dev
>>
----
Ted Leung Open Source Applications Foundation (OSAF)
PGP Fingerprint: 1003 7870 251F FA71 A59A CEE3 BEBA 2B87 F5FC 4B42
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: text/enriched
Size: 6952 bytes
Desc: not available
Url : http://lists.osafoundation.org/pipermail/dev/attachments/20041015/b7c71d39/attachment.bin
More information about the Dev
mailing list