Continued redundancy-elimination with the Google Python Style Guide.
This change eliminates the "Function And Method Decorators" and
"Power Features" sections and updates the "Threading" section.
"Python Language Rules" is now done! Yay, and on to "Python Style
Rules"...
diff --git a/PythonStyleGuide.wiki b/PythonStyleGuide.wiki
index d42e0e5..716bcd3 100644
--- a/PythonStyleGuide.wiki
+++ b/PythonStyleGuide.wiki
@@ -31,9 +31,7 @@
# [PythonStyleGuide#Imports Imports]: _Import only modules and only by name *(no wildcard imports)*_
# [PythonStyleGuide#Function_Arguments Function Arguments]: _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*_
+ # [PythonStyleGuide#Threading Threading]: _*For now, do not use* (but it is on its way as part of [https://code.google.com/p/soc/issues/detail?id=1596 issue 1596])_
== Python Style Rules ==
@@ -109,76 +107,11 @@
*Decision:* Always pass positional arguments positionally and keyword
arguments by keyword.
-== Function and Method Decorators ==
-
-*What they are:* Decorators for Functions and Methods, added in Python 2.4
-(a.k.a "the `@` notation"). The most common decorators are `@classmethod`
-and `@staticmethod`, for converting ordinary methods to class or static
-methods. However, the decorator syntax allows for user-defined decorators
-as well. Specifically, for some function `myDecorator`, this:
-
-{{{
-class C(object):
- @myDecorator
- def aMethod(self):
- # method body ...
-}}}
-
-is equivalent to:
-
-{{{
-class C(object):
- def aMethod(self):
- # method body ...
- aMethod = myDecorator(aMethod)
-}}}
-
-*Pros:* Elegantly specifies some transformation on a method; the
-transformation might eliminate some repetitive code, enforce invariants, etc.
-
-*Cons:* Decorators can perform arbitrary operations on a function's
-arguments or return values, resulting in surprising implicit behavior.
-Additionally, decorators execute at import time. Failures in decorator code
-are pretty much impossible to recover from.
-
-*Decision:* Use decorators judiciously when there is a clear advantage.
-Decorators should follow the same import and naming guidelines as functions.
-Decorator `__doc__` string should clearly state that the function is a
-decorator. Write unit tests for decorators.
-
-Avoid external dependencies in the decorator itself (e.g. don't rely on
-files, sockets, database connections, etc.), since they might not be
-available when the decorator runs (at import time, perhaps from `pychecker`
-or other tools). A decorator that is called with valid parameters should
-(as much as possible) be guaranteed to succeed in all cases.
-
-Decorators are a special case of "top level code" - see
-[PythonStyleGuide#Main Main] for more discussion.
-
== Threading ==
-Threading
-[http://code.google.com/appengine/kb/general.html#libraries is not available in Google App Engine],
-so do not use it in the SoC framework or Melange web applications.
-
-== Power features ==
-
-*What it is:* Python is an extremely flexible language and gives you
-many fancy features such as metaclasses, access to bytecode, on-the-fly
-compilation, dynamic inheritance, object reparenting, import hacks,
-reflection, modification of system internals, etc.
-
-*Pros:* These are powerful language features. They can make your code
-more compact.
-
-*Cons:* It's very tempting to use these "cool" features when they're not
-absolutely necessary. It's harder to read, understand, and debug code
-that's using unusual features underneath. It doesn't seem that way at
-first (to the original author), but when revisiting the code, it tends
-to be more difficult than code that is longer but is straightforward.
-
-*Decision:* Avoid these features in Melange code. Discuss exceptions on the
-[MailingListsGuidelines#Developer_list developer mailing list].
+Melange as of January 2013 is not thread-safe. Work to support thread safety
+is happening as part of [https://code.google.com/p/soc/issues/detail?id=1596
+issue 1596], but for now avoid threading.
= Python Style Rules =
