u1db-discuss team mailing list archive

[John Meinel <john@xxxxxxxxxxxxxxxxx>]

create_doc currently takes a string and returns a Document. put_doc
requires that doc_id and rev be set. (We can always change things.)

I've certainly thought about the _doc thing a bit. Shorter is nice, but IME
debugging / profiling / etc is hard if your names are too generic and
Herbert-used. Is that d.get a dict.get or a Database.get or a Document.get.
I certainly could be swayed, but it is *_doc for a reason.

John
=:->
On Dec 5, 2011 11:43 PM, "Stuart Langridge" <stuart.langridge@xxxxxxxxxxxxx>
wrote:

> 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().
>
>
>
> --
> Mailing list: https://launchpad.net/~u1db-discuss
> Post to     : u1db-discuss@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~u1db-discuss
> More help   : https://help.launchpad.net/ListHelp
>