Talk:Python Style Guide

Copyright

This document has been placed in the public domain.

[A tiny point, since we're in style guide mode: please don't use public domain dedications, for the same sort of reasons given here, and because the statement can be interpreted differently depending on jurisdiction -- for example, France completely disallows authors to give up their author moral rights. So, I'm all about proper copyright licenses.] Cjb 13:57, 13 November 2006 (EST)

I've just copied the copyright notice from PEP 8. While we can reappropriate the copyright (after all, it's public domain), I'm lazy. I'd defer to the site copyright license, but it's considerably more restrictive and it's nice to keep licensing consistency. I looked for a proper CC license, but they all require attribution. How annoying. Not sure how to paste the HTML in here either. Hrm. Ian Bicking 21:22, 17 November 2006 (EST)

Localized docstrings?

Is there a mechanism in Python to localize docstrings? Not everyone who will be using Python libraries will speak English. --IanOsgood 18:37, 17 November 2006 (EST)

Not really; docstrings are syntactically required to be plain strings at the beginning of the function/module/class. Potentially the help browser could perform localization lazily. If translation is done after docstring extraction (which is the only feasible thing, I think) then it doesn't have any effect on Python code. -- Ian Bicking 22:59, 17 November 2006 (EST)

I'm planning to hit this issue eventually with Bityi (translating code editor). Homunq 13:35, 23 August 2007 (EDT)

OLPC Python Environment

The OLPC Python Environment page has a list of good guidelines at the end which should be included.

Some comments

I'm working on Bityi (translating code editor), and have some comments:

1. This is purely personal preference, but due to the fact that it moves around on different keyboards, I don't like the underscore character to show up several times per line of code. I also think that it is good to distinguish function and method names. Therefore, I would propose mixedCase names as an acceptable (or even preferred) alternative for method names / instance variables but NOT for function names. I know that this is contra PEP 8 but there are major projects which ENFORCE this convention, we should at least allow it.

2. My doodad will translate python code in version 1. It will eventually be able to translate docstrings and comments. However, even when it does, there is expected to be a lag period when a method name, argument, or instance variable is translated but the docstrings are not. Therefore, my code has to be able to reach into docstrings and translate some words. But if I just go and translate every translatable word, I will surely overtranslate simple words used as English and not as references to the code. Therefore, it would be beneficial to use some simple markup to mark words as 'code, for translation'. I'm leaning towards giving several options, including the following:

• any single word that leads a line and is followed by colon or n dashes. (this is to catch existing argument lists)
• any single word that is between two dashes like -this-.
• all the words in [brackets,with: at  : least; one =of >these< symbols;between ( each ) word+"except for words in single or double quotes"- also.goes|for*curly&brackets]. And similarly things that look like a function(call,including:above,punctuation). The punctuation, again, is: [,.<>:;|=+-*/^()] and the other kind of bracket - square inside curly and curly inside square. Note that this pattern {will {NOT catch} the_tail_bits_of_nested_brackets} or {unclosed brackets.
• anything that gets monospaced by reST

If we embrace Bityi, all docstrings should be formatted accordingly.

An example:

WRONG:

class MyClass():
    """A silly example class.
    ...
    method1: returns the inverse of its argument
    method2: even sillier, just returns method1(argument)
    """
...
    def method1(self,argument):
        """Returns the inverse of argument"""
        return -argument
...
    def method2(self,whyIsntThisCalledArgument):
        """Calls method1 on whyIsntThisCalledArgument and returns the result.
...
        whyIsntThisCalledArgument  --  number to pass to method1 [and I don't want any argument about that name!]
        """
        return self.method1(whyIsntThisCalledArgument)

Note that above 5 things are caught automatically, but 4 things are missed.

WORKS:

class MyClass():
    """A silly example class.
    ...
    method1: returns the inverse of its argument
    method2: even sillier, just returns method1(argument)
    """
...
    def method1(self,argument):
        """Returns the inverse of [argument]"""
        return -argument
...
    def method2(self,whyIsntThisCalledArgument):
        """Calls method1() on -whyIsntThisCalledArgument- and returns the result.
...
        whyIsntThisCalledArgument  --  number to pass to method1() [and I don't want any argument about that name!]
        """
        return self.method1(whyIsntThisCalledArgument)

Easy markup added to the 4 things missed above (inverse of [argument],method1() on -whyIsntThisCalledArgument-, and method1()