# 安装

利用 pip 安装Requests非常简单

pip install requests

还是使 easy_install 安装

easy_install requests

# 获得源码

Requests 一直当Github上让积极的开发在

而可仿造公共版本库:

git clone git://github.com/kennethreitz/requests.git

下载 源码:

curl -OL https://github.com/kennethreitz/requests/tarball/master

还是下载 zipball:

curl -OL https://github.com/kennethreitz/requests/zipball/master

只要你抱了副本,你虽好轻松的拿其放到至你的python包里或者安装至公的site-packages:

python setup.py install

# 快速达标亲手


## 发送请求

动用Requests发送网络要非常简单。

一如既往开始如导入Requests模块:

>>> import requests

下一场,尝试取有网页。本例子中,我们来取Github的共用时间线

>>> r = requests.get('https://github.com/timeline.json')

而今,我们发出一个曰吧 r 的 Response
对象。可以自之目标中赢得具有我们纪念要的信。

Requests简便的API意味着所有HTTP请求类型且是举世瞩目的。例如,你可以这样发送一个HTTP
POST请求:

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

美妙,对吧?那么其他HTTP请求类型:PUT, DELETE,
HEAD以及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/get")

都充分科学吧,但当下为才是Requests的冰山一角呢。


## 为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)

经打印输出该URL,你可知观看URL已于正确编码:

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

瞩目字典里值为 None 的键都无见面给补充加至 URL 的询问字符串里。


## 响应内容

咱俩能够读取服务器响应的情节。再次因Github时间线为条例:

>>> import requests
>>> r = requests.get('https://github.com/timeline.json')
>>> r.text
u'[{"repository":{"open_issues":0,"url":"https://github.com/...

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

要发出后,Requests会依据HTTP头部对响应的编码作出有根据的推测。当你拜访
r.text
之常,Requests会采取其想的文件编码。你可搜索出Requests使用了啊编码,并且能够使
r.encoding 属性来改其:

>>> 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'[{"repository":{"open_issues":0,"url":"https://github.com/...

Requests会活动为您解码 gzipdeflate 传输编码的响应数据。

诸如,以求返回的二进制数据创建同摆图纸,你可行使如下代码:

>>> from PIL import Image
>>> from StringIO import StringIO
>>> i = Image.open(StringIO(r.content))

## JSON响应内容

Requests中也发一个措的JSON解码器,助你处理JSON数据:

>>> import requests
>>> r = requests.get('https://github.com/timeline.json')
>>> r.json()
[{u'repository': {u'open_issues': 0, u'url': 'https://github.com/...

假若JSON解码失败, r.json 就会丢来一个要命。例如,相应内容是 401
(Unauthorized) ,尝试看 r.json 将会见废弃来 ValueError: No JSON object
could be decoded 异常。


## 原始响应内容

在层层的动静下而也许想博得来自服务器的原始套接字响应,那么您得看
r.raw 。 如果你真想然干,那请你保证在始发请求被设置了
stream=True 。具体的公可如此做:

>>> r = requests.get('https://github.com/timeline.json', stream=True)
>>> r.raw
<requests.packages.urllib3.response.HTTPResponse object at 0x101194810>
>>> r.raw.read(10)
'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03'

然而一般情形下,你当以下面的模式将文本流保存及文件:

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

使用 Response.iter_content 将见面处理大量君一直动用 Response.raw
不得不处理的。 当流下载时,上面是预先推荐的获内容措施。


## 定制请求头

只要您想吧要添加HTTP头部,只要简单地传递一个 dict 给 headers
参数就好了。

如,在前方一个演示中我们从未点名content-type:

>>> import json
>>> url = 'https://api.github.com/some/endpoint'
>>> payload = {'some': 'data'}
>>> headers = {'content-type': 'application/json'}

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

## 更加扑朔迷离的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"
  },
  ...
}

森辰光你想要发送的数毫无编码为表单形式的。如果您传递一个 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))

## POST一个多一些编码(Multipart-Encoded)的文件

Requests使得上传多部分编码文件变得不可开交简短:

>>> url = 'http://httpbin.org/post'
>>> files = {'file': open('report.xls', 'rb')}

>>> r = requests.post(url, files=files)
>>> r.text
{
  ...
  "files": {
    "file": "<censored...binary...data>"
  },
  ...
}

公可显式地安装文件称,文件类型和请求头:

>>> url = 'http://httpbin.org/post'
>>> files = {'file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel', {'Expires': '0'})}

>>> r = requests.post(url, files=files)
>>> r.text
{
  ...
  "files": {
    "file": "<censored...binary...data>"
  },
  ...
}

如若您想,你吧足以发送作为文件来接过的字符串:

>>> url = 'http://httpbin.org/post'
>>> files = {'file': ('report.csv', 'some,data,to,send\nanother,row,to,send\n')}

>>> r = requests.post(url, files=files)
>>> r.text
{
  ...
  "files": {
    "file": "some,data,to,send\\nanother,row,to,send\\n"
  },
  ...
}

假如您发送一个充分很的文本作为 multipart/form-data
请求,你也许要流请求(?)。默认下 requests 不支持, 但有个第三方担保支持 –
requests-toolbelt. 你得看 toolbelt 文档 来询问下办法。

每当一个请求被发送多文件参考 高级用法 一节.


## 响应状态码

咱们得检测响应状态码:

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

为利引用,Requests还附带了一个搭的状态码查询对象:

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

而发送了一个败请求(非200应),我们得经
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

然,由于我们的例子中 r 的 status_code 是 200 ,当我们调用
raise_for_status() 时,得到的是:

>>> r.raise_for_status()
None

总体都深和谐哈。


## 响应头

我们可以翻以一个Python字典形式显得的服务器响应头:

>>> r.headers
{
    'content-encoding': 'gzip',
    'transfer-encoding': 'chunked',
    'connection': 'close',
    'server': 'nginx/1.0.4',
    'x-runtime': '148ms',
    'etag': '"e1ca502697e5c9317743dc078f67693f"',
    'content-type': 'application/json'
}

不过这个字典比较独特:它是独为HTTP头部而特别之。根据 RFC 2616 ,
HTTP头部是深浅写不灵活的。

据此,我们得下任意大写形式来聘这些应头字段:

>>> r.headers['Content-Type']
'application/json'

>>> r.headers.get('content-type')
'application/json'

## Cookies

若是某个响应中蕴藏有Cookie,你得快速访问它们:

>>> 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"}}'

## 重定向与请求历史

默认情况下,除了 HEAD, Requests会活动处理所有又定向。

好以应对象的 history 方法来追踪重定向。

Response.history 是一个:class:Response<requests.Response>
对象的列表,为了成功请求而创立了这些目标。这个目标列表按照自太总到近来底要进行排序。

譬如说,Github将享有的HTTP请求重定向到HTTPS。:

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

假若你使用的凡GET, OPTIONS, POSTjson, PUT, PATCH 或者
DELETE,,那么你可由此 allow_redirects 参数禁用重定向处理:

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

## 超时

君得告知requests在经过以 timeout 参数设定的秒数时间后休等待响应:

>>> requests.get('http://github.com', 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秒内没从基础套接字上收取至其它字节的多寡时)


## 错误和老

遇见网络问题(如:DNS查询失败、拒绝连接等)时,Requests会丢弃来一个
ConnectionError 异常。

赶上罕见的失效HTTP响应时,Requests则会扔来一个 HTTPError 异常。

设若要过,则弃来一个 Timeout 异常。

假如要过了设定的最特别重定向次数,则会废弃来一个 TooManyRedirects
异常。

所有Requests显式抛出的雅且继承自
requests.exceptions.RequestException

相关文章

网站地图xml地图