urllib官方库说明文档阅读笔记

前言

最近在学习URLLIB便找到其之Doc 一大串英文看到晕 便决定边看边译

• 翻译中 2019-5-20

官方链接

-	地址
介绍	点击跳转
urllib.request	点击跳转
urllib.error	点击跳转
urllib.parse	点击跳转
urllib.robotparser	点击跳转

urllib.request

方法列表

urllib.request.urlopen

urllib.request.urlopen(
url, data=None, [timeout, ]*,
cafile=None, capath=None, 
cadefault=False, context=None)

参数列表

url

打开URL用的的 url参数 可能是字符串或者是一个Request对象

例如

import urllib
url = "http://www.example.com"
req = urllib.request.Request('http://www.example.com')

data

该参数必须是一个拥有具体要发给服务器的额外数据的对象，或者毋须类似数据时是None
查看Request类的详细得知更多
urllib.request 模块使用 HTTP/1.1 且 在其之HTTP请求头部含有 Connection:close 的头部

可选参数 timeout

该参数定义了一个以秒计的超时参数 来 阻塞操作 例如 尝试连接的过程（如果没有指定 ，那么会使用默认的全局超时）。 但事实上这个参数只在 HTTP HTTPS FTP 连接中启到作用。

context

该参数如果被指定 ，它一定是一个描述各种SSL选项的 ssl.SSLContext 实例 查看HTTPSConnection了解更多

cafile 和 capath

该参数 指定了一个用于HTTPS请求的可信任CA证书的集合。 cafile 应该指向包含一堆CA证书的单文件 而 capath 应当指向 含有被散列化（HASHED）的证书文件们 的目录 在ssl.SSLContext.load_verify_locations()了解更多

cadefault

该参数 已被忽略 看名字CAdefault 默认CA位置？

返回值

这个函数总会返回一个可以像context manager一样工作的的对象而且包含以下方法

方法	介绍
geturl()	返回从源获取到的URL，通常用来检测是有否重定向
info()	以email.message_from_string()实例的形式返回页面的元数据（meta-information），例如头部信息，（点击此处快速查阅HTTP 头部的信息)
getcode()	返回 回应的 HTTP状态码

对于HTTP 和 HTTPS

对于HTTP 和 HTTPS的URL， 这个函数会返回一个 稍微修改过的http.client.HTTPResponse对象。为了上边讲的三个新方法，这个信息的属性 包含了和 reason属性一样的信息。就是 服务器返回的 原因短语（reason phrase) 而不是按照 HTTPResponse文档中规定的请求头部

对于 FTP、文件 和 数据URL和被显性处理的URLopener和FancyURLopener类

URLopener FancyURLopener
这个函数会返回一个 urllib.response.addinfourl 对象

异常和附加说明

协议错误时会引发URLError错误 （Raise errors）
注意 如果没有 handler 来处理 请求 可能会返回 None (尽管默认安装的全局OpenerDirector会用UnknownHandler来确保这类情况不会发生）
另外 如果检测到有设置代理（例如 当一个 *_proxy环境变量中 像 http_proxy被设置）默认安装的ProxyHandler会确保请求有经过代理处理

python2.6和更早版本的urllib.urlopen函数已经停用 urllib.request.urlopen()对应旧的urllib2.urlopen。其中代理处理可以通过传入一个字典参数入urllib.urlopen完成，这个可以通过使用ProxyHandler的对象们获取到。
3.2版本更改：加入 cafile 和 capath
3.2版本更改： HTTPS 虚拟主机现在经已支持 （如果可能的话）（就是，如果ssl.HAS_SNI 可用）
3.2新增功能 data 可以是一个可迭代对象
3.3版本更改：添加cadefault
3.4.3版本更改：添加context
3.6之后版本移除的内容: 在context方面 cafile,capath 和 cadefault 不再赞成使用。请使用ssl.SSLContext.load_cert_chain()代替 或者让 ssl.create_default_context() 为你选择系统信任的CA证书

urllib.request.install_opener

urllib.request.install_opener(opener)

说明

安装一个Openerdirector实例并作为默认全局opener「访问者」。仅当你想urlopen用那个opener的时候你才需要安装opener「访问者」。不然的话最好调用OpenerDirector.open()代替urlopen，这个代码不会检查是否是真的OpenerDirector，而且任何写得恰当的接口都会工作。

urllib.request.build_opener

urllib.request.build_opener([handler, ...])

返回值

返回一个把传入的handler们串成一串的OpenerDirector实例。handler们能是BaseHandler的实例 亦可是 BaseHandler的子类（在必需要调用无参构造方法的时候）。这些除非handler们包含这些类，不然这些类的实例会在handler们前面，这些类和它们的子类有 ProxyHandler(如果探测到代理设置),UnknownHandler , HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler,FTPHandler,FileHandler,HTTPErrorProcessor

如果 Python 安装的时候 有SSL支持（亦即是能载入ssl模块） HTTPSHandler也会加入

BaseHandler的子类还可以改变它的handler_order属性来改变他在handler们列表中的位置

urllib.request.pathname2url

urllib.request.pathname2url(path)

为了给出一条能用在URL路径组件的 路径 从local syntax（本地语义/本地语法/局部语法）中转换出 路径名称 path.这不是在生成完整的URL。这个函数的返回值已经被用quoted()函数quote过的

urllib.error

由urllib.request引起的异常
urllib.error 定义了由urllib.request 引起的异常和异常类。它的基类是URLError
下列是正常情况下 urllib.error会引发的异常：

exception urllib.error.URLError

handler们会在它们运行出问题的时候引发这个异常。这个异常是OSError的子类

原因

导致这个错误的原因 会可能是 信息字符串或者是 其他的异常实例
3.3版本更改： URLError成为OSError的子类而不是IOError

exception urllib.error.HTTPError

尽管是一个异常（URLError的子类）HTTPError 也可以当作不是异常的文件对象来做为返回值（就比如作为urlopen的返回值）这在处理例如认证请求之类的奇怪的HTTP 错误中很有用

代码

定义在RFC 2616 的 HTTP 状态码。这些数字也对应著定义在http.server.BaseHTTPRequestHandler.responses里边字典找到的的数值

原因

通常是个字符串来解释这个错误的原因

头部

引发HTTPError的HTTP请求中的HTTP响应头

urllib.parse

urllib.robotparser