fdb.py 1.30 — Embryonic /values API support

I’ve just pushed a new version of fdb.py to the GitHub repository.

This release doesn’t change the command line but does add support for the (not-so) new /values API.

The /values API is a huge step forward for Fluidinfo, and I should have started adding support ages ago. It allows bulk reading and writing of tags on groups of objects that can be specified with a Fluidinfo query vastly more efficiently than was possible before.

There are a few things to note about the implementation:

• It is inconsistent with the rest of fdb.py at present; I aim to remedy this (see below).
• In particular, all strings must be unicode for the new calls (input and output), tags being written must already exist (ouch!) and any tags must be specified using full (absolute) Fluidinfo paths with no leading slash (unlike everywhere else in fdb.py).
• The new calls are not exploited by the command line commands show or tag, so those will run no faster. Obviously, I plan to change this over time, too.

Examples¶

The following code shows simple use of the two main new calls, get_values and tag_by_query.

import fdb

db = fdb.FluidDB()

# Get about tag and njr/rating for objects njr has rated < 2:
values = fdb.get_values(db, u'njr/rating < 2',
                        [u'fluiddb/about', u'njr/rating'])
print u'Low ratings:\n'
for v in values:
    print unicode(v), u'\n'

# Tag those same objects with njr/dislike = True.
# (Currently requires njr/dislike to exist; easy to create using
# the command line to tag a single object.

fdb.tag_by_query(db, u'njr/rating < 2',
                 {u'njr/dislike': True})

#
# Now get the ones that are disliked:
#
values = fdb.get_values(db, u'has njr/dislike',
                        [u'fluiddb/about', u'njr/rating', u'njr/dislike'])
print u'Disliked:\n'
for v in values:
    print unicode(v), u'\n'

When run, this produces the following (for me, right now; you won’t be able to run it as-is, because you don’t have write access to my dislike tag.)

$ python ex.py
Low ratings:

   fluiddb/about: book:foucaults pendulum (umberto eco)
              id: a98f2c80-ae5f-405a-a319-d47122ae9da3
      njr/rating: 1

   fluiddb/about: The_Beatles
              id: 5157c69e-ceaf-4e7c-9423-d67751d029d3
      njr/rating: 1

   fluiddb/about: book:beloved (toni morrison)
              id: 1ab066e8-c2a1-4769-9121-e3346849e7e4
      njr/rating: 1

   fluiddb/about: book:the lord of the rings (jrr tolkien)
              id: ff873602-e9a8-4f9a-a7d4-c0cfc394a120
      njr/rating: 1

   fluiddb/about: book:oranges are not the only fruit (jeanette winterson)
              id: 7aed1e67-a88e-439d-8a56-b2ab52c838ab
      njr/rating: 0

Disliked:

   fluiddb/about: book:foucaults pendulum (umberto eco)
              id: a98f2c80-ae5f-405a-a319-d47122ae9da3
     njr/dislike: True
      njr/rating: 1

   fluiddb/about: The_Beatles
              id: 5157c69e-ceaf-4e7c-9423-d67751d029d3
     njr/dislike: True
      njr/rating: 1

   fluiddb/about: book:beloved (toni morrison)
              id: 1ab066e8-c2a1-4769-9121-e3346849e7e4
     njr/dislike: True
      njr/rating: 1

   fluiddb/about: book:the lord of the rings (jrr tolkien)
              id: ff873602-e9a8-4f9a-a7d4-c0cfc394a120
     njr/dislike: True
      njr/rating: 1

   fluiddb/about: book:oranges are not the only fruit (jeanette winterson)
              id: 7aed1e67-a88e-439d-8a56-b2ab52c838ab
     njr/dislike: True
      njr/rating: 0

How fdb.py Will Change¶

Obviously, the fact that these calls are inconsistent with the rest of fdb.py is unfortunate; in fact, it’s plain terrible. I plan to make a number of changes to make this situation better.

First, I plan to change the whole of fdb.py to use unicode internally. This shouldn’t affect the command line much, except for making from unicode cases work better, but will affect users of the fdb.py API.

Secondly, I plan to allow users to use full, fdb.py-style absolute or relative paths for tags, to make it consistent with the rest.

Thirdly, like elsewhere in fdb.py, it will create tags if they don’t exist, as required.

Finally, I plan to add an option to fdb.py to allow the user to choose whether to use fdb.py/Unix-style paths or 100%-genuine, @terrycojones-approved Fluidinfo-style absolute paths only, with no leading slashes, requiring fluiddb/about and disallowing relative paths. I plan to make this choice available both through configuration option and a command-line flag (in the case of the command line), and with an extra initialization parameter for use of the API. The configuration will affect both specification of tags by the user and reporting of tags by the system. So there will be choice. (Maybe Terry will be so pleased he’ll add tag-creation-by-tag-writing for me as a “thank you”.)

Personally, I will continue to use Unix-style paths, because I find it so inconvenient not to have relative paths and to have to add fluiddb/ just to refer to the about tag; but others may prefer conformity.

For those who have been following the mailing list, I will also aim to add a few other aggregation functions (currently there is only count).