DISCUSSION: Are setter methods which clone and return object type confusing to end-users?

[dhermes]

Methods like datastore.key.Key.dataset act as both setters and getters and return a different type of object depending on whether they set or get.

In this case key.dataset(dataset=NEW_DATASET) returns a new clone Key object (to keep the instances immutable, as @tseaver pointed out was discussed in #3) where key.dataset() simply returns a datastore.dataset.Dataset object.

For me (@dhermes) it's really a method which is somewhat overloaded in it's scope (though I'll acknowledge the code is typically short).

I'd be much more in favor of two separate methods for getting and setting, i.e.
update_dataset as a method and dataset decorated with @property as a getter only.

curr_dataset = key.dataset  # Actually a getter.
new_key = key.update_dataset(dataset=NEW_DATASET)

[silvolu]

I like your proposal, I think it's a small price to pay for a more clear API. @aliafshar, any thoughts on this one?

[dhermes]

Closing out due to discussion in Datastore Package API Surface Discussion.

After implemented, this will only occur on datastore.Query and with an expanded constructor even that won't be necessary. (Also, #439 will help a bit.)