什麼是最好的Python庫模塊框架代碼？

Question

許多蟒蛇的IDE將啓動你喜歡的模板：

print 'hello world' 

這還不夠......因此，這裏是我的骨架代碼得到這個問題開始：

我的模塊骨架，短版本：

#!/usr/bin/env python 

""" 
Module Docstring 
""" 

# 
## Code goes here. 
# 

def test(): 
    """Testing Docstring""" 
    pass 

if __name__=='__main__': 
    test() 

，並

我的模塊骨架，長的版本：

#!/usr/bin/env python 
# -*- coding: ascii -*- 

""" 
Module Docstring 
Docstrings: http://www.python.org/dev/peps/pep-0257/ 
""" 

__author__ = 'Joe Author (joe.author@website.org)' 
__copyright__ = 'Copyright (c) 2009-2010 Joe Author' 
__license__ = 'New-style BSD' 
__vcs_id__ = '$Id$' 
__version__ = '1.2.3' #Versioning: http://www.python.org/dev/peps/pep-0386/ 

# 
## Code goes here. 
# 

def test(): 
    """ Testing Docstring""" 
    pass 

if __name__=='__main__': 
    test() 

注（PEP 8，UTF-8）：

""" 
===MODULE TYPE=== 
Since the vast majority of my modules are "library" types, I have constructed 
this example skeleton as such. For modules that act as the main entry for 
running the full application, you would make changes such as running a main() 
function instead of the test() function in __main__. 

===VERSIONING=== 
The following practice, specified in PEP 8, no longer makes sense: 

    __version__ = '$Revision: 1.2.3 $' 

For two reasons: 
    (1) Distributed version control systems make it neccessary to include more 
     than just a revision number. E.g. author name and revision number. 
    (2) It's a revision number not a version number. 


Instead, the __vcs_id__ variable is being adopted. This expands to, for 
example: 
    __vcs_id__ = '$Id: example.py,v 1.1.1.1 2001/07/21 22:14:04 goodger Exp $' 


===VCS DATE=== 
Likewise, the date variable has been removed: 

    __date__ = '$Date: 2009/01/02 20:19:18 $' 


===CHARACTER ENCODING=== 
If the coding is explicitly specified, then it should be set to the default 
setting of ASCII. This can be modified if necessary (rarely in practice). 
Defaulting to UTF-8 can cause anomalies with editors that have poor unicode 
support. 

""" 

替代骨架，長的版本：（代碼改編自DasIch的答案）

#!/usr/bin/env python 
# -*- coding: ascii -*- 

""" 
package.module 
~~~~~~~~~~~~~ 

A description which can be long and explain the complete 
functionality of this module even with indented code examples. 
Class/Function however should not be documented here. 

:copyright: year by my name, see AUTHORS for more details 
:license: license_name, see LICENSE for more details 
""" 

# 
## Code goes here. 
# 

def test(): 
    """ """ 
    pass 

if __name__=='__main__': 
    test() 

有很多政治公衆人物的提出編碼風格建議。我是否錯過了任何重要的最佳實踐？什麼是最好的Python模塊框架代碼？

更新

給我任何類型的，你喜歡的「最佳」。告訴我們您用什麼指標來評估「最佳」。

Answer 1

#!/usr/bin/env python 
# coding: utf-8 
""" 
    package.module 
    ~~~~~~~~~~~~~ 

    A description which can be long and explain the complete 
    functionality of this module even with indented code examples. 
    Class/Function however should not be documented here. 

    :copyright: year by my name, see AUTHORS for more details 
    :license: license_name, see LICENSE for more details 
""" 

模塊可能會或可能不會包含main功能，所以這不是模板的一部分。

Answer 2

根據程序的性質，您可以考慮選擇許可證並將其放在文件的開頭。

Answer 3

它往往是可取的設定

#coding=<coding> 

在第二行。像

#coding=utf8 

例如。這是詳細的替代方案

# -*- coding: <encoding name> -*- 

有關更多信息，請參閱PEP-263。

---

編輯完整答案：取決於情況。如果對於一些內部項目來說，簡單就好一點。但是，我幾乎總是有

def main(): 
    #code 
    pass 

if __name__=="__main__": 
    main() 

如果我打算公佈的代碼，我添加適當的文件和許可條款以及所提到的編碼指令。

shebang（#!/usr/bin/env python）僅適用於本意爲可執行文件的文件。

Answer 4

返回的東西是最好的做法太（這裏稱爲參數）：

... 
import sys 

def main(args): 
    return 0 

if __name__=='__main__': 
    sys.exit(main(sys.argv)) 

但它變得比簡單的「hello world」更復雜。

Answer 5

更妙的是，這裏是提圖斯布朗博士建議的封裝佈局：

http://github.com/ctb/SomePackage

Answer 6

如何：

... 
import sys 

def main(*args): 
    return 0 

if __name__=='__main__': 
    sys.exit(main(*sys.argv[1:])) 

那麼你當然修改骨架主要以反映實際參數（文件名後）：

def main(arg1, arg2, *args): 
    ... 

（驚訝我們不能在評論中使用降價...）

Answer 7

我會說最好的是最簡單的比滿足您的要求。您投入「骨架」的數據越多，您可能會獲得的數據越陳舊或無意義或錯誤。

• if __name__=='__main__':零件在模塊中不需要，只是一個模塊。測試可能是模塊的一部分，但即使如此，它們也可以被稱爲外部。直接調用模塊通常很不方便（或者不可能，例如，當使用相對導入時）。
• Python解釋器通常會說需要編碼信息的時候，並不是每一個代碼都需要非ASCII字符。

合理的最低恕我直言是模塊開頭的文檔字符串。在你的問題和其他答案中提到的其他作品也常常有用，但決不是強制性的。

Answer 8

模塊不可執行，所以他們不應該有一個shebang。

Docstrings很好。

編碼是有用的。

作爲包裝元數據的一部分，元數據（如作者，版權，版本和許可證最好存儲在setup.py中）。使用__(metadata)__模塊屬性是一個過時的做法，因爲它早於Python打包元數據的時間。如果代碼具有足夠的短暫性而不保證打包，那麼您將需要任何元數據是不可靠的。

其他功能，如test（）或__main__黑客我沒有足夠的使用以保證包含在模塊模板中。

因此唯一需要的模板是：

# -*- coding: ascii -*- 
""" 
""" 

尼斯和簡單。