最新最好的Python参考手册：Python文档使用指南

最新最好的Python参考手册，就是Python自带的文档。有鉴于此，与其把文档页面编辑一下再打印出来，还不如探究一下如何用好官方文档更加有用。

标准的文档包分成若干部分，包括Python在各个平台上的文档编写、分发、安装和扩展说明。只要是有关Python的问题，这些文档都是寻求答案的逻辑起点。Python文档最主要的两个内容，可能也是最有用的部分，就是库参考手册（Library Reference）和语言参考手册（Language Reference）。库参考手册是绝对必要的，因为它对内置数据类型和Python所有内置模块都做了解释。语言参考手册解释了Python内核的工作方式，包括语言内核的官方术语，解释了数据类型、语句等的工作机制。“新特性”（What’s New）部分也值得一读，特别是在发布新版Python的时候，因为这里对新版本的所有改动都做了汇总介绍。

A.1　访问Web端的Python文档

对很多人而言，访问Python文档最方便的途径就是访问Python官方网站并浏览其中的文档。虽然这样需要连入Web，但优点就是内容始终是最新的。对很多项目而言，通过Web检索其他文档和信息是常用操作，因此始终在浏览器的一个标签页中打开并指向在线Python文档，就是将Python参考文档常备手边的简单方案。

A.1.1　浏览机器上的Python文档

Python的很多发行版本都默认包含了完整的文档。在某些Linux发行版本中，文档是独立的包，需要单独安装。不过在大多数情况下，Python安装完成后计算机中就已包含完整文档了，访问起来也很容易。

1．在交互式shell或命令行中访问联机帮助信息

第2章已介绍过了，在交互式命令解释器中如何用help命令访问Python模块或对象的联机帮助信息：

>>> help(int)
Help on int object:

class int(object)
 |  int(x[, base]) -> integer
 |  
 |  Convert a string or number to an integer, if possible.  A floating
 |  point argument will be truncated towards zero (this does not include a
 |  string representation of a floating point number!)  When converting a
 |  string, use the optional base.  It is an error to supply a base when 
 |  converting a non-string.
 |  
 |  Methods defined here:
... (后面是int对象的方法列表)

以上其实是解释器调用pydoc模块生成文档的过程。用pydoc模块还可以在命令行搜索Python文档。在Linux或macOS系统中，如果要在终端窗口中得到同样的输出，只需在提示符下键入pydoc int即可，键入q则可以退出。在Windows命令窗口中，除非已在搜索路径中包含了Python库所在目录，否则就需要键入完整路径，可能类似于C:\Users\<user>\AppData\Local\Programs\Python\Python36\Lib\pydoc.py int，其中<user>是指Windows的用户名。

2．用pydoc创建HTML格式的帮助页面

如果希望更加顺畅地查看pydoc为Python对象或模块生成的文档，可以将输出写入HTML文件，这样就可以在任何浏览器中进行浏览了。为此，请将-w选项添加到pydoc命令中，在Windows系统中将是C:\Users\<user>\AppData\Local\Programs\Python \Python36\Lib\pydoc.py –w int。这时就会查找int对象的文档，pydoc会在当前目录中创建一个名为int.html的文件，可以打开并在浏览器中进行查看。图A-1显示了int.html在浏览器中的样子。

图A-1　由pydoc创建的int.html

如果由于某种原因只需要数量有限的几页文档，那么这种方案就足够用了。但大多数情况下，最好还是用pydoc提供更完整的文档，下一节将会介绍。

3．将pydoc用作文档服务器

除了能为任何Python对象生成文本文档和HTML文档，pydoc模块还可以被当作服务器来使用，以便提供基于Web的文档服务。运行pydoc时可以带上-p和端口号参数，即可在该端口上开启文档服务。然后就可以输入”b“命令，打开浏览器并访问所有可用模块的文档，如图A-2所示。

图A-2　由pydoc文档服务提供的模块文档（部分）

用pydoc提供文档服务有一个好处，就是它还会扫描当前目录，在找到的模块中由文档字符串提取出文档信息，即便模块不属于标准库也没关系。这样要访问任何Python模块的文档时，就比较有用了。但有一点必须说明，为了能从模块中提取文档，pydoc必须要导入模块，这意味着它会执行模块顶层的所有代码。因此，对导入会带来副作用的代码（如第11章所述）也会被执行，因此使用此项功能时务必小心。

4．Windows帮助文件的使用

在Windows系统上，Python 3标准软件包中包含了完整的Windows帮助文件格式的Python文档。在Python的安装文件夹内的Doc文件夹中可以找到这些文件，通常位于“程序”菜单的“Python 3”程序组中。打开主文件时，如图A-3所示。

图A-3　如果习惯使用Window帮助文件，则该文件就是所需的全部文档

A.1.2　文档的下载

如果想在计算机上查看Python文档，但不一定或不需要运行Python，也可以从Python官方网站下载PDF、HTML或文本格式的完整文档。如果需要能在电子书阅读器之类的设备上访问文档，这样就很方便。

A.2　最佳实践：如何成为Pythonista

每种编程语言都有自己的传统和文化，Python就是一个很好的例子。最有经验的Python程序员，有时被称为Python高手（Pythonista），非常关心编码风格，应该符合Python的风格和最佳实践。此类代码常被称作Python式风格的代码，相对Java、C或JavaScript风格的Python代码，更加受到尊重。

Python新手面临的问题，就是该如何学习编写Python式风格的代码。了解Python语言及其风格需要花一些时间和努力，本附录接下来将对如何开始提供一些建议。

成为Python高手的10条技巧

本节列出的技巧是针对Python中级人员的，也是对提升Python技能给出的建议。不一定要求每个人都要完全认可，但根据我多年来的观察，这些技巧将让你踏上成为真正Python高手的正途。

• 尊重Python之禅。Python之禅即PEP 20，总结了Python成为语言的设计理念。在讨论是什么让代码更具Python式风格时，常被提及的就是Python之禅。特别是“优美胜于丑陋”“简洁胜于复杂”，应该始终成为编码的指南。本附录末尾收录了“Python之禅”，只要在Python shell提示符下键入import this，就一定可以看到这些话。
• 遵守PEP 8。PEP 8是官方的Python风格指南，本附录也在下面加以收录。从代码格式化、变量命名到语言的使用，PEP 8都给出了很好的建议。如果想要写出Python式风格的代码，请对PEP 8烂熟于胸。
• 熟悉文档。Python拥有内容丰富、维护良好的文档集，应该经常去查阅一下。最有用的可能就是标准库的文档了，但教程和how-to文件也包含了有效使用语言的大量信息。
• 尽可能少写代码。虽然该建议可能对很多语言都适用，但特别适用于Python。这里的意思是应该努力让程序尽可能短而简单（直至不能更短、更简单为止），应该尽可能多练习一下这种编码风格。
• 尽可能多读代码。从一开始，Python社区就已经意识到阅读代码比编写代码更为重要。尽可能多读一些Python代码，如果有可能就与别人讨论一下读过的代码。
• 优先采用内置数据结构。在编写自己的类保存数据之前，应该首先考虑一下Python的内置数据结构。Python的多种数据类型几乎可以无限灵活地自由组合，优点是经过了多年调试和优化。请充分利用它们。
• 对生成器（generator）和推导（comprehension）多花些精力。Python新手几乎总是无法体会到，列表和字典推导以及生成器表达式，正是Python式风格编码的组成部分。请查看一下已读过的Python代码示例，并进行练习。只有几乎不假思索就能写出列表推导，才能成为Python高手。
• 采用标准库。如果内置数据结构无法满足需求，接下来应该考虑采用标准库。标准库中的成员，正以Python的“功能齐备”特性著称。标准库已经经过了时间的考验，其优化和文档化程度几乎超过了其他任何Python代码。只要有可能就请采用标准库。
• 尽可能少写自定义类。仅在必要时才编写自己的类。有经验的Python高手往往对自定义类非常节省，因为他们知道设计良好的类并不是件小事，类一旦创建就不得不去做测试和调试工作。
• 小心使用框架。框架可能很有吸引力，特别是对新手而言，因为框架提供了很多强大的便捷功能。当然该用还得用，但请小心框架的弊端。学习Python本身的时间，可能还不如学习非Python式风格框架的怪异之处来得多。或者你可能会发现自己正在适应框架，而不是让框架适合你。

A.3　PEP 8——Python编码风格指南

本节收录了稍作剪辑的PEP 8摘要（Python Enhancement Proposal，Python增强提案）。PEP 8由Guido van Rossum和Barry Warsaw撰写，是Python的最接近编程风格手册的东西。这里省略了一些比较具体的部分，但主要内容都已包括。应该尽可能让代码遵守PEP 8规范，代码会由此更具Python风格。

访问Python官方网站的文档部分并搜索PEP，就可以获得PEP 8全文及Python历史上发布的所有其他PEP。PEP既是Python历史和经验的绝佳来源，也是当前议题和将来计划的解释。

A.3.1　简介

本文档给出的Python编码约定，适用于由Python主发行版本中的标准库构成的代码。有关Python的C实现中的C代码风格指南，参见相应的PEP^[1]。本文档改编自Guido最初的Python风格指南文章，并加入了Barry风格指南的一些内容。如果与Guido的风格规则存在冲突，应该遵从本PEP。本PEP可能尚未完结（其实可能永远不会完结）。

盲目的一致性是头脑简单的表现

Guido的一个重要观点是，代码被阅读的次数远多于被编写的次数。本指南旨在提高代码的可读性，使各种各样的Python代码能保持风格一致。正如PEP 20^[2]所述，“Readability counts”（注重可读性）。

风格指南是讨论一致性的。与风格指南保持一致很重要。维持同一个项目内部的一致性更加重要。而保证同一个模块和函数内部的一致性则最重要。

然而最最重要的是，知道何时应打破一致性，有时风格指南并不适用。如果心存疑虑，请采用自己的最佳判断。请看看别人的例子并做出最佳决定。不要犹豫，尽管发出疑问。

以下是两个打破规范的好理由。

• 如果应用风格指南会让代码的可读性变差，甚至对于习惯阅读遵守本规范代码的人来说也是如此。
• 需要与周边的代码保持一致，而这些代码并未遵守规范（可能是历史原因造成的），尽管这也可能是个收拾别人烂摊子的机会（真正的极限编程风格）。

A.3.2　代码布局

1．缩进

每级缩进采用4个空格。

为了对付那些确实陈旧的代码，又不愿做出清理，那么可以继续沿用8个空格长度的制表符。

2．制表符还是空格

绝对禁止制表符和空格的混用。

最流行的Python缩进方式是只使用空格。第二流行的方式是只使用制表符。混合使用制表符和空格进行缩进的代码，应该转换为只使用空格的方式。如果调用Python命令行解释器时带上-t参数，它就会对非法混用制表符和空格的代码发出警告。如果用了-tt参数，这些警告就会上升为错误。强烈推荐使用这些参数！

对全新的项目而言，强烈建议只用空格缩进，换掉所有的制表符。大部分编辑器都具备将制表符替换为空格的便捷功能。

3．最大行长

所有行都应限制在79个字符以内。

将行长限制在80个字符的设备还有很多，而且将窗口限制为80个字符宽就可以并排放置多个窗口。这些设备上的默认换行会破坏代码的外观，增加理解的难度。因此，请将所有行都限制在79个字符以内。对于连续的大段文字（文档字符串或注释），建议将行长限制在72个字符以内。

对长行进行换行的首选方案，是利用Python隐含的行连接特性，在圆括号、方括号和大括号内部进行断行。必要时可以在表达式外面多加一对圆括号，不过有时候用反斜杠会更好看些。请确保对后续行进行适当的缩进。打断二元运算符的首选位置是在运算符之后，而不是运算符之前。下面给出一些例子：

class Rectangle(Blob):
    def __init__(self, width, height,
                 color='black', emphasis=None, highlight=0):
        if (width == 0 and height == 0 and\
            color == 'red' and emphasis == 'strong' or \
            highlight > 100):
             raise ValueError("sorry, you lose")
        if width == 0 and height == 0 and (color == 'red' or
                                           emphasis is None):
            raise ValueError("I don't think so -- values are %s, %s" %
                             (width, height))
        Blob.__init__(self, width, height,
                      color, emphasis, highlight)

4．空行

顶级函数和类定义之间，请用两个空行分隔。

类内部的各个方法定义之间，请用1个空行分隔。

为了让有关联的函数成组，可以在各函数组之间有节制地添加空行。相互关联的一组单行函数之间，可以省略空行，如一组函数的伪实现（dummy implementation）。

函数内部可以有节制地用空行来区分出各个逻辑部分。

Python可将Ctrl+L（^L）换页符接受为空白符。很多工具都将其视为分页符，所以可以利用其进行分页，使得文件中的关联部分单独成页。

5．导入

导入语句通常应单独成行，例如：

import os
import sys

不要像下面这样写在一起：

import sys, os

不过下面的写法没有问题：

from subprocess import Popen, PIPE

导入语句通常位于文件的顶部，紧挨着模块注释和文档字符串后面，在模块全局变量和常量定义之前。

导入语句应按照以下顺序进行分组。

（1）标准库的导入。

（2）相关第三方库的导入。

（3）本地应用程序/库——特定库的导入。

每组导入语句之间请加入1个空行。

任何对应的__all__声明都应位于导入语句之后。

非常不推荐对内部包的导入使用相对导入语法。请始终对所有导入都使用绝对包路径。即便Python 2.5现在已完全实现了PEP 328^[3]，它的显式相对导入语法也是强烈不推荐的。绝对导入的可移植性更好，通常可读性也会更好。

{:—}如果是从包含类的模块中导入类，通常可以采用如下写法：

from myclass import MyClass
from foo.bar.yourclass import YourClass

如果上述写法会导致本地命名冲突，就采用如下写法：

import myclass
import foo.bar.yourclass

然后用myclass.MyClass和foo.bar.yourclass.YourClass表示类。

6．表达式和语句内的空白符

讨厌之事——以下场合应避免使用多余的空白符。

• 紧靠小括号、中括号或大括号内部。
  
  正确：

  spam(ham[1], {eggs: 2})
  

  错误：

  spam( ham[ 1 ], { eggs: 2 } )
  

• 紧挨着逗号、分号或冒号之前。
  
  正确：

  if x == 4: print x, y; x, y = y, x
  

  错误：

  if x == 4 : print x , y ; x , y = y , x
  

• 紧挨着函数参数列表的左括号之前。
  
  正确：

  spam(1)
  

  错误：

  spam (1)
  

• 紧挨着索引或切片操作的左括号之前。
  
  正确：

  dict['key'] = list[index]
  

  错误：

  dict ['key'] = list [index]
  

• 为了与另一条赋值或其他语句对齐，在运算符两边使用多个空格。
  
  正确：

  x = 1
  y = 2
  long_variable = 3
  

  错误：

  x                = 1
  y                = 2
  long_variable    = 3
  

7．其他建议

始终在以下二元操作符两侧各放1个空格：赋值（=）、增量赋值（+=，-=等）、比较（==、<、>、!=、<>、<=、>=、in、not、in、is、is not）、布尔（and、or、not）。

• 在数学运算符两侧放置空格。
  
  正确：

  i = i + 1
  submitted += 1
  　
  x = x * 2 – 1 
  hypot2 = x * x + y * y 
  c = (a + b) * (a - b)
  

  错误：

  i=i+1
  submitted +=1
  x = x*2 – 1
  hypot2 = x*x + y*y
  c = (a+b) * (a-b)
  

• 在用于指定关键字参数或默认参数值时，请勿在=两边使用空格。
  
  正确：

  def complex(real, imag=0.0):
        return magic(r=real, i=imag)
  

  错误：

  def complex(real, imag = 0.0):
        return magic(r = real, i = imag)
  

• 通常不鼓励使用复合语句，也就是在同一行放置多条语句。
  
  正确：

  if foo == 'blah':
        do_blah_thing()
  do_one()
  do_two()
  do_three()
  

  最好不要：

  if foo == 'blah': do_blah_thing()
  do_one(); do_two(); do_three()
  

• 虽然有时候将小块代码和if/for/while放在同一行没什么问题，但多行语句绝对不能如此。同时还要避免过长代码行的折叠！
  
  最好不要：

  if foo == 'blah': do_blah_thing()
  for x in lst: total += x
        while t < 10: t = delay()
  

  绝对不要：

  if foo == 'blah': do_blah_thing()
  else: do_non_blah_thing()
  try: something()
  finally: cleanup()
  do_one(); do_two(); do_three(long, argument, 
                                 list, like, this)
  if foo == 'blah': one(); two(); three()
  

A.4　注释

与代码不符的注释还不如不加注释。只要代码发生变化，就一定要优先保证更新注释！

注释应该是完整的句子。如果注释是短语或句子，其首个单词应该大写，除非首个单词是以小写字母开头的标识符，永远不要改变标识符的大小写！。

如果注释很短，尾部的句点则可以省略。块注释通常由一个或多个段落组成，每个段落都由多个完整句子构成，每个句子都以一个句点结尾。

在句子末尾的句点后面，应该加上两个空格。^[4]

用英语撰写注释时，请采用Strunk和White编写的书写规范^[5]。

非英语国家的Python程序员，请用英语撰写注释，除非120%确定代码一定不会被用其他语言的人阅读。

1．块注释

块注释通常用于紧随其后的一些（或全部）代码，并且缩进级别与代码相同。每一行块注释都以一个“#”和一个空格开头，注释内部的缩进文字除外。

块注释内部的段落，由只包含一个“#”的空行分隔。

2．行内注释

请有节制地使用行内注释。

行内注释是指与代码语句处于同一行的注释。行内注释和代码之间至少要隔开两个空格，应该由一个“#”和一个空格开头。

事实上，如果状况很明了的话，是不需要用到行内注释的。例如，以下情况就不需要：

x = x + 1                 # Increment x

{:—}但有些时候，行内注释还是有用的：

x = x + 1                 # Compensate for border

3．文档字符串

如何撰写良好的文档字符串（也叫docstrings），其规范在PEP 257^[6]中已名垂青史。

请为所有的公有模块、函数、类和方法撰写文档字符串。非公有的方法不一定需要文档字符串，但是应该带有描述方法用途的注释。该注释应该位于def行后面。

PEP 257描述了良好文档字符串的规范。请注意，有一点是最重要的，多行文档字符串结尾的““”””应该自成一行，并且最好是在前面加一行空行。例如：

"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.

"""

对单行的文档字符串而言，可以让结尾的““”””位于同一行。

本文截选自《Python 快速入门》（第3版），[美] 娜奥米·塞德（Naomi Ceder） 著，戴旭 译

• Python编程基础教程从入门到实践书籍
• 零基础快速上手学Python核心编程
• Python软件基金会作品，提供习题答案及源代码

本书是Python专业人士Naomi Ceder编写的Python语言的综合指南。她是一位经验丰富的教学者，她既能让读者关注语言的细节，又能使其具备解决实际问题的能力。本书中配有大量贴切的示例和边做边学的习题，有助于读者掌握每一个重要概念。无论读者是要抓取网站内容还是想玩转嵌套元组，都会赞叹本书的清晰、专注和对细节的重视。
本书主要内容
● 明确涵盖Python 3。
● 全面介绍核心库、包和工具。
● 配备精深的习题。
● 新增5章与数据科学相关的内容。
本书专为熟悉编程概念的读者编写，但不要求读者具备Python的使用经验。

Python最佳入门书推荐

１、笨办法学Python 3

２、Python编程快速上手 让繁琐工作自动化