查看“Python 官方简明教程 6”的源代码

=-6. 模块 Modules（未翻译，欢迎大家参与翻译）=
'''感谢“[http://www.pydn.cn/forum.php 中译社]”翻译本页（尚未校对），欢迎大家到[http://www.pydn.cn/forum.php Python开发者网络PYDN]参加 Pythn 3.2 文档的翻译工作'''

如果你从Python解释器退出再进入，那么你定义的所有的方法和变量就都消失了。所以，如果你想写一个能保存长一点的程序，你最好使用一个文本编辑器保存这些代码，把保存好的文件作为Python解释器的输入。这就是传说中的”脚本”。当你的程序能够长时间保存了，你就更加希望把他们（按照某种形式）拆分以便于管理。你可能还需要有个办法，在不同的程序中方便的调用，而不是把一坨代码拷来拷去。
If you quit from the Python interpreter and enter it again, the definitions you have made (functions and variables) are lost. Therefore, if you want to write a somewhat longer program, you are better off using a text editor to prepare the input for the interpreter and running it with that file as input instead. This is known as creating a script. As your program gets longer, you may want to split it into several files for easier maintenance. You may also want to use a handy function that you’ve written in several programs without copying its definition into each program.

为此 Python 提供了一个办法，把这些定义存放在文件中，为一些脚本或者交互式的解释器实例使用。这个文件被称为*模块*，模块中的定义可以被*导入*到其他的模块或者*主*模块（*主*模块是执行脚本的最上层或计算模式下的一组可访问变量的集合）。
To support this, Python has a way to put definitions in a file and use them in a script or in an interactive instance of the interpreter. Such a file is called a module; definitions from a module can be imported into other modules or into the main module (the collection of variables that you have access to in a script executed at the top level and in calculator mode).

模块就是拥有 Python 定义和声明的文件。文件名就是模块名称，以 .py 结尾。针对一个模块，模块的名称（字符串）和这个模块提供的全局变量 __name__ 是一样的。例如，用你贴心的编辑器在当前目录创建一个叫做 fibo.py 的文件，内容如下:
A module is a file containing Python definitions and statements. The file name is the module name with the suffix .py appended. Within a module, the module’s name (as a string) is available as the value of the global variable __name__. For instance, use your favorite text editor to create a file called fibo.py in the current directory with the following contents:

 # Fibonacci numbers module
 
 def fib(n):    # write Fibonacci series up to n
     a, b = 0, 1
     while b < n:
         print(b, end=' ')
         a, b = b, a+b
     print()
 
 def fib2(n): # return Fibonacci series up to n
     result = []
     a, b = 0, 1
     while b < n:
         result.append(b)
         a, b = b, a+b
     return result

现在进入 Python 解释器，通过如下命令导入这个模块
Now enter the Python interpreter and import this module with the following command:

 >>> import fibo

这并没有把``fibo``里面定义的方法名称直接导入符号表，他只是把 fibo 这个模块放在这了。你可以通过模块的名称来使用这些方法:
This does not enter the names of the functions defined in fibo directly in the current symbol table; it only enters the module name fibo there. Using the module name you can access the functions:

 >>> fibo.fib(1000)
 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
 >>> fibo.fib2(100)
 [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
 >>> fibo.__name__
 'fibo'

你也可以用一个本地的名字来存放某个方法，这样用起来会比较方便。
If you intend to use a function often you can assign it to a local name:

 >>> fib = fibo.fib
 >>> fib(500)
 1 1 2 3 5 8 13 21 34 55 89 144 233 377

==-6.1. 深入模块 More on Modules==
模块除了方法定义，还可以包括可执行的代码。这些代码一般用来初始化这个模块。这些代码只有在*第一次*被导入时才会被执行。
A module can contain executable statements as well as function definitions. These statements are intended to initialize the module. They are executed only the first time the module is imported somewhere. [1]

每个模块有各自独立的符号表，在模块内部为所有的函数当作全局符号表来使用。所以，模块的作者可以放心大胆的在模块内部使用这些全局变量，而不用担心把其他用户的全局变量搞花。从另一个方面，当你确实知道你在做什么的话，你也可以通过``modname.itemname``这样的表示法来访问模块内的函数。
Each module has its own private symbol table, which is used as the global symbol table by all functions defined in the module. Thus, the author of a module can use global variables in the module without worrying about accidental clashes with a user’s global variables. On the other hand, if you know what you are doing you can touch a module’s global variables with the same notation used to refer to its functions, modname.itemname.

模块是可以导入其他模块的。在一个模块（或者脚本，或者其他地方）的最前面使用 import 来导入一个模块，当然这只是一个惯例，而不是强制的。被导入的模块的名称将被放入当前操作的模块的符号表中。
Modules can import other modules. It is customary but not required to place all import statements at the beginning of a module (or script, for that matter). The imported module names are placed in the importing module’s global symbol table.

还有一种导入的方法，可以使用`import`直接把模块内（函数，变量的）名称导入到当前操作模块。比如:
There is a variant of the import statement that imports names from a module directly into the importing module’s symbol table. For example:

 >>> from fibo import fib, fib2
 >>> fib(500)
 1 1 2 3 5 8 13 21 34 55 89 144 233 377

这种导入的方法不会把被导入的模块的名称放在当前的字符表中（所以在这个例子里面，``fibo``这个名称是没有定义的）。
This does not introduce the module name from which the imports are taken in the local symbol table (so in the example, fibo is not defined).

这还有一种方法，可以一次性的把模块中的所有（函数，变量）名称都导入到当前模块的字符表:
There is even a variant to import all names that a module defines:

 >>> from fibo import *
 >>> fib(500)
 1 1 2 3 5 8 13 21 34 55 89 144 233 377

这将把所有的名字都导入进来，但是那些由单一下划线（``_``）开头的名字不在此例。大多数情况， Python程序员不使用这种方法，因为引入的其它来源的命名，很可能覆盖了已有的定义。
This imports all names except those beginning with an underscore (_). In most cases Python programmers do not use this facility since it introduces an unknown set of names into the interpreter, possibly hiding some things you have already defined.

Note that in general the practice of importing * from a module or package is frowned upon, since it often causes poorly readable code. However, it is okay to use it to save typing in interactive sessions.

'''Note''': For efficiency reasons, each module is only imported once per interpreter session. Therefore, if you change your modules, you must restart the interpreter – or, if it’s just one module you want to test interactively, use imp.reload(), e.g. import imp; imp.reload(modulename).
===-6.1.1. 像脚本一样运行模块 Executing modules as scripts===
使用下面的命令运行一个 Python 模块:
When you run a Python module with

 python fibo.py <arguments>

如果你的模块里面的代码就会执行，就好像你导入他们一样，``__name__`` 会赋值为 ``“__main__”``。也就是说，你在模块的最下面加上如下代码:
the code in the module will be executed, just as if you imported it, but with the __name__ set to "__main__". That means that by adding this code at the end of your module:

 if __name__ == "__main__":
     import sys
     fib(int(sys.argv[1]))

这个文件可以当作一个脚本来使用。而这部分代码只有在这个模块被当作”主”程序执行时才会被执行:
you can make the file usable as a script as well as an importable module, because the code that parses the command line only runs if the module is executed as the “main” file:

 $ python fibo.py 50
 1 1 2 3 5 8 13 21 34

如果这个模块是被导入的，那么这些代码是不被执行的:
If the module is imported, the code is not run:

 >>> import fibo
 >>>

模块经常通过这种写法来提供一些方便的接口，或者用来测试（直接运行脚本，会执行一个/组测试用例）。
This is often used either to provide a convenient user interface to a module, or for testing purposes (running the module as a script executes a test suite).
===-6.1.2. 模块的搜索路径 The Module Search Path===

When a module named spam is imported, the interpreter searches for a file named spam.py in the current directory, and then in the list of directories specified by the environment variable PYTHONPATH. This has the same syntax as the shell variable PATH, that is, a list of directory names. When PYTHONPATH is not set, or when the file is not found there, the search continues in an installation-dependent default path; on Unix, this is usually .:/usr/local/lib/python.

Actually, modules are searched in the list of directories given by the variable sys.path which is initialized from the directory containing the input script (or the current directory), PYTHONPATH and the installation- dependent default. This allows Python programs that know what they’re doing to modify or replace the module search path. Note that because the directory containing the script being run is on the search path, it is important that the script not have the same name as a standard module, or Python will attempt to load the script as a module when that module is imported. This will generally be an error. See section Standard Modules for more information.
===-6.1.3. “Compiled” Python files===

As an important speed-up of the start-up time for short programs that use a lot of standard modules, if a file called spam.pyc exists in the directory where spam.py is found, this is assumed to contain an already-“byte-compiled” version of the module spam. The modification time of the version of spam.py used to create spam.pyc is recorded in spam.pyc, and the .pyc file is ignored if these don’t match.

Normally, you don’t need to do anything to create the spam.pyc file. Whenever spam.py is successfully compiled, an attempt is made to write the compiled version to spam.pyc. It is not an error if this attempt fails; if for any reason the file is not written completely, the resulting spam.pyc file will be recognized as invalid and thus ignored later. The contents of the spam.pyc file are platform independent, so a Python module directory can be shared by machines of different architectures.

Some tips for experts:

*When the Python interpreter is invoked with the -O flag, optimized code is generated and stored in .pyo files. The optimizer currently doesn’t help much; it only removes assert statements. When -O is used, all bytecode is optimized; .pyc files are ignored and .py files are compiled to optimized bytecode.

*Passing two -O flags to the Python interpreter (-OO) will cause the bytecode compiler to perform optimizations that could in some rare cases result in malfunctioning programs. Currently only __doc__ strings are removed from the bytecode, resulting in more compact .pyo files. Since some programs may rely on having these available, you should only use this option if you know what you’re doing.

*A program doesn’t run any faster when it is read from a .pyc or .pyo file than when it is read from a .py file; the only thing that’s faster about .pyc or .pyo files is the speed with which they are loaded.

*When a script is run by giving its name on the command line, the bytecode for the script is never written to a .pyc or .pyo file. Thus, the startup time of a script may be reduced by moving most of its code to a module and having a small bootstrap script that imports that module. It is also possible to name a .pyc or .pyo file directly on the command line.

*It is possible to have a file called spam.pyc (or spam.pyo when -O is used) without a file spam.py for the same module. This can be used to distribute a library of Python code in a form that is moderately hard to reverse engineer.

*The module compileall can create .pyc files (or .pyo files when -O is used) for all modules in a directory.

==-6.2. Standard Modules==

Python comes with a library of standard modules, described in a separate document, the Python Library Reference (“Library Reference” hereafter). Some modules are built into the interpreter; these provide access to operations that are not part of the core of the language but are nevertheless built in, either for efficiency or to provide access to operating system primitives such as system calls. The set of such modules is a configuration option which also depends on the underlying platform For example, the winreg module is only provided on Windows systems. One particular module deserves some attention: sys, which is built into every Python interpreter. The variables sys.ps1 and sys.ps2 define the strings used as primary and secondary prompts:

 >>> import sys
 >>> sys.ps1
 '>>> '
 >>> sys.ps2
 '... '
 >>> sys.ps1 = 'C> '
 C> print('Yuck!')
 Yuck!
 C>

These two variables are only defined if the interpreter is in interactive mode.

The variable sys.path is a list of strings that determines the interpreter’s search path for modules. It is initialized to a default path taken from the environment variable PYTHONPATH, or from a built-in default if PYTHONPATH is not set. You can modify it using standard list operations:

 >>> import sys
 >>> sys.path.append('/ufs/guido/lib/python')

==-6.3. The dir() Function==

The built-in function dir() is used to find out which names a module defines. It returns a sorted list of strings:

 >>> import fibo, sys
 >>> dir(fibo)
 ['__name__', 'fib', 'fib2']
 >>> dir(sys)
 ['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__',
 '__stdin__', '__stdout__', '_getframe', 'api_version', 'argv',
 'builtin_module_names', 'byteorder', 'callstats', 'copyright',
 'displayhook', 'exc_info', 'excepthook',
 'exec_prefix', 'executable', 'exit', 'getdefaultencoding', 'getdlopenflags',
 'getrecursionlimit', 'getrefcount', 'hexversion', 'maxint', 'maxunicode',
 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache',
 'platform', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setdlopenflags',
 'setprofile', 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout',
 'version', 'version_info', 'warnoptions']

Without arguments, dir() lists the names you have defined currently:

 >>> a = [1, 2, 3, 4, 5]
 >>> import fibo
 >>> fib = fibo.fib
 >>> dir()
 ['__builtins__', '__doc__', '__file__', '__name__', 'a', 'fib', 'fibo', 'sys']

Note that it lists all types of names: variables, modules, functions, etc.

dir() does not list the names of built-in functions and variables. If you want a list of those, they are defined in the standard module builtins:

 >>> import builtins
 >>> dir(builtins)
 
 ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException', 'Buffer
Error', 'BytesWarning', 'DeprecationWarning', 'EOFError', 'Ellipsis', 'Environme
ntError', 'Exception', 'False', 'FloatingPointError', 'FutureWarning', 'Generato
rExit', 'IOError', 'ImportError', 'ImportWarning', 'IndentationError', 'IndexErr
or', 'KeyError', 'KeyboardInterrupt', 'LookupError', 'MemoryError', 'NameError',
 'None', 'NotImplemented', 'NotImplementedError', 'OSError', 'OverflowError', 'P
endingDeprecationWarning', 'ReferenceError', 'RuntimeError', 'RuntimeWarning', '
StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'Ta
bError', 'True', 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', 'Unicod
eEncodeError', 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserW
arning', 'ValueError', 'Warning', 'ZeroDivisionError', '__build_class__', '__deb
ug__', '__doc__', '__import__', '__name__', '__package__', 'abs', 'all', 'any',
'ascii', 'bin', 'bool', 'bytearray', 'bytes', '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', 'memory
view', 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property'
, 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice', 'sort
ed', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars', 'zip']

==-6.4. Packages==

Packages are a way of structuring Python’s module namespace by using “dotted module names”. For example, the module name A.B designates a submodule named B in a package named A. Just like the use of modules saves the authors of different modules from having to worry about each other’s global variable names, the use of dotted module names saves the authors of multi-module packages like NumPy or the Python Imaging Library from having to worry about each other’s module names.

Suppose you want to design a collection of modules (a “package”) for the uniform handling of sound files and sound data. There are many different sound file formats (usually recognized by their extension, for example: .wav, .aiff, .au), so you may need to create and maintain a growing collection of modules for the conversion between the various file formats. There are also many different operations you might want to perform on sound data (such as mixing, adding echo, applying an equalizer function, creating an artificial stereo effect), so in addition you will be writing a never-ending stream of modules to perform these operations. Here’s a possible structure for your package (expressed in terms of a hierarchical filesystem):

 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
               ...

When importing the package, Python searches through the directories on sys.path looking for the package subdirectory.

The __init__.py files are required to make Python treat the directories as containing packages; this is done to prevent directories with a common name, such as string, from unintentionally hiding valid modules that occur later on the module search path. In the simplest case, __init__.py can just be an empty file, but it can also execute initialization code for the package or set the __all__ variable, described later.

Users of the package can import individual modules from the package, for example:

 import sound.effects.echo

This loads the submodule sound.effects.echo. It must be referenced with its full name.

 sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

An alternative way of importing the submodule is:

 from sound.effects import echo

This also loads the submodule echo, and makes it available without its package prefix, so it can be used as follows:

 echo.echofilter(input, output, delay=0.7, atten=4)

Yet another variation is to import the desired function or variable directly:

 from sound.effects.echo import echofilter

Again, this loads the submodule echo, but this makes its function echofilter() directly available:

 echofilter(input, output, delay=0.7, atten=4)

Note that when using from package import item, the item can be either a submodule (or subpackage) of the package, or some other name defined in the package, like a function, class or variable. The import statement first tests whether the item is defined in the package; if not, it assumes it is a module and attempts to load it. If it fails to find it, an ImportError exception is raised.

Contrarily, when using syntax like import item.subitem.subsubitem, each item except for the last must be a package; the last item can be a module or a package but can’t be a class or function or variable defined in the previous item.
===-6.4.1. Importing * From a Package===

Now what happens when the user writes from sound.effects import *? Ideally, one would hope that this somehow goes out to the filesystem, finds which submodules are present in the package, and imports them all. This could take a long time and importing sub-modules might have unwanted side-effects that should only happen when the sub-module is explicitly imported.

The only solution is for the package author to provide an explicit index of the package. The import statement uses the following convention: if a package’s __init__.py code defines a list named __all__, it is taken to be the list of module names that should be imported when from package import * is encountered. It is up to the package author to keep this list up-to-date when a new version of the package is released. Package authors may also decide not to support it, if they don’t see a use for importing * from their package. For example, the file sounds/effects/__init__.py could contain the following code:

 __all__ = ["echo", "surround", "reverse"]

This would mean that from sound.effects import * would import the three named submodules of the sound package.

If __all__ is not defined, the statement from sound.effects import * does not import all submodules from the package sound.effects into the current namespace; it only ensures that the package sound.effects has been imported (possibly running any initialization code in __init__.py) and then imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by __init__.py. It also includes any submodules of the package that were explicitly loaded by previous import statements. Consider this code:

 import sound.effects.echo
 import sound.effects.surround
 from sound.effects import *

In this example, the echo and surround modules are imported in the current namespace because they are defined in the sound.effects package when the from...import statement is executed. (This also works when __all__ is defined.)

Although certain modules are designed to export only names that follow certain patterns when you use import *, it is still considered bad practise in production code.

Remember, there is nothing wrong with using from Package import specific_submodule! In fact, this is the recommended notation unless the importing module needs to use submodules with the same name from different packages.
===-6.4.2. Intra-package References===

When packages are structured into subpackages (as with the sound package in the example), you can use absolute imports to refer to submodules of siblings packages. For example, if the module sound.filters.vocoder needs to use the echo module in the sound.effects package, it can use from sound.effects import echo.

You can also write relative imports, with the from module import name form of import statement. These imports use leading dots to indicate the current and parent packages involved in the relative import. From the surround module for example, you might use:

 from . import echo
 from .. import formats
 from ..filters import equalizer

Note that relative imports are based on the name of the current module. Since the name of the main module is always "__main__", modules intended for use as the main module of a Python application must always use absolute imports.
===-6.4.3. Packages in Multiple Directories===

Packages support one more special attribute, __path__. This is initialized to be a list containing the name of the directory holding the package’s __init__.py before the code in that file is executed. This variable can be modified; doing so affects future searches for modules and subpackages contained in the package.

While this feature is not often needed, it can be used to extend the set of modules found in a package.

'''附录''' Footnotes
#[1]	In fact function definitions are also ‘statements’ that are ‘executed’; the execution of a module-level function enters the function name in the module’s global symbol table.

'''<center>————&mdash;　[[Python_官方简明教程|返回《 Python 官方教程 》目录]]　&mdash;————</center>'''
'''<center>—&mdash;　[[编程语言|返回《 Python 手册 》总目录]]　&mdash;—</center>'''