### 導航 - [索引](../genindex.xhtml "總目錄") - [模塊](../py-modindex.xhtml "Python 模塊索引") | - [下一頁](inputoutput.xhtml "7. 輸入輸出") | - [上一頁](datastructures.xhtml "5. 數據結構") | -  - [Python](https://www.python.org/) ? - zh\_CN 3.7.3 [文檔](../index.xhtml) ? - [Python 教程](index.xhtml) ? - $('.inline-search').show(0); | # 6. 模塊 如果你從Python解釋器退出并再次進入，之前的定義（函數和變量）都會丟失。因此，如果你想編寫一個稍長些的程序，最好使用文本編輯器為解釋器準備輸入并將該文件作為輸入運行。這被稱作編寫 *腳本* 。隨著程序變得越來越長，你或許會想把它拆分成幾個文件，以方便維護。你亦或想在不同的程序中使用一個便捷的函數， 而不必把這個函數復制到每一個程序中去。 為支持這些，Python有一種方法可以把定義放在一個文件里，并在腳本或解釋器的交互式實例中使用它們。這樣的文件被稱作 *模塊* ；模塊中的定義可以 *導入* 到其它模塊或者 *主* 模塊（你在頂級和計算器模式下執行的腳本中可以訪問的變量集合）。 模塊是一個包含Python定義和語句的文件。文件名就是模塊名后跟文件后綴 `.py` 。在一個模塊內部，模塊名（作為一個字符串）可以通過全局變量 `__name__` 的值獲得。例如，使用你最喜愛的文本編輯器在當前目錄下創建一個名為 `fibo.py` 的文件， 文件中含有以下內容: ``` # Fibonacci numbers module def fib(n): # write Fibonacci series up to n a, b = 0, 1 while a < n: print(a, end=' ') a, b = b, a+b print() def fib2(n): # return Fibonacci series up to n result = [] a, b = 0, 1 while a < n: result.append(a) a, b = b, a+b return result ``` 現在進入Python解釋器，并用以下命令導入該模塊: ``` >>> import fibo ``` 在當前的符號表中，這并不會直接進入到定義在 `fibo` 函數內的名稱；它只是進入到模塊名 `fibo` 中。你可以用模塊名訪問這些函數: ``` >>> fibo.fib(1000) 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 >>> fibo.fib2(100) [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] >>> fibo.__name__ 'fibo' ``` 如果你想經常使用某個函數，你可以把它賦值給一個局部變量: ``` >>> fib = fibo.fib >>> fib(500) 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 ``` ## 6.1. 有關模塊的更多信息 模塊可以包含可執行的語句以及函數定義。這些語句用于初始化模塊。它們僅在模塊 *第一次* 在 import 語句中被導入時才執行。 [1](#id2) (當文件被當作腳本運行時，它們也會執行。) 每個模塊都有它自己的私有符號表，該表用作模塊中定義的所有函數的全局符號表。因此，模塊的作者可以在模塊內使用全局變量，而不必擔心與用戶的全局變量發生意外沖突。另一方面，如果你知道自己在做什么，則可以用跟訪問模塊內的函數的同樣標記方法，去訪問一個模塊的全局變量，`modname.itemname`。 模塊可以導入其它模塊。習慣上但不要求把所有 [`import`](../reference/simple_stmts.xhtml#import) 語句放在模塊（或腳本）的開頭。被導入的模塊名存放在調入模塊的全局符號表中。 [`import`](../reference/simple_stmts.xhtml#import) 語句有一個變體，它可以把名字從一個被調模塊內直接導入到現模塊的符號表里。例如: ``` >>> from fibo import fib, fib2 >>> fib(500) 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 ``` 這并不會把被調模塊名引入到局部變量表里（因此在這個例子里，`fibo` 是未被定義的）。 還有一個變體甚至可以導入模塊內定義的所有名稱: ``` >>> from fibo import * >>> fib(500) 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 ``` 這會調入所有非以下劃線（`_`）開頭的名稱。 在多數情況下，Python程序員都不會使用這個功能，因為它在解釋器中引入了一組未知的名稱，而它們很可能會覆蓋一些你已經定義過的東西。 注意通常情況下從一個模塊或者包內調入 `*` 的做法是不太被接受的， 因為這通常會導致代碼的可讀性很差。不過，在交互式編譯器中為了節省打字可以這么用。 如果模塊名稱之后帶有 `as`，則跟在 `as` 之后的名稱將直接綁定到所導入的模塊。 ``` >>> import fibo as fib >>> fib.fib(500) 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 ``` 這會和 `import fibo` 方式一樣有效地調入模塊， 唯一的區別是它以 `fib` 的名稱存在的。 It can also be used when utilising [`from`](../reference/simple_stmts.xhtml#from) with similar effects: ``` >>> from fibo import fib as fibonacci >>> fibonacci(500) 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 ``` 注解 出于效率的考慮，每個模塊在每個解釋器會話中只被導入一次。因此，如果你更改了你的模塊，則必須重新啟動解釋器， 或者，如果它只是一個要交互式地測試的模塊，請使用 [`importlib.reload()`](../library/importlib.xhtml#importlib.reload "importlib.reload")，例如 `import importlib; importlib.reload(modulename)`。 ### 6.1.1. 以腳本的方式執行模塊 當你用下面方式運行一個Python模塊: ``` python fibo.py <arguments> ``` 模塊里的代碼會被執行，就好像你導入了模塊一樣，但是 `__name__` 被賦值為 `"__main__"`。 這意味著通過在你的模塊末尾添加這些代碼: ``` if __name__ == "__main__": import sys fib(int(sys.argv[1])) ``` 你既可以把這個文件當作腳本又可當作一個可調入的模塊來使用， 因為那段解析命令行的代碼只有在當模塊是以“main”文件的方式執行的時候才會運行: ``` $ python fibo.py 50 0 1 1 2 3 5 8 13 21 34 ``` 如果模塊是被導入的，那些代碼是不運行的: ``` >>> import fibo >>> ``` 這經常用于為模塊提供一個方便的用戶接口，或用于測試（以腳本的方式運行模塊從而執行一些測試套件）。 ### 6.1.2. 模塊搜索路徑 當一個名為 `spam` 的模塊被導入的時候，解釋器首先尋找具有該名稱的內置模塊。如果沒有找到，然后解釋器從 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") 變量給出的目錄列表里尋找名為 `spam.py` 的文件。[`sys.path`](../library/sys.xhtml#sys.path "sys.path") 初始有這些目錄地址: - 包含輸入腳本的目錄（或者未指定文件時的當前目錄）。 - [`PYTHONPATH`](../using/cmdline.xhtml#envvar-PYTHONPATH) （一個包含目錄名稱的列表，它和shell變量 `PATH` 有一樣的語法）。 - 取決于安裝的默認設置 注解 在支持符號鏈接的文件系統上，包含輸入腳本的目錄是在追加符號鏈接后才計算出來的。換句話說，包含符號鏈接的目錄并 **沒有** 被添加到模塊的搜索路徑上。 在初始化后，Python程序可以更改 [`sys.path`](../library/sys.xhtml#sys.path "sys.path")。包含正在運行腳本的文件目錄被放在搜索路徑的開頭處， 在標準庫路徑之前。這意味著將加載此目錄里的腳本，而不是標準庫中的同名模塊。 除非有意更換，否則這是錯誤。更多信息請參閱 [標準模塊](#tut-standardmodules)。 ### 6.1.3. “編譯過的”Python文件 為了加速模塊載入，Python在 `__pycache__` 目錄里緩存了每個模塊的編譯后版本，名稱為 `module.version.pyc` ，其中名稱中的版本字段對編譯文件的格式進行編碼； 它一般使用Python版本號。例如，在CPython版本3.3中，spam.py的編譯版本將被緩存為 `__pycache__/spam.cpython-33.pyc`。此命名約定允許來自不同發行版和不同版本的Python的已編譯模塊共存。 Python根據編譯版本檢查源的修改日期，以查看它是否已過期并需要重新編譯。這是一個完全自動化的過程。此外，編譯的模塊與平臺無關，因此可以在具有不同體系結構的系統之間共享相同的庫。 Python在兩種情況下不會檢查緩存。首先，對于從命令行直接載入的模塊，它從來都是重新編譯并且不存儲編譯結果；其次，如果沒有源模塊，它不會檢查緩存。為了支持無源文件（僅編譯）發行版本， 編譯模塊必須是在源目錄下，并且絕對不能有源模塊。 給專業人士的一些小建議: - 你可以在Python命令中使用 [`-O`](../using/cmdline.xhtml#cmdoption-o) 或者 [`-OO`](../using/cmdline.xhtml#cmdoption-oo) 開關， 以減小編譯后模塊的大小。 `-O` 開關去除斷言語句，`-OO` 開關同時去除斷言語句和 \_\_doc\_\_ 字符串。由于有些程序可能依賴于這些，你應當只在清楚自己在做什么時才使用這個選項。“優化過的”模塊有一個 `opt-` 標簽并且通常小些。將來的發行版本或許會更改優化的效果。 - 一個從 `.pyc` 文件讀出的程序并不會比它從 `.py` 讀出時運行的更快，`.pyc` 文件唯一快的地方在于載入速度。 - [`compileall`](../library/compileall.xhtml#module-compileall "compileall: Tools for byte-compiling all Python source files in a directory tree.") 模塊可以為一個目錄下的所有模塊創建.pyc文件。 - 關于這個過程，[**PEP 3147**](https://www.python.org/dev/peps/pep-3147) \[https://www.python.org/dev/peps/pep-3147\] 中有更多細節，包括一個決策流程圖。 ## 6.2. 標準模塊 Python附帶了一個標準模塊庫，在單獨的文檔Python庫參考（以下稱為“庫參考”）中進行了描述。一些模塊內置于解釋器中；它們提供對不屬于語言核心但仍然內置的操作的訪問，以提高效率或提供對系統調用等操作系統原語的訪問。這些模塊的集合是一個配置選項，它也取決于底層平臺。例如，[`winreg`](../library/winreg.xhtml#module-winreg "winreg: Routines and objects for manipulating the Windows registry. (Windows)") 模塊只在Windows操作系統上提供。一個特別值得注意的模塊 [`sys`](../library/sys.xhtml#module-sys "sys: Access system-specific parameters and functions.")，它被內嵌到每一個Python解釋器中。變量 `sys.ps1` 和 `sys.ps2` 定義用作主要和輔助提示的字符串: ``` >>> import sys >>> sys.ps1 '>>> ' >>> sys.ps2 '... ' >>> sys.ps1 = 'C> ' C> print('Yuck!') Yuck! C> ``` 這兩個變量只有在編譯器是交互模式下才被定義。 `sys.path` 變量是一個字符串列表，用于確定解釋器的模塊搜索路徑。該變量被初始化為從環境變量 [`PYTHONPATH`](../using/cmdline.xhtml#envvar-PYTHONPATH) 獲取的默認路徑，或者如果 [`PYTHONPATH`](../using/cmdline.xhtml#envvar-PYTHONPATH) 未設置，則從內置默認路徑初始化。你可以使用標準列表操作對其進行修改: ``` >>> import sys >>> sys.path.append('/ufs/guido/lib/python') ``` ## 6.3. [`dir()`](../library/functions.xhtml#dir "dir") 函數 內置函數 [`dir()`](../library/functions.xhtml#dir "dir") 用于查找模塊定義的名稱。 它返回一個排序過的字符串列表: ``` >>> import fibo, sys >>> dir(fibo) ['__name__', 'fib', 'fib2'] >>> dir(sys) ['__displayhook__', '__doc__', '__excepthook__', '__loader__', '__name__', '__package__', '__stderr__', '__stdin__', '__stdout__', '_clear_type_cache', '_current_frames', '_debugmallocstats', '_getframe', '_home', '_mercurial', '_xoptions', 'abiflags', 'api_version', 'argv', 'base_exec_prefix', 'base_prefix', 'builtin_module_names', 'byteorder', 'call_tracing', 'callstats', 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_info', 'excepthook', 'exec_prefix', 'executable', 'exit', 'flags', 'float_info', 'float_repr_style', 'getcheckinterval', 'getdefaultencoding', 'getdlopenflags', 'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit', 'getrefcount', 'getsizeof', 'getswitchinterval', 'gettotalrefcount', 'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info', 'intern', 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache', 'platform', 'prefix', 'ps1', 'setcheckinterval', 'setdlopenflags', 'setprofile', 'setrecursionlimit', 'setswitchinterval', 'settrace', 'stderr', 'stdin', 'stdout', 'thread_info', 'version', 'version_info', 'warnoptions'] ``` 如果沒有參數，[`dir()`](../library/functions.xhtml#dir "dir") 會列出你當前定義的名稱: ``` >>> a = [1, 2, 3, 4, 5] >>> import fibo >>> fib = fibo.fib >>> dir() ['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys'] ``` 注意：它列出所有類型的名稱：變量，模塊，函數，等等。 [`dir()`](../library/functions.xhtml#dir "dir") 不會列出內置函數和變量的名稱。如果你想要這些，它們的定義是在標準模塊 [`builtins`](../library/builtins.xhtml#module-builtins "builtins: The module that provides the built-in namespace.") 中: ``` >>> import builtins >>> dir(builtins) ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException', 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning', 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError', 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning', 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False', 'FileExistsError', 'FileNotFoundError', 'FloatingPointError', 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError', 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError', 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError', 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented', 'NotImplementedError', 'OSError', 'OverflowError', 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError', 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning', 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning', 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__', '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs', 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable', 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit', 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass', 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview', 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property', 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars', 'zip'] ``` ## 6.4. 包 包是一種通過用“帶點號的模塊名”來構造 Python 模塊命名空間的方法。 例如，模塊名 `A.B` 表示 `A` 包中名為 `B` 的子模塊。正如模塊的使用使得不同模塊的作者不必擔心彼此的全局變量名稱一樣，使用加點的模塊名可以使得 NumPy 或 Pillow 等多模塊軟件包的作者不必擔心彼此的模塊名稱一樣。 假設你想為聲音文件和聲音數據的統一處理，設計一個模塊集合（一個“包”）。由于存在很多不同的聲音文件格式（通常由它們的擴展名來識別，例如：`.wav`， `.aiff`， `.au`），因此為了不同文件格式間的轉換，你可能需要創建和維護一個不斷增長的模塊集合。 你可能還想對聲音數據還做很多不同的處理（例如，混聲，添加回聲，使用均衡器功能，創造人工立體聲效果）， 因此為了實現這些處理，你將另外寫一個無窮盡的模塊流。這是你的包的可能結構（以分層文件系統的形式表示）： ``` sound/ Top-level package __init__.py Initialize the sound package formats/ Subpackage for file format conversions __init__.py wavread.py wavwrite.py aiffread.py aiffwrite.py auread.py auwrite.py ... effects/ Subpackage for sound effects __init__.py echo.py surround.py reverse.py ... filters/ Subpackage for filters __init__.py equalizer.py vocoder.py karaoke.py ... ``` 當導入這個包時，Python搜索 `sys.path` 里的目錄，查找包的子目錄。 必須要有 `__init__.py` 文件才能讓 Python 將包含該文件的目錄當作包。 這樣可以防止具有通常名稱例如 `string` 的目錄在無意中隱藏稍后在模塊搜索路徑上出現的有效模塊。 在最簡單的情況下，`__init__.py` 可以只是一個空文件，但它也可以執行包的初始化代碼或設置 `__all__` 變量，具體將在后文介紹。 包的用戶可以從包中導入單個模塊，例如: ``` import sound.effects.echo ``` 這會加載子模塊 `sound.effects.echo` 。但引用它時必須使用它的全名。 ``` sound.effects.echo.echofilter(input, output, delay=0.7, atten=4) ``` 導入子模塊的另一種方法是 ``` from sound.effects import echo ``` 這也會加載子模塊 `echo` ，并使其在沒有包前綴的情況下可用，因此可以按如下方式使用: ``` echo.echofilter(input, output, delay=0.7, atten=4) ``` 另一種形式是直接導入所需的函數或變量: ``` from sound.effects.echo import echofilter ``` 同樣，這也會加載子模塊 `echo`，但這會使其函數 `echofilter()` 直接可用: ``` echofilter(input, output, delay=0.7, atten=4) ``` 請注意，當使用 `from package import item` 時，item可以是包的子模塊（或子包），也可以是包中定義的其他名稱，如函數，類或變量。 `import` 語句首先測試是否在包中定義了item；如果沒有，它假定它是一個模塊并嘗試加載它。如果找不到它，則引發 [`ImportError`](../library/exceptions.xhtml#ImportError "ImportError") 異常。 相反，當使用 `import item.subitem.subsubitem` 這樣的語法時，除了最后一項之外的每一項都必須是一個包；最后一項可以是模塊或包，但不能是前一項中定義的類或函數或變量。 ### 6.4.1. 從包中導入 \* 當用戶寫 `from sound.effects import *` 會發生什么？理想情況下，人們希望這會以某種方式傳遞給文件系統，找到包中存在哪些子模塊，并將它們全部導入。這可能需要很長時間，導入子模塊可能會產生不必要的副作用，這種副作用只有在顯式導入子模塊時才會發生。 唯一的解決方案是讓包作者提供一個包的顯式索引。[`import`](../reference/simple_stmts.xhtml#import) 語句使用下面的規范：如果一個包的 `__init__.py` 代碼定義了一個名為 `__all__` 的列表，它會被視為在遇到 `from package import *` 時應該導入的模塊名列表。在發布該包的新版本時，包作者可以決定是否讓此列表保持更新。包作者如果認為從他們的包中導入 \* 的操作沒有必要被使用，也可以決定不支持此列表。例如，文件 `sound/effects/__init__.py` 可以包含以下代碼: ``` __all__ = ["echo", "surround", "reverse"] ``` 這意味著 `from sound.effects import *` 將導入 `sound` 包的三個命名子模塊。 如果沒有定義 `__all__`，`from sound.effects import *` 語句 *不* 會從包 `sound.effects` 中導入所有子模塊到當前命名空間；它只確保導入了包 `sound.effects` （可能運行任何在 `__init__.py` 中的初始化代碼），然后導入包中定義的任何名稱。這包括 `__init__.py`` 定義的任何名稱（以及顯式加載的子模塊）。它還包括由之前的 [`import`](../reference/simple_stmts.xhtml#import) 語句顯式加載的包的任何子模塊。思考下面的代碼: ``` import sound.effects.echo import sound.effects.surround from sound.effects import * ``` 在這個例子中， `echo` 和 `surround` 模塊是在執行 `from...import` 語句時導入到當前命名空間中的，因為它們定義在 `sound.effects` 包中。（這在定義了 `__all__` 時也有效。） 雖然某些模塊被設計為在使用 `import *` 時只導出遵循某些模式的名稱，但在生產代碼中它仍然被認為是不好的做法。 請記住，使用 `from package import specific_submodule` 沒有任何問題！ 實際上，除非導入的模塊需要使用來自不同包的同名子模塊，否則這是推薦的表示法。 ### 6.4.2. 子包參考 當包被構造成子包時（與示例中的 `sound` 包一樣），你可以使用絕對導入來引用兄弟包的子模塊。例如，如果模塊 `sound.filters.vocoder` 需要在 `sound.effects` 包中使用 `echo` 模塊，它可以使用 `from sound.effects import echo` 。 你還可以使用import語句的 `from module import name` 形式編寫相對導入。這些導入使用前導點來指示相對導入中涉及的當前包和父包。例如，從 `surround` 模塊，你可以使用: ``` from . import echo from .. import formats from ..filters import equalizer ``` 請注意，相對導入是基于當前模塊的名稱進行導入的。由于主模塊的名稱總是 `"__main__"` ，因此用作Python應用程序主模塊的模塊必須始終使用絕對導入。 ### 6.4.3. 多個目錄中的包 包支持另一個特殊屬性， [`__path__`](../reference/import.xhtml#__path__ "__path__") 。它被初始化為一個列表，其中包含在執行該文件中的代碼之前保存包的文件 `__init__.py` 的目錄的名稱。這個變量可以修改；這樣做會影響將來對包中包含的模塊和子包的搜索。 雖然通常不需要此功能，但它可用于擴展程序包中的模塊集。 腳注 [1](#id1)實際上，函數定義也是“被執行”的“語句”；模塊級函數定義的執行在模塊的全局符號表中輸入該函數名。 ### 導航 - [索引](../genindex.xhtml "總目錄") - [模塊](../py-modindex.xhtml "Python 模塊索引") | - [下一頁](inputoutput.xhtml "7. 輸入輸出") | - [上一頁](datastructures.xhtml "5. 數據結構") | -  - [Python](https://www.python.org/) ? - zh\_CN 3.7.3 [文檔](../index.xhtml) ? - [Python 教程](index.xhtml) ? - $('.inline-search').show(0); | ? [版權所有](../copyright.xhtml) 2001-2019, Python Software Foundation. Python 軟件基金會是一個非盈利組織。 [請捐助。](https://www.python.org/psf/donations/) 最后更新于 5月 21, 2019. [發現了問題](../bugs.xhtml)？ 使用[Sphinx](http://sphinx.pocoo.org/)1.8.4 創建。