u1db-discuss team mailing list archive

[Stuart Langridge <stuart.langridge@xxxxxxxxxxxxx>]

At the moment, the Python reference implementation of u1db has two
separate functions create_doc() and put_doc(). The distinction is that
create_doc() only takes a Document, without revision, and put_doc
requires both id and revision; create_doc() is unambiguously for
creating new documents (it's an INSERT, in SQL terminology) and
put_doc() is only for overwriting existing docs (it's an UPDATE).

When the API was originally designed, these took the input as
parameters: create_doc took a JSON string (for document) and an optional
document ID, and put_doc took a JSON string, a document id, and a
revision. However, now that we use Document objects everywhere, both
just take a Document object (which may have id and revision filled in or
may not). So, there's a clearer argument that perhaps they should be
unified and there's just put, which works like this:

id         | revision      | result
null       | null          | create new doc with new id
not null   | null          | create new doc with specified ID
null       | not null      | error!
not null   | not null      | update existing doc (if rev is correct)

One reason for *not* doing this is that create and put are different
things in the mental model, and therefore should be different functions.
However, this is a lot less relevant in the new world of Document
objects. So, I invite thoughts on whether they should be unified.

sil

PS. Is there any reason to not just call them put and create rather than
put_doc and create_doc()? It does help to distinguish create_doc() and
create_index(), but if they're unified to put() then there's no
collision with create_index().