在语言要求的地方注释，以标准的注释语法。
注释说明必要的信息，
适当的设计思路描述
适当的算法设计描述

文档化的工具：
    1. epydoc:
        纯Python实现。
        与Python的结合非常自然，稳定，可扩展。
       
    2. DoxyGen.
   
epydoc标签规范：
    1. py文献信息：
        @author:   ...作者
        @license:  ...版权
        @contact:  ...联系
       
    2. py状态信息：
        @version:  ...版本推荐使用$Id$
        @todo[ver]:...改进，可以指定针对的版本
       
    3. py模块信息：
        @var v: ...模块变量v说明
        @type v: ...模块变量类型v说明
       
    4. py函数信息：
        @param p: ...参数p说明
        @type p: ...参数p类型说明
        @return: ...返回值说明
        @rtype: ...返回值类型说明
       
    5. py提醒信息：
        @note: ...注解
        @attention: ...注意
        @bug: ... 问题
        @warning: ...警告
       
    6. py关联信息：
        @see: ...参考资料
       
    7. py注释风格：

 1#xxxx.py文件模板
 2'''
 3@version: $Id$
 4@author: U{username<mailto: email_address>}
 5@see: 资料
 6'''
 7
 8import sys, os, other
 9
10class Templates(object):
11    '''
12    类说明
13    '''
14    def __init__(self, param1):
15        '''
16        @param param1: 注释内容。
17         @type param1: 介绍。
18         @return: 返回简介。
19         @rtype v： 返回类型简介。
20         '''
21        self.param1 = param1

@A

def f():

Python最后会处理为：

f = A(f)

，可扩展为：

@A
@B
@C
def f():

最终Python会处理为:

f = A(B(C(f)))

2.带参数：

@A(args)
def f():

Python会处理为：

def f();
  _deco = A(args)
  f = _deco(f)

Python先执行A(args)得到_deco，然后跟第一种方式一样的处理函数f。


对应的两种函数定义方法：
第一种：

def A(func):
  #处理func
  #如func.attr='decorated'
  return func

@A
def f(args): pass

A对f处理完后，仍返回函数对象。 如果要返回一个新的函数，可以为：

def A(func):
  #做额外的工作
  def new_func(args):
    #做额外工作
    return func(args)  
  return new_func

@A
def f(args): pass

注意：new_func的定义形式要和待处理的函数相同。

如果想根据原来函数的结果进行一些处理：

def A(func):
  def new_func(*args, **argkw):
    result = func(*args, **argkw)
    if result:
      return new_result
    else:
      return result
  return new_func

@A
def f(args): pass

第二种： 

def A(arg):
  def _A(func):
    def new_func(args):
      #do any operation
      return func(args)
    return new_func
  return _A

@A(arg)
def f(args): pass

文档上说：如果你的decorator在调用时使用了参数，那么你的decorator函数只会使用这些参数进行调用。因此你需要返回一个新的decorator函数，就和第一种方式定义形式一致了。

Deferreds - a signal that data is yet to come
In our email sending example above, a parent functions calls a function to connect to the remote server. Asynchrony requires that this connection function return without waiting for the result so that the parent function can do other things. So how does the parent function or its controlling program know that the connection doesn't exist yet, and how does it use the connection once it does exist?
Twisted has an object that signals this situation. When the connection function returns, it signals that the operation is imcomplete by returning a twisted.internet.defer.Deferred object.
The Deferred has two purposes. The first is that it says "I am a signal that the result of whatever you wanted me to do is still pending.". The second is that you can ask the Deferred to run things when the data does arrive.

Callbacks
The way you tell a Deferred what to do with the data once it arrives is by adding a callback - asking the Deferred to call a function once the data arrives.
One Twisted library function that returns a Deferred is twisted.web.client.getPage. In this example, we call getPage, which returns a Deferred, and we attach a callback to handle the contents of the page once the data is available:

from twisted.web.client import getPage
from twisted.internet import reactor

def printContents(contents):
   '''
   This is the 'callback' function, added to the Deferred and called by it when the promised data is available
 '''
 print "The Deferred has called printContents with the following contents:"
 print contents
 
 #Stop the Twisted event handling system -- this is usually handled
 #in higher lever ways
 reactor.stop()
 
#call getPage, which returns immediately with a Deferred, promissing to
#pass the page contents onto our callbacks when the contents are available
deferred = getPage('http://www.google.com')

#added a callback to the deferred -- request that it run printContents when
#the page content has been downloaded
deferred.addCallback(printContents)

#Begin the Twisted event handling system to manage the process -- again
# this isn't the usual way to do this
reactor.run()

A very common use of Deferreds is to attach two callbacks. The result of the first callback is passed to the second callback:

from twisted.web.client import getPage
from twisted.internet import reactor

def lowerCaseContents(contents):
 '''
 This is a 'callback' function, added to the Deferred and called by
 it when the promised data is available. It converts all the data to lower case.
 '''
 return contents.lower()
 
def printContents(contents):
 '''
 This a 'callback' function, added to the Deferred after lowerCaseContents
 and called by it with the results of lowerCaseContents
 '''
 print contents
 reactor.stop()
 
deferred = getPage('http://www.google.com')

#add two callbacks to the deferred -- request that it run lowerCaseContents
#when the page content has been downloaded, and then run printContents with
#the result of lowerCaseContents
deferred.addCallback(lowerCaseContents)
deferred.addCallback(printContents)

reactor.run()

Error handling: errbacks
Just as a asynchronous function returns before its result is available, it may also return before it is possible to detect errors: failed connections, erroneous data, protocol errors, and so on. Just as you can add callbacks to a Deferred which it calls when the data you are expecting is available, you can add error handlers(errbacks) to a Deferred for it to call when an error occurs and it cannot obtain the data:

from twisted.web.client import getPage
from twisted.internet import reactor

def errorHandler(err):
 '''
 This is an 'errback' function, added to the Deferred which will call it in the event of an error
 '''
 
 #this isn't a very effective handling of the error, we just print it out:
 print "An error has occurred: <%s>" % str(err)
 #and then we stop the entire process:
 reactor.stop()
 
def printContents(contents):
 '''
 This is a 'callback' function, added to the Deferred and called by it which the page content
 '''
 print contents
 reactor.stop()
 
#we request a page which doesn't exist in order to demonstrate the
#error chain
deferred = getPage("http://www.google.com/does-not-exits")

#add the callback to the Deferred to handle the page content
deferred.addCallback(printContents)

#add the errback to the Deferred to handle any errors
deferred.addErrback(errorHandler)

reactor.run()

3. 一切皆为对象，对象都有名字。

4. 基本数据类型和c/c++相像，但是1 == 1.0, 原因：float和int比较时，会把int转为long, 再把long转为double，float也被转为double。

5. None是特殊变量。跟C中的NULL不完全一样。

6. bool型，很多的情况都可以作为false，如0， 0.0，[], {}, None等。感觉不错，这个世界就应该把是和非直接平衡些。

7. IndentationError: expected an indented block: 缩进问题。

9. list列表，叫什么都无所谓，数组， Vector都行。

10.list一个特别的地方，可以使用负数索引。

11.list常用操作：
  list的截取： a[3:5], a[3:], a[:]
  list的追加： a.append(var)
  某个元素在list出现的次数: a.count(var)
  list长度： len(list)
  list追加一个list： a.extend(list)
  返回某元素在list中的位置： a.index(var)
  list中插入： a.insert(index, var)
  list弹出最后或指定位置的元素： a.pop(), a.pop(index)
  list找到某值，删除之： a.remove(var)
  list中倒次序： a.reverse()
  list排序： a.sort()， a.sort(func),使用func(x, y)作为规则排序
 
12.很好玩的一个东西：
  [<expr1> for k in L if <expr2>]
  例子： [k + 1 for k in a if type(k) == types.IntType]
 
16. 序列sequence
  sequence就是list，string，tuple的总称。
  它们之间的共性就是以下操作：
   (a). in判断某个object是否在sequence中。
   (b). len取得sequence的长度
   (c). 可以使用下标操作：sequence[i]
   (d). 取子sequence用sequence[start:end],
      取得的子sequence下标为[start, start+1,...,end-1],不是到end结束。
   (e). 用+号可以连接sequence.
   (f). 用乘号*可以重复几个sequence.
   (g). 可以使用list comprehension: [<expr1> for k in L if <expr2>]
  
22. 函数参数的设置
  (a). 默认参数
  (b). 参数个数可变： **对应dictionary，*对应tuple。
     例如：def printf(format, *args), 调用方式: printf("%d,%d", 1, 3)
     而：
     def printf(format, **args),调用方式：printf("ok", One=1, Two=2, Three=3)
     注意： **和*参数必须为最后一个参数。
    
25. 函数的作用域： LGB准则就是Python找变量的次序： Local - Global - Build-in

26. 函数可以嵌套，但内部的函数不能访问外部的变量。

1import unittest
2
3class DefaultWidgetSizeTestCase(unittest.TestCase):
4  def runTest(self):
5    widget = Widget('The widget')
6    self.assertEqual(widget.size(), (50, 50), 'incorrect default size')

testcase = DefaultWidgetSizeTestCase()

Now, such test cases can be numerous, and their set-up can be repetitive. In the above case, constructin a Widget in each of 100 Widget test case subclass would mean unsightly duplication.

luckily, we can factor out such set-up code by implementing a method called setU(), which the testing framework will automatically call for us when we run the test:

 1import unittest
 2
 3class SimpleWidgetTestCase(unittest.TestCase):
 4  def setUp(self):
 5    self.widget = Widget('The widget')
 6
 7class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
 8  def runTest(self):
 9    self.failUnless(self.widget.size() == (50, 50), 'incorrect default size')
10
11class WidgetResizeTestCase(SimpleWidgetTestCase):
12  def runTest(self):
13    self.widget.resize(100, 150)
14    self.failUnless(self.widget.size() == (100, 150), 'wrong size after resize')

If the setUp() method raises an exception while the test is running, the framework will consider that test to have suffered an error, and the runTest() method will not be executed.

Similarly, we can provide a tearDown() method that tidies up after the runTest() method has been run:

1import unittest
2
3class SimpleWidgetTestCase(unittest.TestCase):
4  def setUp(self):
5    self.widget = Widget('The widget')
6
7  def tearDown(self):
8    self.widget.dispose()
9    self.widget = None

If setUp() succeeded, the tearDown() method will be run whether runTest() succeeded or not.

Such a working environment for the testing code is called a fixture.

Often, many small test cases will use the same fixture. In this case, we would end up subclassing SimpleWidgetTestCase into many small one-method classed such as DefaultWidgetSizeTestCase. This is time-consuming and discouraging,  so in the same vein as JUnit, unittest provides a simpler mechanism:

 1import unittest
 2
 3class WidgetTestCase(unittest.TestCase):
 4  def setUp(self):
 5    self.widget = Widget('The widget')
 6
 7  def tearDown(self):
 8    self.widget.dispose()
 9    self.widget = None
10
11  def testDefaultSize(self):
12    self.failUnless(self.widget.size() == (50, 50), 'incorrect default size')
13
14  def testResize(self):
15    self.widget.resize(100, 150)
16    self.failUnless(self.widget.size() == (100, 150), 'wrong size after resize')

Here we have not provided a runTest() method, but have instead provided two different test methods. Class instances will now each run one of the test*() methods, with self.widget created and destroyed separately for each instance. When creating an instance we must specify the test method it is to run. We do this by passing the method name in the constructor:

defaultSizeTestCase = WidgetTestCase('testDefaultSize')

resizeTestCase = WidgetTestCase('testResize')

Test case instances are grouped together according to the features they test. unittest provides a mechanism for this: the test suite, represented by unittest's TestSuite class:

widgetTestSuite = unittest.TestSuite()
widgetTestSuite.addTest(WidgetTestCase('testDefaultSize'))
widgetTestSuite.addTest(WidgetTestCase('testResize'))

For the ease of running tests, as we will see later, it is a good idea to provide in each test module a callable object that returns a pre-built test suite:

def suite():
  suite = unittest.TestSuite()
  suite.addTest(WidgetTestCase('testDefaultSize'))
  suite.addTest(WidgetTestCase('testResize'))
  return suite

or even:

def suite():
  tests = ['testDefaultSize', 'testResize']
  return unittest.TestSuite(map(WidgetTestCase, tests))

Since it is a common pattern to create a TestCase subclass with many similarly named test functions, unittest provides a TestLoader class that can be used to automate the process of creating a test suite and populating it with individual tests. For example,

suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)

will create a test suite that will run WidgetTestCase.testDefaultSize() and WidgetTestCase.testResize(). TestLoader use the 'test' method name prefix to identify test methods automatically.

Note that the order in which the various test cases will be run is determined by sorting the function names with the built-in cmp() function.

Often it is desirable to group suites of test cases together, so as to run tests for the whole system at once. This is easy, since TestSuite instances can be added to a TestSuite just as TestCase instances can be added to a TestSuite.

suite1 = module1.TheTestSuite()
suite2 = module2.TheTestSuite()
alltests = unittest.TestSuite([suite1. suite2])

You can place the definitions of test cases and test suites in the same modules as the code they are to test(such as widget.py), but there are several advantages to placing the test code in a separate module, such as test_widget.py.

• The test module can be run standalone from the command line.
• The test code can more easily be separated from shipped code.
• There is less temptation to change test code to fit the code it tests without a good reason.
• Test code should be modified much less frequently than the code it tests.
• Tested code can be refactored more easily.
• Tests for modules written in C must be in separate modules anyway, so why not be consistent?
• If the testing strategy changes, there is no need to change the source code.

 1import random
 2import unittest
 3
 4class TestSequenceFunctions(unittest.TestCase):
 5  def setUp(self):
 6    self.seq = range(10)
 7 
 8  def testshuffle(self):
 9    #make sure the shuffled sequence does not
10    #lose any elements
11    random.shuffle(self.seq)
12    self.seq.sort()
13    self.assertEqual(self.seq, range(10))
14
15  def testchoice(self):
16    element = random.choice(self.seq)
17    self.assert_(element in self.seq)
18
19  def testsample(self):
20    self.assertRaises(ValueError, random.sample, self.seq, 20)
21    for element in random.sample(self.seq, 5):
22      self.assert_(element in self.seq)
23
24if __name__ == '__main__':
25  unittest.main()
26

A testcase is created by subclassing unittest.TestCase. The thress individual tests are defined with methods whose names start with the letters "test". This nameing convention informs the test runner about which methods represent tests.
The crux of each tests is a call to assertEqual() to check for an expected result; assert_() to verify a condition; or assertRaises() to verify that an expected exception gets raised. These methods are used instead of the assert statement so the test runner can accumulate all test results and produce a report.
When a setUp() method is defined, the test runner will run that method prior to each test. Likewise, if a tearDown() method is defined, the test runner wil invoke that method after each test. In the example,setUp() was used to create a fresh sequence for each test.
The final block shows a simple way to run the tests. unittest.main() provides a command line interface to the test script. When run from the command line, the above script produces an output that looks like this:
...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

Instead of unittest.main(), there are other ways to run the tests with a finer level of control, less terse output, and no requirement to be run from the command line. For example, the last two line may be replaced with:

suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions)
unittest.TextTestRunner(verbosity=2).run(suite)

Running the revised script from the interpreter or another script produces the following output:
testchoice (__main__.TestSequenceFunctions) ... ok
testsample (__main__.TestSequenceFunctions) ... ok
testshuffle (__main__.TestSequenceFunctions) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.110s

OK

The above examples show the most commonly used unittest features which are sufficient to meet many everyday testing needs. The remainder of the documentation explores the full feature set from first principles.

线程相对进程来说是“轻量级”的，操作系统用较少的资源创建和管理线程。程序中的线程在相同的内存空间中执行，并共享许多相同的资源。

在python中如何创建一个线程对象

如果你要创建一个线程对象，很简单，只要你的类继承threading.Thread，然后在__init__里首先调用threading.Thread的__init__方法即可

import threading
class mythread(threading.Thread):
def __init__(self, threadname):
threading.Thread.__init__(self, name = threadname)
....

这才仅仅是个空线程，我可不是要他拉空车的，他可得给我干点实在活。很简单，重写类的run()方法即可，把你要在线程执行时做的事情都放到里面

import threading
import time
class mythread(threading.Thread):
def __init__(...):
....
def run(self):
for i in range(10):
print self.getName, i
time.sleep(1)

以上代码我们让这个线程在执行之后每隔1秒输出一次信息到屏幕，10次后结束

getName()是threading.Thread类的一个方法，用来获得这个线程对象的name。还有一个方法setName()当然就是来设置这个线程对象的name的了。

如果要创建一个线程，首先就要先创建一个线程对象

mythread1 = mythread('mythread 1')

一个线程对象被创建后，他就处于“born”（诞生状态）

如何让这个线程对象开始运行呢?只要调用线程对象的start()方法即可

mythread1.start()

现在线程就处于“ready”状态或者也称为“runnable”状态。

奇怪吗？不是已经start了吗？为什么不称为“running”状态呢？其实是有原因的。因为我们的计算机一般是不具有真正并行处理能力的。我们所谓的多线程只是把时间分成片段，然后隔一个时间段就让一个线程执行一下，然后进入“sleeping ”状态，然后唤醒另一个在“sleeping”的线程，如此循环runnable->sleeping->runnable... ，只是因为计算机执行速度很快，而时间片段间隔很小，我们感受不到，以为是同时进行的。所以说一个线程在start了之后只是处在了可以运行的状态，他什么时候运行还是由系统来进行调度的。

那一个线程什么时候会“dead”呢？一般来说当线程对象的run方法执行结束或者在执行中抛出异常的话，那么这个线程就会结束了。系统会自动对“dead”状态线程进行清理。

如果一个线程t1在执行的过程中需要等待另一个线程t2执行结束后才能运行的话那就可以在t1在调用t2的join()方法

....
def t1(...):
...
t2.join()
...

这样t1在执行到t2.join()语句后就会等待t2结束后才会继续运行。

但是假如t1是个死循环的话那么等待就没有意义了，那怎么办呢？可以在调用t2的join()方法的时候给一个浮点数做超时参数，这样这个线程就不会等到花儿也谢了了。我等你10s，你不回来我还不允许我改嫁啊？:)

def t1(...):
...
t2.join(10)
...

如果一个进程的主线程运行完毕而子线程还在执行的话，那么进程就不会退出，直到所有子线程结束为止，如何让主线程结束的时候其他子线程也乖乖的跟老大撤退呢？那就要把那些不听话的人设置为听话的小弟，使用线程对象的setDaemon()方法，参数为bool型。True的话就代表你要听话，我老大（主线程）扯呼，你也要跟着撤，不能拖后腿。如果是False的话就不用那么听话了，老大允许你们将在外军命有所不受的。需要注意的是setDaemon()方法必须在线程对象没有调用start()方法之前调用，否则没效果。

t1 = mythread('t1')
print t1.getName(),t1.isDaemon()
t1.setDaemon(True)
print t1.getName(),t1.isDaemon()
t1.start()
print 'main thread exit'

当执行到 print 'main thread exit' 后，主线程就退出了，当然t1这个线程也跟着结束了。但是如果不使用t1线程对象的setDaemon()方法的话，即便主线程结束了，还要等待t1线程自己结束才能退出进程。isDaemon()是用来获得一个线程对象的Daemonflag状态的。

如何来获得与线程有关的信息呢？

获得当前正在运行的线程的引用

running = threading.currentThread()

获得当前所有活动对象（即run方法开始但是未终止的任何线程）的一个列表

threadlist = threading.enumerate()

获得这个列表的长度

threadcount = threading.activeCount()

查看一个线程对象的状态调用这个线程对象的isAlive()方法，返回1代表处于“runnable”状态且没有“dead”

threadflag = threading.isAlive()