SPHINXOPTS =

SPHINXBUILD = sphinx-build

PAPER =

BUILDDIR = build

PAPEROPT_a4 = -D latex_paper_size=a4

PAPEROPT_letter = -D latex_paper_size=letter

ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext

help:

@echo "Please use \`make <target>' where <target> is one of"

@echo " html to make standalone HTML files"

@echo " dirhtml to make HTML files named index.html in directories"

@echo " singlehtml to make a single large HTML file"

@echo " pickle to make pickle files"

@echo " json to make JSON files"

@echo " htmlhelp to make HTML files and a HTML help project"

@echo " qthelp to make HTML files and a qthelp project"

@echo " devhelp to make HTML files and a Devhelp project"

@echo " epub to make an epub"

@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"

@echo " latexpdf to make LaTeX files and run them through pdflatex"

@echo " text to make text files"

@echo " man to make manual pages"

@echo " texinfo to make Texinfo files"

@echo " info to make Texinfo files and run them through makeinfo"

@echo " gettext to make PO message catalogs"

@echo " changes to make an overview of all changed/added/deprecated items"

@echo " linkcheck to check all external links for integrity"

@echo " doctest to run all doctests embedded in the documentation (if enabled)"

clean:

-rm -rf $(BUILDDIR)/*

html:

$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

@echo

@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

dirhtml:

$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

@echo

@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

singlehtml:

$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml

@echo

@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."

pickle:

$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle

@echo

@echo "Build finished; now you can process the pickle files."

json:

$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json

@echo

@echo "Build finished; now you can process the JSON files."

htmlhelp:

$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp

@echo

@echo "Build finished; now you can run HTML Help Workshop with the" \

".hhp project file in $(BUILDDIR)/htmlhelp."

qthelp:

$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp

@echo

@echo "Build finished; now you can run "qcollectiongenerator" with the" \

".qhcp project file in $(BUILDDIR)/qthelp, like this:"

@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Pythontutorial.qhcp"

@echo "To view the help file:"

@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Pythontutorial.qhc"

devhelp:

$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp

@echo

@echo "Build finished."

@echo "To view the help file:"

@echo "# mkdir -p $$HOME/.local/share/devhelp/Pythontutorial"

@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Pythontutorial"

@echo "# devhelp"

epub:

$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub

@echo

@echo "Build finished. The epub file is in $(BUILDDIR)/epub."

latex:

$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

@echo

@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."

@echo "Run \`make' in that directory to run these through (pdf)latex" \

"(use \`make latexpdf' here to do that automatically)."

latexpdf:

$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

@echo "Running LaTeX files through pdflatex..."

$(MAKE) -C $(BUILDDIR)/latex all-pdf

@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

text:

$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

@echo

@echo "Build finished. The text files are in $(BUILDDIR)/text."

man:

$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man

@echo

@echo "Build finished. The manual pages are in $(BUILDDIR)/man."

texinfo:

$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

@echo

@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."

@echo "Run \`make' in that directory to run these through makeinfo" \

"(use \`make info' here to do that automatically)."

info:

$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

@echo "Running Texinfo files through makeinfo..."

make -C $(BUILDDIR)/texinfo info

@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

gettext:

$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale

@echo

@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

changes:

$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes

@echo

@echo "The overview file is in $(BUILDDIR)/changes."

linkcheck:

$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck

@echo

@echo "Link check complete; look for any errors in the above output " \

"or in $(BUILDDIR)/linkcheck/output.txt."

doctest:

$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest

@echo "Testing of doctests in the sources finished, look at the " \

"results in $(BUILDDIR)/doctest/output.txt."

# Sphinx build info version 1

# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.

config: 140fb1222a934ddb93f559dc5229263a

tags: 645f666f9bcd5a90fca523b33c5a78b7

.. _tut-appendix:

********

附录

********

.. _tut-interac:

交互模式

================

.. _tut-error:

错误处理

--------------

当错误发生时，解释器打印一个错误信息和堆栈跟踪。在交互模式下，它返回主提示符；当输入来自文件的时候，在打印堆栈跟踪后以非零退出状态退出。（在 `try <https://docs.python.org/3/reference/compound_stmts.html#try>`_ 声明中被 `except <https://docs.python.org/3/reference/compound_stmts.html#except>`_ 子句捕捉到的异常在这种情况下不是错误。）有些错误是非常致命的会导致一个非零状态的退出；这也适用于内部错误以及某些情况的内存耗尽。所有的错误信息都写入到标准错误流；来自执行的命令的普通输出写入到标准输出。

输入中断符（通常是 Control-C 或者 DEL）到主或者从提示符中慧取消输入并且返回到主提示。[#]_ 当命令执行中输入中断符会引起 `KeyboardInterrupt <https://docs.python.org/3/library/exceptions.html#KeyboardInterrupt>`_ 异常，这个异常能够被一个 `try <https://docs.python.org/3/reference/compound_stmts.html#try>`_ 声明处理。

.. _tut-scripts:

可执行 Python 脚本

-------------------------

在 BSD'ish Unix 系统上，Python 脚本可直接执行，像 shell 脚本一样，只需要把下面内容加入到 ::

#!/usr/bin/env python3.5

（假设 python 解释器在用户的 :envvar:`PATH` 中）脚本的开头，并给予该文件的可执行模式。``#!`` 必须是文件的头两个字符。在一些系统上，第一行必须以 Unix-style 的行结束符（``'\n'``）结束，不能以 Windows 的行结束符（``'\r\n'``）。 注意 ``'#'`` 在 Python 中是用于注释的。

使用 :program:`chmod` 命令能够给予脚本执行模式或者权限。

.. code-block:: bash

$ chmod +x myscript.py

在 Windows 系统上，没有一个 “可执行模式” 的概念。Python 安装器会自动地把 ``.py`` 文件和 ``python.exe`` 关联起来，因此双击 Python 分拣将会把它当成一个脚本运行。文件扩展名也可以是 ``.pyw``，在这种情况下，运行时不会出现控制台窗口。

.. _tut-startup:

交互式启动文件

----------------------------

当你使用交互式 Python 的时候，它常常很方便地执行一些命令在每次解释器启动时。你可以这样做：设置一个名为 `PYTHONSTARTUP <https://docs.python.org/3/using/cmdline.html#envvar-PYTHONSTARTUP>`_ 的环境变量为包含你的启动命令的文件名。这跟 Unix shells 的 :file:`.profile` 特点有些类似。

这个文件在交互式会话中是只读的，在当 Python 从脚本中读取命令，以及在当 :file:`/dev/tty` 被作为明确的命令源的时候不只是可读的。该文件在交互式命令被执行的时候在相同的命名空间中能够被执行，因此在交互式会话中定义或者导入的对象能够无需授权就能使用。你也能在文件中更改提示 ``sys.ps1`` 和 ``sys.ps2``。

如果你想要从当前目录中读取一个附加的启动文件，你可以在全局启动文件中编写代码像这样：``if

os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read())``。如果你想要在脚本中使用启动文件的话，你必须在脚本中明确要这么做::

import os

filename = os.environ.get('PYTHONSTARTUP')

if filename and os.path.isfile(filename):

with open(filename) as fobj:

startup_file = fobj.read()

exec(startup_file)

.. _tut-customize:

定制模块

-------------------------

Python 提供两个钩子为了让你们定制 :mod:`sitecustomize` 和 :mod:`usercustomize`。为了看看它的工作机制的话，你必须首先找到你的用户 site-packages 目录的位置。启动 Python 并且运行这段代码::

>>> import site

>>> site.getusersitepackages()

'/home/user/.local/lib/python3.4/site-packages'

现在你可以创建一个名为 :file:`usercustomize.py` 的文件在你的用户 site-packages 目录，并且在里面放置你想要的任何内容。它会影响 Python 的每一次调用，除非它以 `-s <https://docs.python.org/3/using/cmdline.html#cmdoption-s>`_ （禁用自动导入）选项启动。

:mod:`sitecustomize` 以同样地方式工作，但是通常由是机器的管理员创建在全局的 site-packages 目录中，并且是在 :mod:`usercustomize` 之前导入。请参阅 `site <https://docs.python.org/3/library/site.html#module-site>`_ 模块获取更多信息。

.. rubric:: Footnotes

.. [#] GNU 的 Readline 包的问题可能会阻止这种做法。

.. _tut-intro:

**********************

开胃菜

**********************

如果你要用计算机做很多工作，最后你会发现有一些任务你更希望用自动化的方式进行处理。比如，你想要在大量的文本文件中执行查找/替换，或者以复杂的方式对大量的图片进行重命名和整理。也许你想要编写一个小型的自定义数据库、一个特殊的 GUI 应用程序或一个简单的小游戏。

如果你是一名专业的软件开发者，可能你必须使用几种 C/C++/JAVA 类库，并且发现通常编写/编译/测试/重新编译的周期是如此漫长。也许你正在为这些类库编写测试用例，但是发现这是一个让人烦躁的工作。又或者你已经完成了一个可以使用扩展语言的程序，但你并不想为此重新设计并实现一套全新的语言。

那么 Python 正是你所需要的语言。

虽然你能够通过编写 Unix shell 脚本或 Windows 批处理文件来处理其中的某些任务，但 Shell 脚本更适合移动文件或修改文本数据，并不适合编写 GUI 应用程序或游戏；虽然你能够使用 C/C++/JAVA 编写程序，但即使编写一个简单的 first-draft 程序也有可能耗费大量的开发时间。相比之下，Python 更易于使用，无论在 Windows、Mac OS X 或 Unix 操作系统上它都会帮助你更快地完成任务。

虽然 Python 易于使用，但它却是一门完整的编程语言；与 Shell 脚本或批处理文件相比，它为编写大型程序提供了更多的结构和支持。另一方面，Python 提供了比 C 更多的错误检查，并且作为一门 *高级语言*，它内置支持高级的数据结构类型，例如：灵活的数组和字典。因其更多的通用数据类型，Python 比 Awk 甚至 Perl 都适用于更多问题领域，至少大多数事情在 Python 中与其他语言同样简单。

Python 允许你将程序分割为不同的模块，以便在其他的 Python 程序中重用。Python 内置提供了大量的标准模块，你可以将其用作程序的基础，或者作为学习 Python 编程的示例。这些模块提供了诸如文件 I/O、系统调用、Socket 支持，甚至类似 Tk 的用户图形界面（GUI）工具包接口。

Python 是一门解释型语言，因为无需编译和链接，你可以在程序开发中节省宝贵的时间。Python 解释器可以交互的使用，这使得试验语言的特性、编写临时程序或在自底向上的程序开发中测试方法非常容易。你甚至还可以把它当做一个桌面计算器。

Python 让程序编写的紧凑和可读。用 Python 编写的程序通常比同样的 C、C++ 或 Java 程序更短小，这是因为以下几个原因::

* 高级数据结构使你可以在一条语句中表达复杂的操作；

* 语句组使用缩进代替开始和结束大括号来组织；

* 变量或参数无需声明。

Python 是 *可扩展* 的：如果你会 C 语言编程便可以轻易地为解释器添加内置函数或模块，或者为了对性能瓶颈作优化，或者将 Python 程序与只有二进制形式的库（比如某个专业的商业图形库）连接起来。一旦你真正掌握了它，你可以将 Python 解释器集成进某个 C 应用程序，并把它当作那个程序的扩展或命令行语言。

顺便说一句，这个语言的名字来自于 BBC 的 “Monty Python’s Flying Cirecus” 节目，和爬行类动物没有任何关系。在文档中引用 Monty Python 的典故不仅可行，而且值得鼓励！

现在你已经为 Python 兴奋不已了吧，大概想要领略一些更多的细节！学习一门语言最好的方法就是使用它，本指南推荐你边读边使用 Python 解释器练习。

下一节中，我们将解释 Python 解释器的用法。这是很简单的一件事情，但它有助于试验后面的例子。

本手册剩下的部分将通过示例介绍 Python 语言及系统的诸多特性，开始是简单的语法、数据类型和表达式，接着介绍函数与模块，最后涉及异常和自定义类这样的高级内容。