Still more redundancy-elimination between the two style guides. This change drops the sections on Properties, True/False evaluations, the Boolean built-in type, String methods, and Lexical scoping, all of which differed in no way from the Google Python Style Guide.
diff --git a/PythonStyleGuide.wiki b/PythonStyleGuide.wiki index 318b583..d42e0e5 100644 --- a/PythonStyleGuide.wiki +++ b/PythonStyleGuide.wiki
@@ -31,11 +31,6 @@ # [PythonStyleGuide#Imports Imports]: _Import only modules and only by name *(no wildcard imports)*_ # [PythonStyleGuide#Function_Arguments Function Arguments]: _Yes_ - # [PythonStyleGuide#Properties Properties]: _Yes_ - # [PythonStyleGuide#True_False_evaluations True/False evaluations]: _Yes_ - # [PythonStyleGuide#Boolean_built_in_type Boolean built-in type]: _Yes_ - # [PythonStyleGuide#String_Methods String Methods]: _Yes_ - # [PythonStyleGuide#Lexical_Scoping Lexical Scoping]: _Yes_ # [PythonStyleGuide#Function_and_Method_Decorators Function and Method Decorators]: _Yes, *in moderation*_ # [PythonStyleGuide#Threading Threading]: _*do not use* (not available in [http://code.google.com/appengine/kb/general.html#libraries Google App Engine])_ # [PythonStyleGuide#Power_features Power features]: _*No*_ @@ -114,159 +109,6 @@ *Decision:* Always pass positional arguments positionally and keyword arguments by keyword. -== Properties == - -*What they are:* A way to wrap method calls for getting and setting an -attribute as a standard attribute access when the computation is lightweight. - -*Pros:* Readability is increased by eliminating explicit `get` and `set` -method calls for simple attribute access. Allows calculations to be lazy. -Considered the Pythonic way to maintain the interface of a class. In terms -of performance, allowing properties bypasses needing trivial accessor -methods when a direct variable access is reasonable while allowing future -accessor methods to be possible without breaking the interface. - -*Cons:* Properties are specified after the getter and setter methods are -declared, requiring one to notice they are used for properties farther down -in the code (except for read-only properties created with the `@property` -decorator - see below). Must inherit from object. Can hide side-effects -much like operator overloading. Can be confusing for subclasses. - -*Decision:* Use properties in code where you are accessing or setting -data where you would normally have used simple, lightweight accessor or -setter methods. Read-only properties should be created with the -`@property` [PythonStyleGuide#Function_and_Method_Decorators decorator]. - -Inheritance with properties can be non-obvious if the property itself -is not overridden. Thus one must make sure that accessor methods are -called indirectly to ensure methods overridden in subclasses are called -by the property (using the Template Method design pattern). - -*Yes:* - -{{{ -import math - -class Square(object): - """Basic square with writable 'area' property, read-only 'perimeter' property. - - To use: - >>> sq = Square(3) - >>> sq.area - 9 - >>> sq.perimeter - 12 - >>> sq.area = 16 - >>> sq.side - 4 - >>> sq.perimeter - 16 - """ - - def __init__(self, side): - self.side = side - - def _getArea(self): - """Calculation for 'area' property""" - return self.side ** 2 - - def __getArea(self): - """Indirect accessor for 'area' property""" - return self._getArea() - - def _setArea(self, area): - """Setter for 'area' property""" - self.side = math.sqrt(area) - - def __setArea(self, area): - """Indirect setter for 'area' property""" - self._setArea(area) - - area = property(__getArea, __setArea, - doc="""Get or set the area of the square""") - - @property - def perimeter(self): - return self.side * 4 -}}} - -== True False evaluations == - -*What it is:* Python evaluates certain values as "false" when in a boolean -context. A quick "rule of thumb" is that all "empty" values are considered -"false" so `0`, `None`, `[]`,` {}`, `""` all evaluate as "false" in a -boolean context. - -*Pros:* Conditions using Python booleans are easier to read and less -error-prone. In most cases, it's also faster. - -*Cons:* May look strange to C/C++ developers. - -*Decision:* Use the "implicit" false if at all possible, e.g., -`if foo:` rather than `if foo != []:`. There are a few caveats that you -should keep in mind though: - - * Comparisons to singletons like `None` should always be done with `is` or `is not`. Also, beware of writing `if x:` when you really mean `if x is not None:` -e.g., when testing whether a variable or argument that defaults to `None` was set to some other value. The other value might be a value that's false in a boolean context! - * For sequences (strings, lists, tuples), use the fact that empty sequences are false, so `if not seq:` or `if seq:` is preferable to `if len(seq):` or `if not len(seq):`. - * Note that `'0'` (i.e., 0 as string) evaluates to true. - -== Boolean built in type == - -*What it is:* A boolean type has been available in Python since version 2.3. -Two new built-in constants were added: `True` and `False`. - -*Pros:* It makes code easier to read and is backward-compatible with the -use of integers as boolean in previous versions. - -*Cons:* None. - -*Decision:* Use booleans. - -== String Methods == - -*What they are:* String objects include methods for functions that used to -be in the `string` module. - -*Pros:* No need to import the `string` module; methods work with both -regular byte-strings and unicode-strings. - -*Cons:* None. - -*Decision:* Use them. The `string` module is deprecated in favor of -string methods. - -*No:* `words = string.split(foo, ':')` - -*Yes:* `words = foo.split(':')` - -== Lexical Scoping == - -*What it is:* A nested Python function can refer to variables defined -in enclosing functions, but can not assign to them. Variable bindings are -resolved using lexical scoping, that is, based on the static program text. -Any assignment to a name in a block will cause Python to treat all -references to that name as a local variable, even if the use precedes -the assignment. If a global declaration occurs, the name is treated as a -global variable. - -An example of the use of this feature is: - -{{{ -def getAdder(summand1): - """getAdder returns a function that adds numbers to a given number.""" - def anAdder(summand2): - return summand1 + summand2 - - return anAdder -}}} - -*Pros:* Often results in clearer, more elegant code. Especially comforting -to experienced Lisp and Scheme (and Haskell and ML and ...) programmers. - -*Cons:* None. - -*Decision:* Okay to use. - == Function and Method Decorators == *What they are:* Decorators for Functions and Methods, added in Python 2.4