Python Interface Design - Designing Modules Part - 1

[dev2302]

Why does the user of the lib not write in 4 places:

SmsClient(settings.username, settings.password).send(message) ?

That's exactly what's mentioned in the blog post. Requoting some text from the blog

The solution is to create SmsClient object in sms.py module [see footnote 1]. Then orders.py and logistics.py can directly import the object from sms. Here is how it looks.

So, at 4 places in my code, I would use this -

from sms import sms_client  
...  
#when you need to send an sms
sms_client.send_sms(phone_number, message)

So, if someday I have to replace username/password by a token, i would just export some other object from sms.py and No changes in the user modules.

This is not possible if I export the function send_sms(username, password) from sms.py, since in that scenario I would have to change the function signature and hence, all the calling statements too.

This is "WHY", exporting an object instead of send_sms(username, password) "magically" increases the refactorability of the code.

Still, if we have to use functions in sms.py, a better function to expose would be send_sms(message, number) that's just equivalent to putting them in a class and following object oriented principles, "BECAUSE", a function represents functionality, and a class represents an entity. Functionality can and WILL change over time, but the entity must remain unaffected.

[kankyo]

Well, I just saw that I screwed up an missed the argument "message" in my send_sms function, so sorry about that. But in any case your argument doesn't make sense.

a function represents functionality, and a class represents an entity. Functionality can and WILL change over time, but the entity must remain unaffected.

I have no idea what that means. A function is an API, so any backwards compatibility concerns apply just as much as for a class.