u1db-discuss team mailing list archive

[Rodney Dawes <dobey.pwns@xxxxxxxxx>]

So, I have started writing an implementation of U1DB in Vala. I haven't
actually dove into the back-end code writing bits yet, as I've just been
setting up the basics to get proper GObject Introspection data
generated, and such. However, I have started attempting to define some
of the classes for the implementation, and either I am misunderstanding
what U1DB is defined as, or we're doing it all wrong.

It is my understanding (from UDS session, etc…) that U1DB is a
definition of API, which is an abstraction layer, for storing JSON in
some sort of database below it, and managing synchronization. And the
reference implementation (and thus, the definition), is in Python.

However, not all languages are Python. While looking at the
u1db.Database class, it occurs to me that the code is more written
in a way that is very tied to the dynamic design of Python, and to
make writing the unit tests more trivial, than perhaps a structured
document-based storage system should present an API.

For instance, there seems to be a fair bit of inconsistency in the
document-related functions; particularly as relates to return values,
arguments, and argument ordering. In most all cases, the arguments are
also positional, and not keyword arguments, which can be annoying when
similar methods expect similar arguments, but in different orders.

It seems to me, that aside from the Database and SyncTarget objects,
there should also be Document and Index. Then the API could more easily
be made consistent across the board. For example, Document APIs on the
Database object, might instead look something like this:

  Document   create_doc (string content, string doc_id=None)
  Document   get_doc    (string doc_id, bool check_for_conflicts=True)
  Document[] get_docs   (string doc_id[], bool check_for_conflicts=True)
  long       put_doc    (Document)
  void       delete_doc (Document)

Here, Document would be a simple object containing attributes for the
id, revision, and content. The mentioned calls would still be on the
Database object. The constructor arguments for Document, would be the
id, revision, and content.

This sort of API design would make it easier to keep consistency across
the board for all related methods, and would translate much better to
other languages, such as C, Vala, Java, etc… which are not dynamic, and
must have complex types defined to hold this data.

Am I wrong?