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

[Carol Willing]

On 11/1/15 7:57 AM, Larry Hastings wrote:
>
>
> On 10/31/2015 01:08 PM, Carol Willing wrote:
>> Does this have to be a decision between x, x(), get_x()?
>
> I think it should be, yes.  I remind you of the guiding principle from 
> the Zen Of Python: "There should be one (and preferably only one) 
> obvious way to do it".  This is so often cited it's been abbreviated 
> as TOOWTDI (There's Only One Way To Do It).  No foolin'!

Larry, Ideally one "obvious" way but there are frequently convenience 
functions that do the same/similar thing :P Though your point is taken :-)

>
> Having only one way to do things enhances code clarity.  If there are 
> two ways to read the X value of the accelerometer, I might use one and 
> you'd use the other, and then I'd puzzle over your code (and you mine) 
> when it came time for code review.
>
>
> On 11/01/2015 06:27 AM, Nicholas H.Tollervey wrote:
>> This also makes me wonder about descriptor v accessor in other parts of
>> the API. For example, could we do this?
>> >> microbit.pin0  # digital read
>> 1
>> >> microbit.pin0  # analog read
>> 234
>> >> microbit.pin0 = 0  # digital set
>> >> microbit.pin0 = 234  # analog set (0...255)
>
> We probably /could/, but it would be difficult and it would introduce 
> another problem.
>
> You're proposing that we make pin0 (and presumably the others) a 
> "property".  In CPython, modules don't support properties.  We could 
> get around that by making "microbit" not be a module--or, perhaps, a 
> subclass of module that supports properties.
>
> (Of course, we're not /using/ CPython, we're using /MicroPython/. And 
> it's possible MicroPython modules actually /do/ support properties.   
> Damien?)
>
>
> The other technological problem it raises: we could no longer use 
> attributes on the pin0 object.  For example we could no longer say:
>
>     microbit.pin0.set_digital_mode(True)
>
> (or whatever the method is called here, I forgot).  Python would see 
> microbit.pin0 and say "oh, that's a property", call the property's 
> getter function, and return the result.  If the result was 234 then 
> this would be the same as 234.set_digital_mode(True) which clearly 
> won't work.
>
> (The only way to get your hands on the actual pin0 object would be 
> through the dict, e.g. 
> microbit.__dict__['pin0'].set_digital_mode(True) would work.  But 
> obviously that's a bad API.)
>
>
> My final argument is subjective.  I'll remind you that at the PyCon UK 
> sprints I was actually arguing for this exact thing--that you should 
> set the value of pin0 by saying microbit.pin0 = True or what have 
> you.  But I was convinced to change my mind.  What did it was, again, 
> citing the rule of thumb for when to make something a property: it 
> shouldn't feel like it is /doing/ something.  A property should behave 
> like a passive object.  But the I/O pins are doing I/O, and I/O is 
> traditionally an active API.  I've never seen a file object or a 
> socket that behaved like a passive object.
>
> Again, it's a subjective distinction.  But checking the accelerometer 
> reading feels like a passive activity, like looking at my watch for 
> the time.  Whereas reading the input pin feels more active, like 
> checking my mailbox to see if I have any letters

While I would love to see a matrix of approach vs. benefits and 
downsides from a student and teacher perspective, I don't have a strong 
preference. What I do think we are all in agreement on is that good 
documentation and clarity in help messages will be important for the end 
users.

Warmly,
Carol

-- 
*Carol Willing*
Developer | Willing Consulting
https://willingconsulting.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/microbit/attachments/20151101/7e3c0a52/attachment-0001.html>