[sugar] Python Style Guide

[Ian Bicking]

Marco Pesenti Gritti wrote:
> Cool! Some comments:
> 
>  > Use 4 spaces per indentation level. Do not use tabs.
> 
> Heh, I'm fine with this... we just need to convince Dan.

I remember him saying he was okay with it last time it came up.

>  > Separate top-level function and class definitions with two blank lines.
> 
> Is this taken from PEP-8?

Yes (like almost everything in the style guide).  I find the vertical 
whitespace recommendations a bit excessive, in that *I* have never cared 
at all about the details of vertical whitespace and would rather leave 
it to the author.  At least we don't have to worry about brace styles.

Maybe we should just trim that down to a simple "use a little but not 
too much vertical whitespace".

>  >__init__.py files should generally contain no substantive code. 
> Instead they should import from >other modules. Importing from other 
> modules is done so that a package can provide a front-facing >set of 
> objects and functions it exports, without exposing each of the internal 
> modules in the >package. Note however that this causes the submodules to 
> be eagerly imported; if this is likely to >cause unnecessary overhead 
> then the import in __init__.py should be reconsidered.
> 
> Can you give an example of this? I think it would be useful to have it 
> on the guide too. Is it part of PEP-8 in any way?

This was my addition.  __init__.py can be a little tricky, because it 
will swallow ImportErrors and maybe some other errors.  (This way if you 
__init__.py is broken, the entire package won't become unusable.)  For 
this reason I prefer not to put too much into those files.  Also I must 
admit an Emacs bias, where I like it when files tend to have more unique 
names than __init__; but I that's not a real justification ;)

As for the imports, if you have:

   mypkg/__init__.py
   mypkg/main.py

And in __init__.py you have:

   from mypkg.main import MyProvider

Then other people can do:

   from mypkg import MyProvider

>  > Version bookkeeping
> 
> Doesn't sound particularly interesting to me. I'd probably just omit  
> that section.

Agreed.

>  > Module names
> 
> Might be worth motivating lowercase with other reasons than filesystem 
> compatibility (I think you gave better reasons on the list a while ago).

Also agreed.

>  > [note: I don't think double underscore should ever be used; maybe 
> this should be removed]
> 
> I think it should, it's just confusing.

OK.

>  >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.

I guess the guide goes into some details, but mostly in the negative 
(when you shouldn't use simple attributes for accessors/mutators).

> *> Comparisons to singletons like None should always be done with 'is' 
> or 'is not', never the equality operators.*
> 
> Is this just style or does it have other consequences?

It does have some purpose; is/is not does identity comparison.  There's 
only ever one None object, so this works.  == does fancier comparison, 
and checks for some magic methods to overload == and other stuff.  So 
it's slightly slower.  It also touches the object in ways that is/is not 
does not.

> *> For sequences, (strings, lists, tuples), use the fact that empty 
> sequences are false.
> 
> Nice one!

Thank Python ;)

> *> Is _() always defined?
> 
> Nope, I think you need to import it from gettext.

OK; are we just using plain gettext for everything?  I've been 
encountering places where people use fancier _'s, but I think that's 
because in server-side apps you might be supporting multiple language 
simultaneously, which isn't an issue for OLPC.

In some of these cases people often put _ in __builtins__.  Which seems 
convenient, except you end up doing this for portability:

   try:
       _
   except NameError:
       (import from gettext or define a dummy)

Which isn't any more convenient.


I also just added a not-filled-out section on deprecations, as I think 
recommendations associated with that are useful.

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