[sugar] Python Style Guide

[Marco Pesenti Gritti]

Ian Bicking wrote:
> Ivan mentioned that there was someone willing to update all the OLPC 
> code once we have a style guide.
>
> With that in mind I put together a draft of a style guide: 
> http://wiki.laptop.org/go/Python_Style_Guide
>
> This is primarily a copy of PEP 8: 
> http://www.python.org/dev/peps/pep-0008/ -- I think we discussed most 
> of the variances the current code has from PEP 8 a couple months ago, 
> and I think everyone was okay with changing the code in those ways.  
> But of course, there were other things to attend to at the time; 
> having someone else volunteer to do the change makes this relevant again.
>
> I've marked a number of things I'm unsure of with [note: ...].  
> Several of these are about code (and other file) layout issues, which 
> don't matter too much to an initial changeover of the code. 
> Internationalization style remains; I think someone besides myself 
> would be better at specifying the style for these.
>
> We might want to consider setting up a pylint profile for this style. 
> pylint (http://www.logilab.org/projects/pylint) is notable among 
> Python source checkers for being anal about style and other small 
> details. Whoever is updating the code for the style might start out by 
> tweaking pylint until it can detect all the details we want to 
> update.  It's also better to stick to the easy/mechanical updates to 
> start with, and avoid updates that might introduce bugs.  Probably it 
> would make sense to annotate the style guide rules with "code already 
> should conform", "we will update current code" and "code will be 
> updated when possible".
>

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.

 > Separate top-level function and class definitions with two blank lines.

Is this taken from PEP-8?

 >__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?

 > Version bookkeeping

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

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

 > [note: I don't think double underscore should ever be used; maybe 
this should be removed]

I think it should, it's just confusing.

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

*> 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?

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

Nice one!

*> Is _() always defined?

Nope, I think you need to import it from gettext.

Anyway, great stuff. Let's try to finalize and start using it.

Marco