需要適用於python軟件包的正確目錄結構以及有關良好API設計的准則

Question

我正在發布python軟件包，並對包裝的各個方面感到困惑。

首先，我的目錄結構如下：

SamplePackage/
 - setup.py
 - README.rst
 - LICENSE.rst
 - sampledir/
    -__init__.py
    -sample.py
    -utils.py

當前__init__和setup尚未填充。 sample.py是軟件包的任何用戶都想要導入的文件。 它包含具有不同功能形式的api： foo1 ， foo2 。

utils.py包含幫手小說smaple.py 。 后者包含一條語句import utils

放在sampledir目錄下的任何腳本都可以輕松import sample並將小說用作sample.foo1() 。 退出該目錄，我可以調用import sampledir ，但不能調用import sample ，這是預期的。 所以我需要from sampledir import sample 。 這導致sample.py的import utils行出現錯誤

ImportError: No module named 'utils'

在某些地方，我看到了在同一目錄中import .utils文件的信息。 但是，當我嘗試這樣做時，會導致語法錯誤。

為什么我不能從sampledir外部導入sample.py ？

同樣，什么樣的目錄結構將允許已安裝軟件包的用戶能夠簡單地調用import sample然后調用sample.foo1() ，而不必from sampledir import sample或import sampeldir.sample 。 例如，在使用HTTP庫requests ，只需將其導入並調用requests.get(url) 。 像在urllib一樣，不需要urllib requests.requests.get('url') 。 如果我想將該包命名為sample ，那么實現該目的的正確目錄命名和安排是什么？

Answer 1

首先，我想你誤解了包和項目之間的區別。 您的目錄結構應該是這樣的

arbitrary_name_of_project/
 - setup.py
 - README.rst
 - LICENSE.rst
 - package_name/
    -__init__.py
    -sample.py
    -utils.py

存在文件__init__.py來“標記” Python軟件包。 Python在他的PYTHONPATH上搜索，並尋找文件__init__.py所有目錄（簡單地說，實際上要復雜得多）。 這些是您可以在運行時導入的程序包。

在我們的情況下，僅package_name目錄將安裝在PYTHONPATH某個位置。 因此，安裝完成后（通過setup.py和disutils或setuptools ），您可以輸入

import package_name

現在，您可以從此包中的任何模塊調用任意類或函數，或諸如此類

package_name.sample.func1()

如果要避免在調用中鍵入package_name.sample ，可以將此行放在__init__.py

from .sample import func1

然后，在“導入時間”期間將函數func1放入您的全局名稱空間。 在程序中執行import package_name時，會發生這種情況。 可以通過每次導入包時都執行__init__.py文件這一事實來解決此問題。

有時有必要吐更多的東西。 您可以具有“嵌套”包（即，需要導入的包中的包）。 還有名稱空間包，您可以在其中將一個包“吐”到更多目錄中。 世界是多元化的。 :)

免責聲明

我寫的是沒有測試我提供的代碼。 可能會有小的錯別字，但我希望這個故事或多或少是正確的。 請，如果我錯了，請糾正我。