[Microbit-Python] Accessor API design on the micro:bit

[Larry Hastings]

I want to revisit something that was decided during the sprints at PyCon 
UK.  On a Github PR today ( 
https://github.com/bbcmicrobit/micropython/pull/58 ) there was a short 
discussion about how to spell "give me the x coordinate reading from the 
accelerometer object".  I suggested "accelerometer.x".  In response, 
Damien George said:
> We discussed this at length at PyCon UK: we use functions for 
> everything. It's more consistent (and setters like obj.attr = 1 can't 
> be used in a lambda, while obj.set_attr(1) can).

Nick Tollervey said, nigh-simultaneously:
> I seem to remember having a conversation about get_foo() v foo or 
> foo() at PyCon UK. IIRC we agreed to keep such things as method calls 
> since that's a consistent pattern in the way the API is written. I 
> also remember a discussion about using explicit verbs in the method 
> name so kids immediately understood what it was they were calling. 
> I.e. get_foo() is more obvious than simply just foo().

I'm all for consistency, but in this case I think the group has chosen 
to be consistent in the wrong way. Things like "accelerometer.x" are 
/exactly/ what the descriptor protocol is for. The spelling couldn't be 
clearer, not to mention it's easy to read and pleasingly short to type. 
I would absolutely 100% design my API that way for adults and I think 
it's better for kids too.

It's true that you can't use an assignment statement in a lambda 
function. But:

 1. one shouldn't warp one's API design to accommodate lambda functions,
 2. accelerometer.x is read-only,
 3. I doubt the curriculum for 11-year-olds will include lambda, and
 4. I propose we strenuously avoid callback-based APIs. ("I don't like
    callback interfaces, I always get them wrong" --GvR (quote is
    approximate)) Iteration > callbacks.  For example, Python's
    sched.Scheduler class has a callback-based API, but the Scheduler
    class I've written for the micro:bit (coming soon!) does not.


I'd greatly rather see us make properties of objects behave like simple 
attributes, using descriptors where necessary. I suggest that's far more 
Pythonic--accessor functions always feel like Java or C++ to me.  
(Indeed, ISTM the descriptor protocol was added to Python precisely so 
we don't ever need accessor functions!)

It's our API, we can spell it any way we like.  I propose we use simple 
attributes nearly everywhere, using descriptors where necessary. I'd 
reserve the .set_x() accessor method spelling for the rare attribute 
that actively changes something (e.g. 
microbit.display.set_display_mode). And I still might use a read-only 
descriptor instead of a .get_x() method for those. (Though I'd have to 
think about that one, and/or play with some examples.)


Cheers,


//arry/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.python.org/mailman/private/microbit/attachments/20151030/5dace30e/attachment.html>