[sugar] Python Style Guide

[Ian Bicking]

Dan Williams wrote:
>>  > [note: I don't think double underscore should ever be used; maybe 
>> this should be removed]
>>
>> I think it should, it's just confusing.
> 
> I am a bit concerned about visibility though; for stuff that should
> _never_ be used from programs outside of the sugar bindings we should
> really be using __ to keep the symbols private.  There _are_ things that
> we need to do that we really don't want to be part of the public API,
> and that we want to enforce; especially where the implementation details
> might change quite rapidly over the next few months.  But in general, __
> should go away.

Note that __ isn't just private outside of sugar, but private to every 
function outside of the original class, including functions defined or 
overridden in subclasses.

>>  >For simple public data attributes, it is best to expose just the 
>> attribute name, without complicated >accessor/mutator methods
>>
>> I'm not sure I like this... It's quite unusual for non python coders. If 
>> we want to keep it we should probably elaborate more on it in the guide.
> 
> Again, if we expect any of this stuff to change we should be hiding them
> behind accessors...  I know there are a _ton_ of tricks you can use in
> Python to maintain backward compatibility, and I've seen & used a few of
> them before in my python projects.  This is a balance between work we'd
> have to do in the future to maintain backwards compat and a small amount
> of adding accessors here and there.
> 
> I'm very uncomfortable with exposing stuff like:
> 
> class Foo:
> 	def __init__(self):
> 		self.var = 1
> 
> a = Foo()
> a.var = 2
> 
> because then you can't do any validation and you never know when the
> variable changes; accessors fix this because you always know when the
> value changes and you can validate the change and throw exceptions.  If
> this isn't what you're talking about, ignore me.

I'm not arguing against single-underscore private variables (like 
self._var).  Double underscore (e.g., self.__var) is the stuff that does 
name mangling, which does weird things to introspection tools and 
subclassing.

> For example; dbus always returns strings as unicode because the native
> bus encoding is UTF-8, and you can't just do 'if a == b' where a is
> unicode and b is encoded.  Therefore, for stuff like that, you always
> need to use an accessor to either enforce the restriction or to do the
> conversion yourself.

Not directly your point, but I do think we need to be very careful about 
avoiding encoding strings, doing the decoding at the boundaries whenever 
possible (where dbus is a boundary).


-- 
Ian Bicking | ianb at colorstudy.com | http://blog.ianbicking.org