Python模块：requests – 运维那点事

一、初识 Requests 库

Requests 是用 Python 语言编写，基于urllib，采用 Apache 2 协议开源的 Python HTTP 库，号称是“为人类准备的 HTTP 库”。它比 urllib 更加方便，可以节约我们大量的工作，完全满足 HTTP 测试需求。

Python 中，系统自带的 urllib 和 urllib2 都提供了功能强大的 HTTP 支持，但是API接口确实太难用了。requests 作为更高一层的封装，确实在大部分情况下对得起它的 slogan——HTTP for Humans。

安装什么的就很简单的了，直接使用pip即可。

让我们从一些简单的示例开始吧。

二、发送请求

使用 Requests 发送网络请求非常简单。

一开始要导入 Requests 模块：

>>> import requests

1	>>> import requests

然后，尝试获取某个网页。

>>> r = requests.get('http://httpbin.org/get')

1	>>> r = requests.get('http://httpbin.org/get')

现在，我们有一个名为 r 的 Response 对象。我们可以从这个对象中获取所有我们想要的信息。

Requests 简便的 API 意味着所有 HTTP 请求类型都是显而易见的。例如，你可以这样发送一个 HTTP POST 请求：

>>> r = requests.post("http://httpbin.org/post")

1	>>> r = requests.post("http://httpbin.org/post")

漂亮，对吧？那么其他 HTTP 请求类型：PUT（替换资源），DELETE（删除资源），HEAD（查看响应头），PATCH（更新资源），POST（增加资源）以及 OPTIONS（查看可用请求方法）又是如何的呢？都是一样的简单：

>>> r = requests.put("http://httpbin.org/put")
>>> r = requests.delete("http://httpbin.org/delete")
>>> r = requests.head("http://httpbin.org/get")
>>> r = requests.options("http://httpbin.org/patch")

>>> r = requests.put("http://httpbin.org/put")

>>> r = requests.delete("http://httpbin.org/delete")

>>> r = requests.head("http://httpbin.org/get")

>>> r = requests.options("http://httpbin.org/patch")

都很不错吧，但这也仅是 Requests 的冰山一角呢。

http://httpbin.org/是requests作者提供的一个Restful API测试服务

传递 URL 参数

你也许经常想为 URL 的查询字符串(query string)传递某种数据。如果你是手工构建 URL，那么数据会以键/值对的形式置于 URL 中，跟在一个问号的后面。例如， httpbin.org/get?key=val。 Requests 允许你使用 params 关键字参数，以一个字符串字典来提供这些参数。举例来说，如果你想传递 key1=value1 和 key2=value2 到 httpbin.org/get ，那么你可以使用如下代码：

>>> payload = {'key1': 'value1', 'key2': 'value2'}
>>> r = requests.get("http://httpbin.org/get", params=payload)

1 2	>>> payload = {'key1': 'value1', 'key2': 'value2'} >>> r = requests.get("http://httpbin.org/get", params=payload)

通过打印输出该 URL，你能看到 URL 已被正确编码：

>>> print(r.url)
http://httpbin.org/get?key2=value2&key1=value1

1 2	>>> print(r.url) http://httpbin.org/get?key2=value2&key1=value1

注意字典里值为 None 的键都不会被添加到 URL 的查询字符串里。

你还可以将一个列表作为值传入：

>>> payload = {'key1': 'value1', 'key2': ['value2', 'value3']}
>>> r = requests.get('http://httpbin.org/get', params=payload)
>>> print(r.url)
http://httpbin.org/get?key1=value1&key2=value2&key2=value3

>>> payload = {'key1': 'value1', 'key2': ['value2', 'value3']}

>>> r = requests.get('http://httpbin.org/get', params=payload)

>>> print(r.url)

http://httpbin.org/get?key1=value1&key2=value2&key2=value3

三、响应内容

我们能读取服务器响应的内容：

>>> r = requests.get('http://httpbin.org/get')
>>> r.text

1 2	>>> r = requests.get('http://httpbin.org/get') >>> r.text

想输出格式化好看一点，简单使用json模块即可。

>>> import json
>>> print(json.dumps(json.loads(r.text), indent=4))

1 2	>>> import json >>> print(json.dumps(json.loads(r.text), indent=4))

Requests 会自动解码来自服务器的内容。大多数 unicode 字符集都能被无缝地解码。

请求发出后，Requests 会基于 HTTP 头部对响应的编码作出有根据的推测。当你访问 r.text 之时，Requests 会使用其推测的文本编码。你可以找出 Requests 使用了什么编码，并且能够使用r.encoding 属性来改变它：

>>> r.encoding
'utf-8'
>>> r.encoding = 'ISO-8859-1'

>>> r.encoding

'utf-8'

>>> r.encoding = 'ISO-8859-1'

如果你改变了编码，每当你访问 r.text ，Request 都将会使用 r.encoding 的新值。你可能希望在使用特殊逻辑计算出文本的编码的情况下来修改编码。比如 HTTP 和 XML 自身可以指定编码。这样的话，你应该使用 r.content 来找到编码，然后设置 r.encoding 为相应的编码。这样就能使用正确的编码解析 r.text 了。

在你需要的情况下，Requests 也可以使用定制的编码。如果你创建了自己的编码，并使用 codecs模块进行注册，你就可以轻松地使用这个解码器名称作为 r.encoding 的值，然后由 Requests 来为你处理编码。

二进制响应内容

你也能以字节的方式访问请求响应体，对于非文本请求：

>>> r.content
b'{...}'

1 2	>>> r.content b'{...}'

Requests 会自动为你解码 gzip 和 deflate 传输编码的响应数据。

例如，以请求返回的二进制数据创建一张图片，你可以使用如下代码：

>>> URL="http://img.taopic.com/uploads/allimg/120727/201995-120HG1030762.jpg"
>>> r = requests.get(URL)
>>> with open('/tmp/demo.jpg', 'wb') as fd:
        fd.write(r.content)

>>> URL="http://img.taopic.com/uploads/allimg/120727/201995-120HG1030762.jpg"

>>> r = requests.get(URL)

>>> with open('/tmp/demo.jpg', 'wb') as fd:

fd.write(r.content)

但一般情况下，你应该以下面的模式将文本流保存到文件：

URL="http://img.taopic.com/uploads/allimg/120727/201995-120HG1030762.jpg"
r = requests.get(URL, stream=True)
with open('/tmp/demo.jpg', 'wb') as fd:
    for chunk in r.iter_content(128):
        fd.write(chunk)

URL="http://img.taopic.com/uploads/allimg/120727/201995-120HG1030762.jpg"

r = requests.get(URL, stream=True)

with open('/tmp/demo.jpg', 'wb') as fd:

for chunk in r.iter_content(128):

fd.write(chunk)

这里推荐另外一种更好的方式，由于我们这个请求打开的是一个流传输，在这个请求中这个流会一直是打开的，可以调用r.cloese 手动关闭。当然也可以有更友好的方式，使用Python提供的管理上下文信息的contextlib语法糖，可自动close请求。

from requests
from contextlib import closing
URL="http://img.taopic.com/uploads/allimg/120727/201995-120HG1030762.jpg"
with closing(requests.get(URL, stream=True)) as r:
    with open('/tmp/demo.jpg', 'wb') as f:
        for chunk in r.iter_content(128):
            f.write(chunk)

from requests

from contextlib import closing

URL="http://img.taopic.com/uploads/allimg/120727/201995-120HG1030762.jpg"

with closing(requests.get(URL, stream=True)) as r:

with open('/tmp/demo.jpg', 'wb') as f:

for chunk in r.iter_content(128):

f.write(chunk)

JSON 响应内容

Requests 中也有一个内置的 JSON 解码器，助你处理 JSON 数据：

>>> r.json()

1	>>> r.json()

如果 JSON 解码失败， r.json() 就会抛出一个异常。例如，响应内容是 401 (Unauthorized)，尝试访问 r.json() 将会抛出 ValueError: No JSON object could be decoded 异常。

需要注意的是，成功调用 r.json() 并**不**意味着响应的成功。有的服务器会在失败的响应中包含一个 JSON 对象（比如 HTTP 500 的错误细节）。这种 JSON 会被解码返回。要检查请求是否成功，请使用 r.raise_for_status() 或者检查 r.status_code 是否和你的期望相同。

原始响应内容

在罕见的情况下，你可能想获取来自服务器的原始套接字响应，那么你可以访问 r.raw。如果你确实想这么干，那请你确保在初始请求中设置了 stream=True。具体你可以这么做：

>>> r = requests.get('http://httpbin.org/get', stream=True)
>>> r.raw
<urllib3.response.HTTPResponse object at 0x7f38e5cc56d8>
>>> r.raw.read(10)

>>> r = requests.get('http://httpbin.org/get', stream=True)

>>> r.raw

<urllib3.response.HTTPResponse object at 0x7f38e5cc56d8>

>>> r.raw.read(10)

但一般情况下，你应该以下面的模式将文本流保存到文件：

with open(filename, 'wb') as fd:
    for chunk in r.iter_content(chunk_size):
        fd.write(chunk)

with open(filename, 'wb') as fd:

for chunk in r.iter_content(chunk_size):

fd.write(chunk)

使用 Response.iter_content 将会处理大量你直接使用 Response.raw 不得不处理的。当下载时，上面是优先推荐的获取内容方式。 Note that chunk_size can be freely adjusted to a number that may better fit your use cases.

响应状态码

我们可以检测响应状态码：

>>> r = requests.get('http://httpbin.org/get')
>>> r.status_code
200
>>> r.reason
'OK'

>>> r = requests.get('http://httpbin.org/get')

>>> r.status_code

200

>>> r.reason

'OK'

为方便引用，Requests还附带了一个内置的状态码查询对象：

>>> r.status_code == requests.codes.ok
True

1 2	>>> r.status_code == requests.codes.ok True

如果发送了一个错误请求(一个 4XX 客户端错误，或者 5XX 服务器错误响应)，我们可以通过Response.raise_for_status() 来抛出异常：

>>> bad_r = requests.get('http://httpbin.org/status/404')
>>> bad_r.status_code
404

>>> bad_r.raise_for_status()
Traceback (most recent call last):
  File "requests/models.py", line 832, in raise_for_status
    raise http_error
requests.exceptions.HTTPError: 404 Client Error

>>> bad_r = requests.get('http://httpbin.org/status/404')

>>> bad_r.status_code

404

>>> bad_r.raise_for_status()

Traceback (most recent call last):

File "requests/models.py", line 832, in raise_for_status

raise http_error

requests.exceptions.HTTPError: 404 Client Error

但是，由于我们的例子中 r 的 status_code 是 200 ，当我们调用 raise_for_status() 时，得到的是：

>>> r.raise_for_status()
None

1 2	>>> r.raise_for_status() None

一切都挺和谐哈。

响应处理时间

>>> r = requests.get('http://httpbin.org/get')
>>> r.elapsed
datetime.timedelta(0, 0, 503655)

>>> r = requests.get('http://httpbin.org/get')

>>> r.elapsed

datetime.timedelta(0, 0, 503655)

重定向与请求历史

默认情况下，除了 HEAD, Requests 会自动处理所有重定向。

可以使用响应对象的 history 方法来追踪重定向。

Response.history 是一个 Response 对象的列表，为了完成请求而创建了这些对象。这个对象列表按照从最老到最近的请求进行排序。

例如，Github 将所有的 HTTP 请求重定向到 HTTPS：

>>> r = requests.get('http://github.com')
>>> r.url
'https://github.com/'
>>> r.status_code
200
>>> r.history
[<Response [301]>]

>>> r = requests.get('http://github.com')

>>> r.url

'https://github.com/'

>>> r.status_code

200

>>> r.history

[<Response [301]>]

如果你使用的是GET、OPTIONS、POST、PUT、PATCH 或者 DELETE，那么你可以通过 allow_redirects 参数禁用重定向处理：

>>> r = requests.get('http://github.com', allow_redirects=False)
>>> r.status_code
301
>>> r.history
[]

>>> r = requests.get('http://github.com', allow_redirects=False)

>>> r.status_code

301

>>> r.history

[]

如果你使用了 HEAD，你也可以启用重定向：

>>> r = requests.head('http://github.com', allow_redirects=True)
>>> r.url
'https://github.com/'
>>> r.history
[<Response [301]>]

>>> r = requests.head('http://github.com', allow_redirects=True)

>>> r.url

'https://github.com/'

>>> r.history

[<Response [301]>]

Cookie

如果某个响应中包含一些 cookie，你可以快速访问它们：

>>> url = 'http://example.com/some/cookie/setting/url'
>>> r = requests.get(url)

>>> r.cookies['example_cookie_name']
'example_cookie_value'

>>> url = 'http://example.com/some/cookie/setting/url'

>>> r = requests.get(url)

>>> r.cookies['example_cookie_name']

'example_cookie_value'

要想发送你的cookies到服务器，可以使用 cookies 参数：

>>> url = 'http://httpbin.org/cookies'
>>> cookies = dict(cookies_are='working')

>>> r = requests.get(url, cookies=cookies)
>>> r.text
'{"cookies": {"cookies_are": "working"}}'

>>> url = 'http://httpbin.org/cookies'

>>> cookies = dict(cookies_are='working')

>>> r = requests.get(url, cookies=cookies)

>>> r.text

'{"cookies": {"cookies_are": "working"}}'

Cookie 的返回对象为 RequestsCookieJar，它的行为和字典类似，但界面更为完整，适合跨域名跨路径使用。你还可以把 Cookie Jar 传到 Requests 中：

>>> jar = requests.cookies.RequestsCookieJar()
>>> jar.set('tasty_cookie', 'yum', domain='httpbin.org', path='/cookies')
>>> jar.set('gross_cookie', 'blech', domain='httpbin.org', path='/elsewhere')
>>> url = 'http://httpbin.org/cookies'
>>> r = requests.get(url, cookies=jar)
>>> r.text
'{"cookies": {"tasty_cookie": "yum"}}'

>>> jar = requests.cookies.RequestsCookieJar()

>>> jar.set('tasty_cookie', 'yum', domain='httpbin.org', path='/cookies')

>>> jar.set('gross_cookie', 'blech', domain='httpbin.org', path='/elsewhere')

>>> url = 'http://httpbin.org/cookies'

>>> r = requests.get(url, cookies=jar)

>>> r.text

'{"cookies": {"tasty_cookie": "yum"}}'

四、定制请求头

如果你想为请求添加 HTTP 头部，只要简单地传递一个 dict 给 headers 参数就可以了。

例如，在前一个示例中我们没有指定 content-type:

>>> url = 'https://developer.github.com/v3'
>>> headers = {'user-agent': 'my-app/0.0.1'}
>>> r = requests.get(url, headers=headers)

>>> url = 'https://developer.github.com/v3'

>>> headers = {'user-agent': 'my-app/0.0.1'}

>>> r = requests.get(url, headers=headers)

注意: 定制 header 的优先级低于某些特定的信息源，例如：

如果在 .netrc 中设置了用户认证信息，使用 headers= 设置的授权就不会生效。而如果设置了 auth= 参数，“.netrc“ 的设置就无效了。
如果被重定向到别的主机，授权 header 就会被删除。
代理授权 header 会被 URL 中提供的代理身份覆盖掉。
在我们能判断内容长度的情况下，header 的 Content-Length 会被改写。

更进一步讲，Requests 不会基于定制 header 的具体情况改变自己的行为。只不过在最后的请求中，所有的 header 信息都会被传递进去。

注意: 所有的 header 值必须是 string、bytestring 或者 unicode。尽管传递 unicode header 也是允许的，但不建议这样做。

五、POST 请求

通常给服务端发送数据，要不通过GET方法URL参数形式，要不通过POST方法表单形式。

通常，你想要发送一些编码为表单形式的数据——非常像一个 HTML 表单。要实现这个，只需简单地传递一个字典给 data 参数。

你的数据字典在发出请求时会自动编码为表单形式：

>>> payload = {'key1': 'value1', 'key2': 'value2'}

>>> r = requests.post("http://httpbin.org/post", data=payload)
>>> print(r.text)
{
  ...
  "form": {
    "key2": "value2",
    "key1": "value1"
  },
  ...
}

>>> payload = {'key1': 'value1', 'key2': 'value2'}

>>> r = requests.post("http://httpbin.org/post", data=payload)

>>> print(r.text)

{

...

"form": {

"key2": "value2",

"key1": "value1"

...

}

你可以看到 Content-Type 类型为 form

>>> r.request.headers
{'User-Agent': 'python-requests/2.22.0', 'Content-Type': 'application/x-www-form-urlencoded'}

1 2	>>> r.request.headers {'User-Agent': 'python-requests/2.22.0', 'Content-Type': 'application/x-www-form-urlencoded'}

你还可以为 data 参数传入一个元组列表。在表单中多个元素使用同一 key 的时候，这种方式尤其有效：

>>> payload = (('key1', 'value1'), ('key1', 'value2'))
>>> r = requests.post('http://httpbin.org/post', data=payload)
>>> print(r.text)
{
  ...
  "form": {
    "key1": [
      "value1",
      "value2"
    ]
  },
  ...
}

>>> payload = (('key1', 'value1'), ('key1', 'value2'))

>>> r = requests.post('http://httpbin.org/post', data=payload)

>>> print(r.text)

{

...

"form": {

"key1": [

"value1",

"value2"

]

...

}

很多时候你想要发送的数据并非编码为表单形式的。如果你传递一个 string 而不是一个 dict，那么数据会被直接发布出去。

例如，Github API v3 接受编码为 JSON 的 POST/PATCH 数据：

>>> import json

>>> url = 'https://api.github.com/some/endpoint'
>>> payload = {'some': 'data'}

>>> r = requests.post(url, data=json.dumps(payload))

>>> import json

>>> url = 'https://api.github.com/some/endpoint'

>>> payload = {'some': 'data'}

>>> r = requests.post(url, data=json.dumps(payload))

其默认 Content-Type 类型为 text/plain。此方式可能大部分网站都不支持，需要手动添加 headers，指定 Content-Type 为 application/json 类型。

此处除了可以自行对 dict 进行编码，你还可以使用 json 参数直接传递，然后它就会被自动编码。这是 2.4.2 版的新加功能。

>>> url = 'https://api.github.com/some/endpoint'
>>> payload = {'some': 'data'}

>>> r = requests.post(url, json=payload)

>>> url = 'https://api.github.com/some/endpoint'

>>> payload = {'some': 'data'}

>>> r = requests.post(url, json=payload)

此时，你可以看到 Content-Type 类型为 application/json

>>> r.request.headers
{'User-Agent': 'python-requests/2.22.0', 'Content-Type': 'application/json'}

1 2	>>> r.request.headers {'User-Agent': 'python-requests/2.22.0', 'Content-Type': 'application/json'}

特别注意不同传递方式的情况下，其默认 Content-Type 的不同，需要正确的 Content-Type 对应正确的数据类型才能更好地工作。

六、超时处理

你可以告诉 requests 在经过以 timeout 参数设定的秒数时间之后停止等待响应。基本上所有的生产代码都应该使用这一参数。如果不使用，你的程序可能会永远失去响应：

>>> requests.get('https://api.github.com/users', timeout=0.001)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
requests.exceptions.Timeout: HTTPConnectionPool(host='github.com', port=80): Request timed out. (timeout=0.001)

>>> requests.get('https://api.github.com/users', timeout=0.001)

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

requests.exceptions.Timeout: HTTPConnectionPool(host='github.com', port=80): Request timed out. (timeout=0.001)

注意

timeout 仅对连接过程有效，与响应体的下载无关。 timeout 并不是整个下载响应的时间限制，而是如果服务器在 timeout 秒内没有应答，将会引发一个异常（更精确地说，是在 timeout 秒内没有从基础套接字上接收到任何字节的数据时）If no timeout is specified explicitly, requests do not time out.

七、错误与异常

当我们在调用任何第三方服务时都应该考虑到对方不是100%稳定的，因此就要做异常的处理。requests库提供了一个exceptions包把常见的异常都定义出来了。比如：

遇到网络问题（如：DNS 查询失败、拒绝连接等）时，Requests 会抛出一个 ConnectionError 异常。
如果 HTTP 请求返回了不成功的状态码， Response.raise_for_status() 会抛出一个 HTTPError 异常。
若请求超时，则抛出一个 Timeout 异常。
若请求超过了设定的最大重定向次数，则会抛出一个 TooManyRedirects 异常。

所有Requests显式抛出的异常都继承自 requests.exceptions.RequestException。

import requests
from requests import exceptions

try:
    r = requests.get('https://api.github.com/users', timeout=0.1)
except exceptions.Timeout as e:
    print(e)
else:
    print(r.text)

import requests

from requests import exceptions

try:

r = requests.get('https://api.github.com/users', timeout=0.1)

except exceptions.Timeout as e:

print(e)

else:

print(r.text)

八、 GitHub REST API v3操作实例

下面我们以Github Rest API v3为例，简单使用一下Requests库。

Github API文档：https://developer.github.com/v3/

Github API列表：https://api.github.com/

所有API访问都通过HTTPS访问，并通过HTTPS访问https://api.github.com。所有数据都以JSON形式发送和接收。

用户API

我们以用户API为例，用户API上的许多资源提供了获取有关当前经过身份验证的用户信息的快捷方式。如果请求URL不包含:username参数，则响应将针对登录用户（并且你必须在请求中传递认证信息）。

获取简单用户信息

GET /users/:username

1	GET /users/:username

响应内容属于公开信息。

代码示例：

>>> URL = "https://api.github.com/users/imoocdemo"
>>> r = requests.get(URL)
>>> r.text

>>> URL = "https://api.github.com/users/imoocdemo"

>>> r = requests.get(URL)

>>> r.text

结果如下：

{
    "hireable": true,
    "site_admin": false,
    "public_repos": 1,
    "received_events_url": "https://api.github.com/users/imoocdemo/received_events",
    "updated_at": "2018-03-06T13:00:30Z",
    "public_gists": 0,
    "blog": "https://github.com/blog123456",
    "avatar_url": "https://avatars0.githubusercontent.com/u/20262371?v=4",
    "id": 20262371,
    "location": "aufe-xx",
    "followers": 1,
    "name": "Tshen5",
    "starred_url": "https://api.github.com/users/imoocdemo/starred{/owner}{/repo}",
    "repos_url": "https://api.github.com/users/imoocdemo/repos",
    "gists_url": "https://api.github.com/users/imoocdemo/gists{/gist_id}",
    "subscriptions_url": "https://api.github.com/users/imoocdemo/subscriptions",
    "login": "imoocdemo",
    "gravatar_id": "",
    "company": "imooc\u516c\u53f8",
    "type": "User",
    "following_url": "https://api.github.com/users/imoocdemo/following{/other_user}",
    "following": 1,
    "events_url": "https://api.github.com/users/imoocdemo/events{/privacy}",
    "organizations_url": "https://api.github.com/users/imoocdemo/orgs",
    "bio": "123@qq.com",
    "created_at": "2016-07-03T03:12:42Z",
    "html_url": "https://github.com/imoocdemo",
    "url": "https://api.github.com/users/imoocdemo",
    "email": null,
    "followers_url": "https://api.github.com/users/imoocdemo/followers"
}

{

"hireable": true,

"site_admin": false,

"public_repos": 1,

"received_events_url": "https://api.github.com/users/imoocdemo/received_events",

"updated_at": "2018-03-06T13:00:30Z",

"public_gists": 0,

"blog": "https://github.com/blog123456",

"avatar_url": "https://avatars0.githubusercontent.com/u/20262371?v=4",

"id": 20262371,

"location": "aufe-xx",

"followers": 1,

"name": "Tshen5",

"starred_url": "https://api.github.com/users/imoocdemo/starred{/owner}{/repo}",

"repos_url": "https://api.github.com/users/imoocdemo/repos",

"gists_url": "https://api.github.com/users/imoocdemo/gists{/gist_id}",

"subscriptions_url": "https://api.github.com/users/imoocdemo/subscriptions",

"login": "imoocdemo",

"gravatar_id": "",

"company": "imooc\u516c\u53f8",

"type": "User",

"following_url": "https://api.github.com/users/imoocdemo/following{/other_user}",

"following": 1,

"events_url": "https://api.github.com/users/imoocdemo/events{/privacy}",

"organizations_url": "https://api.github.com/users/imoocdemo/orgs",

"bio": "123@qq.com",

"created_at": "2016-07-03T03:12:42Z",

"html_url": "https://github.com/imoocdemo",

"url": "https://api.github.com/users/imoocdemo",

"email": null,

"followers_url": "https://api.github.com/users/imoocdemo/followers"

}

获取所有用户信息

GET /users

1	GET /users

按照他们在GitHub上注册的顺序列出所有用户，该列表包括个人用户帐户和组织帐户。提供since参数分页，可以指定从某个ID号之后开始查看。

代码示例：

>>> URL = "https://api.github.com/users"
>>> r = requests.get(URL, params={'since':100})
>>> r.text

>>> URL = "https://api.github.com/users"

>>> r = requests.get(URL, params={'since':100})

>>> r.text

获取经过认证的用户信息

GET /user

GET /user

代码示例：

>>> URL = "https://api.github.com/users/imoocdemo"
>>> r = requests.get(URL, auth=('imoocdemo', 'imoocdemo123'))
>>> r.text

>>> URL = "https://api.github.com/users/imoocdemo"

>>> r = requests.get(URL, auth=('imoocdemo', 'imoocdemo123'))

>>> r.text

响应内容属于公开和私有信息，当通过基本身份验证或OAuth与user范围进行身份验证后。上面是Github提供的一种简单的验证方式，当然很不安全。

{
    "starred_url": "https://api.github.com/users/imoocdemo/starred{/owner}{/repo}",
    "public_gists": 0,
    "events_url": "https://api.github.com/users/imoocdemo/events{/privacy}",
    "id": 20262371,
    "login": "imoocdemo",
    "type": "User",
    "private_gists": 1,
    "received_events_url": "https://api.github.com/users/imoocdemo/received_events",
    "two_factor_authentication": false,
    "blog": "https://github.com/blog123456",
    "gravatar_id": "",
    "public_repos": 1,
    "owned_private_repos": 0,
    "followers": 1,
    "following_url": "https://api.github.com/users/imoocdemo/following{/other_user}",
    "plan": {
        "collaborators": 0,
        "name": "free",
        "private_repos": 0,
        "space": 976562499
    },
    "avatar_url": "https://avatars0.githubusercontent.com/u/20262371?v=4",
    "hireable": true,
    "url": "https://api.github.com/users/imoocdemo",
    "email": null,
    "updated_at": "2018-03-06T13:00:30Z",
    "bio": "123@qq.com",
    "html_url": "https://github.com/imoocdemo",
    "followers_url": "https://api.github.com/users/imoocdemo/followers",
    "repos_url": "https://api.github.com/users/imoocdemo/repos",
    "location": "aufe-xx",
    "collaborators": 0,
    "following": 1,
    "total_private_repos": 0,
    "organizations_url": "https://api.github.com/users/imoocdemo/orgs",
    "disk_usage": 0,
    "name": "Tshen5",
    "site_admin": false,
    "gists_url": "https://api.github.com/users/imoocdemo/gists{/gist_id}",
    "subscriptions_url": "https://api.github.com/users/imoocdemo/subscriptions",
    "created_at": "2016-07-03T03:12:42Z",
    "company": "imooc\u516c\u53f8"
}

{

"starred_url": "https://api.github.com/users/imoocdemo/starred{/owner}{/repo}",

"public_gists": 0,

"events_url": "https://api.github.com/users/imoocdemo/events{/privacy}",

"id": 20262371,

"login": "imoocdemo",

"type": "User",

"private_gists": 1,

"received_events_url": "https://api.github.com/users/imoocdemo/received_events",

"two_factor_authentication": false,

"blog": "https://github.com/blog123456",

"gravatar_id": "",

"public_repos": 1,

"owned_private_repos": 0,

"followers": 1,

"following_url": "https://api.github.com/users/imoocdemo/following{/other_user}",

"plan": {

"collaborators": 0,

"name": "free",

"private_repos": 0,

"space": 976562499

"avatar_url": "https://avatars0.githubusercontent.com/u/20262371?v=4",

"hireable": true,

"url": "https://api.github.com/users/imoocdemo",

"email": null,

"updated_at": "2018-03-06T13:00:30Z",

"bio": "123@qq.com",

"html_url": "https://github.com/imoocdemo",

"followers_url": "https://api.github.com/users/imoocdemo/followers",

"repos_url": "https://api.github.com/users/imoocdemo/repos",

"location": "aufe-xx",

"collaborators": 0,

"following": 1,

"total_private_repos": 0,

"organizations_url": "https://api.github.com/users/imoocdemo/orgs",

"disk_usage": 0,

"name": "Tshen5",

"site_admin": false,

"gists_url": "https://api.github.com/users/imoocdemo/gists{/gist_id}",

"subscriptions_url": "https://api.github.com/users/imoocdemo/subscriptions",

"created_at": "2016-07-03T03:12:42Z",

"company": "imooc\u516c\u53f8"

}

更新经过身份验证的用户

PATCH /user

1	PATCH /user

参数

名称	类型	描述
name	string	用户的新名称。
email	string	用户的公开可见的电子邮件地址。
blog	string	用户的新博客URL。
company	string	用户的新公司。
location	string	用户的新位置。
hireable	string	用户的新用户可用性。
bio	string	用户的新简历。

代码示例：

>>> URL = "https://api.github.com/user"
>>> r = requests.patch(URL, auth=('imoocdemo', 'imoocdemo123'), json={'name': 'dkey'})
>>> r.request.header

>>> URL = "https://api.github.com/user"

>>> r = requests.patch(URL, auth=('imoocdemo', 'imoocdemo123'), json={'name': 'dkey'})

>>> r.request.header

看一下请求和响应信息：

# 请求信息;
>>> r.request.body
b'{"name": "dkey"}'
>>> r.request.headers
{'User-Agent': 'python-requests/2.18.4', 'Accept': '*/*', 'Accept-Encoding': 'gzip, .....}
>>> r.request.url
'https://api.github.com/user'
>>> r.request.method
'PATCH'

# 响应信息;
>>> r.status_code
200
>>> r.elapsed
datetime.timedelta(0, 1, 205809)

# 请求信息;

>>> r.request.body

b'{"name": "dkey"}'

>>> r.request.headers

{'User-Agent': 'python-requests/2.18.4', 'Accept': '*/*', 'Accept-Encoding': 'gzip, .....}

>>> r.request.url

'https://api.github.com/user'

>>> r.request.method

'PATCH'

# 响应信息;

>>> r.status_code

200

>>> r.elapsed

datetime.timedelta(0, 1, 205809)

获取用户邮箱信息

GET /user/emails

1	GET /user/emails

代码示例：

>>> URL = "https://api.github.com/user/emails"
>>> r = requests.get(URL, auth=('imoocdemo', 'imoocdemo123'))
>>> r.text

>>> URL = "https://api.github.com/user/emails"

>>> r = requests.get(URL, auth=('imoocdemo', 'imoocdemo123'))

>>> r.text

返回信息：

[
    {
        "email": "hello-world@imooc.org",
        "primary": true,
        "visibility": "private",
        "verified": false
    }
]

[

{

"email": "hello-world@imooc.org",

"primary": true,

"visibility": "private",

"verified": false

}

]

获取用户公开邮箱

GET /user/public_emails

1	GET /user/public_emails

代码示例：

>>> URL = "https://api.github.com/user/public_emails"
>>> r = requests.get(URL, auth=('imoocdemo', 'imoocdemo123'))
>>> r.text

>>> URL = "https://api.github.com/user/public_emails"

>>> r = requests.get(URL, auth=('imoocdemo', 'imoocdemo123'))

>>> r.text

增加用户邮箱信息

POST /user/emails

1	POST /user/emails

示例代码：

>>> URL = "https://api.github.com/user/emails"
>>> r = requests.post(URL, auth=('imoocdemo', 'imoocdemo123'), json=["dkey@github.com"])
>>> r.text

>>> URL = "https://api.github.com/user/emails"

>>> r = requests.post(URL, auth=('imoocdemo', 'imoocdemo123'), json=["dkey@github.com"])

>>> r.text

删除用户邮箱信息

DELETE /user/emails

1	DELETE /user/emails

示例代码：

>>> URL = "https://api.github.com/user/emails"
>>> r = requests.delete(URL, auth=('imoocdemo', 'imoocdemo123'), json=["dkey@github.com"])
>>> r.text

>>> URL = "https://api.github.com/user/emails"

>>> r = requests.delete(URL, auth=('imoocdemo', 'imoocdemo123'), json=["dkey@github.com"])

>>> r.text

切换电子邮件可见

PATCH /user/email/visibility

1	PATCH /user/email/visibility

示例代码：

>>> URL = "https://api.github.com/user/email/visibility"     
>>> r = requests.patch(URL, auth=('imoocdemo', 'imoocdemo123'))      
>>> r.text
'[{"email":"hello-world@imooc.org","primary":true,"verified":false,"visibility":"public"}]'

>>> URL = "https://api.github.com/user/email/visibility"

>>> r = requests.patch(URL, auth=('imoocdemo', 'imoocdemo123'))

>>> r.text

'[{"email":"hello-world@imooc.org","primary":true,"verified":false,"visibility":"public"}]'

超时与异常处理

我们还是以用户邮箱API为例。

import requests
from requests import exceptions

try:
    r = requests.get('https://api.github.com/user/emails', timeout=0.1)
except exceptions.Timeout as e:
    print(e)
else:
    print(r.text)

import requests

from requests import exceptions

try:

r = requests.get('https://api.github.com/user/emails', timeout=0.1)

except exceptions.Timeout as e:

print(e)

else:

print(r.text)

此段代码的意思就是如果有 Timeout 异常就打印出来，如果没有就把response信息打印出来。正常情况下如果把timeout值调大，执行此段代码应该会抛出需要认证的错误：{“message”:”Requires authentication”,”documentation_url”:”https://developer.github.com/v3/users/emails/#list-email-addresses-for-a-user”}。

这个时候就可以再加一个 HTTP 异常捕获，另外可以通过Response.raise_for_status() 来抛出异常：

import requests
from requests import exceptions

try:
    r = requests.get('https://api.github.com/user/emails', timeout=1)
    r.raise_for_status()
except exceptions.Timeout as e:
    print(e)
except exceptions.HTTPError as e:
    print(e)
else:
    print(r.text)

import requests

from requests import exceptions

try:

r = requests.get('https://api.github.com/user/emails', timeout=1)

r.raise_for_status()

except exceptions.Timeout as e:

print(e)

except exceptions.HTTPError as e:

print(e)

else:

print(r.text)

由于我们没有添加认证信息，所以会抛出此异常：401 Client Error: Unauthorized for url: https://api.github.com/user/emails。

Session 对象

会话对象让你能够跨请求保持某些参数，它也会在同一个 Session 实例发出的所有请求之间保持 cookie，期间使用 urllib3 的 connection pooling 功能。所以如果你向同一主机发送多个请求，底层的 TCP 连接将会被重用，从而带来显著的性能提升。

import requests
from requests import Request, Session

s = Session()
headers = {'User-Agent': 'fake 1.0'}
r = Request('GET', 'https://api.github.com/users', headers=headers)
prepped = r.prepare()
print(prepped.body)

r = s.send(prepped, timeout=5)
r.test

import requests

from requests import Request, Session

s = Session()

headers = {'User-Agent': 'fake 1.0'}

r = Request('GET', 'https://api.github.com/users', headers=headers)

prepped = r.prepare()

print(prepped.body)

r = s.send(prepped, timeout=5)

r.test

事件钩子

事件钩子（event hooks）在程序届特别流行，比如说如果你用Gitlab或Github的话有很多钩子函数，比如说当你去push一个库的时候它会自动去触发的一些动作，这些钩子属于事件驱动型开发，它可以改变我们的编程思路。还有比如说JavaScript中它的很多开发模式都是基于回调的，这种回调就是事件完成之后触发的一些动作。这种编程方式比我们使用线性编程在某些情况下会灵活很多。

Requests有一个钩子系统，你可以用来操控部分请求过程或信号事件处理。你可以通过传递一个 {hook_name: callback_function} 字典给 hooks 请求参数为每个请求分配一个钩子函数：

hooks=dict(response=get_info)

1	hooks=dict(response=get_info)

callback_function 会接受一个数据块作为它的第一个参数。

def get_info(r, *args, **kwargs):
    '''
    callback function
    '''
    print(r.headers['Content-Type'])

def get_info(r, *args, **kwargs):

'''

callback function

'''

print(r.headers['Content-Type'])

若执行你的回调函数期间发生错误，系统会给出一个警告。

若回调函数返回一个值，默认以该值替换传进来的数据。若函数未返回任何东西，也没有什么其他的影响。

>>> requests.get('https://api.github.com/users', hooks=dict(response=get_info)) 
application/json; charset=utf-8
<Response [200]>

>>> requests.get('https://api.github.com/users', hooks=dict(response=get_info))

application/json; charset=utf-8

HTTP 与 OAUTH 认证

我们知道一个基本的 HTTP 认证流程如下：

我们前面验证 Github 使用的 auth=(‘imoocdemo’, ‘imoocdemo123’) 其实就是这种基本验证方式。这种方式有什么问题呢？

>>> URL = "https://api.github.com/user/emails"
>>> r = requests.get(URL, auth=('imoocdemo', 'imoocdemo123'))
>>> r.request.headers
{'Accept-Encoding': 'gzip, deflate', 'User-Agent': 'python-requests/2.18.4', 'Authorization': 'Basic aW1vb2NkZW1vOmltb29jZGVtbzEyMw==', 'Accept': '*/*', 'Connection': 'keep-alive'}

>>> URL = "https://api.github.com/user/emails"

>>> r = requests.get(URL, auth=('imoocdemo', 'imoocdemo123'))

>>> r.request.headers

{'Accept-Encoding': 'gzip, deflate', 'User-Agent': 'python-requests/2.18.4', 'Authorization': 'Basic aW1vb2NkZW1vOmltb29jZGVtbzEyMw==', 'Accept': '*/*', 'Connection': 'keep-alive'}

可以看到在 request.headers 中有认证信息，显示的是一个 basic 认证，其字符串是通过 base64 编码的。

>>> import base64
>>> base64.b64decode('aW1vb2NkZW1vOmltb29jZGVtbzEyMw==')
b'imoocdemo:imoocdemo123'

>>> import base64

>>> base64.b64decode('aW1vb2NkZW1vOmltb29jZGVtbzEyMw==')

b'imoocdemo:imoocdemo123'

可以发现一解码就出来了。

可以发现使用用户名/密码方式认证，在安全性上有待商榷。所以现在基本主流网站都提供 OAUTH 认证（就是我们经常使用的第三方登录），Github 也不例外。OAUTH 协议为用户资源的授权提供了一个安全的、开放而又简易的标准。与以往的授权方式不同之处是 OAUTH 的授权不会使第三方触及到用户的帐号信息（如用户名与密码），即第三方无需使用用户的用户名与密码就可以申请获得该用户资源的授权，因此 OAUTH 是安全的。OAuth 是 Open Authorization 的简写。目前基本都是使用 OAUTH 2.0 标准。

具体 OAuth 认证流程是怎么样的？以及如何使用 Github OAuth 进行认证，可以看官方文档。如果只是简单验证，可以到 Github 个人中心：Settings/Developer settings/Personal access tokens 页面生成一个个人访问 token。其认证方式如下：

>>> URL = "https://api.github.com/user/emails"               
>>> headers = {"Authorization": "token effc40aa193fde4626f857fd274dfd646a724b"}
>>> r = requests.get(URL, headers=headers)
>>> r.request.headers
{'Accept-Encoding': 'gzip, deflate', 'User-Agent': 'python-requests/2.18.4', 'Authorization': 'token effc40aa193fde4626f857fd274dfd646a724b', 'Accept': '*/*', 'Connection': 'keep-alive'}

>>> URL = "https://api.github.com/user/emails"

>>> headers = {"Authorization": "token effc40aa193fde4626f857fd274dfd646a724b"}

>>> r = requests.get(URL, headers=headers)

>>> r.request.headers

{'Accept-Encoding': 'gzip, deflate', 'User-Agent': 'python-requests/2.18.4', 'Authorization': 'token effc40aa193fde4626f857fd274dfd646a724b', 'Accept': '*/*', 'Connection': 'keep-alive'}

可以看出我们这里是硬编码的方式，其实 requests 还给我们提供了一个更友好的方式：

from requests.auth import AuthBase
class GithubAuth(AuthBase):
    def __init__(self, token):
        self.token = token
    
    def __call__(self, r):
        r.headers['Authorization'] = ' '.join(['token', self.token])
        return r

from requests.auth import AuthBase

class GithubAuth(AuthBase):

def __init__(self, token):

self.token = token

def __call__(self, r):

r.headers['Authorization'] = ' '.join(['token', self.token])

return r

然后就可以这么调用了：

auth = GithubAuth('effc40aa193fde4626f857fd274dfd646a724b')
r = requests.get(URL, auth=auth)

1 2	auth = GithubAuth('effc40aa193fde4626f857fd274dfd646a724b') r = requests.get(URL, auth=auth)

<扩展>

OAuth2授权

简述OAuth 2.0的运作流程（Github）

如果您觉得本站对你有帮助，那么可以支付宝扫码捐助以帮助本站更好地发展，在此谢过。

您必须 登录 才能发表评论！

您必须登录才能发表评论！